Skip to main content

Database and Migration Guidelines

Database Setup​

  • Database setup MUST be centralized under database/.
  • Startup SHOULD include bounded retry/backoff.
  • SQL logging SHOULD be config-driven.

Transactions​

  • Multi-step writes MUST use explicit transactions.
  • Critical counters/balances SHOULD use row-level locking when needed.
  • Transactions MUST be short and deterministic.
  • External network calls MUST NOT run inside open transactions.

Query Hygiene​

  • N+1 query patterns SHOULD be avoided.
  • Unbounded lists MUST be paginated.
  • Frequently filtered/sorted fields SHOULD be indexed.
  • Large payload queries SHOULD use select/projection.

Migration Strategy​

  • Production schema changes MUST use SQL migrations (golang-migrate).
  • Every migration SHOULD include both up and down files.
  • Naming MUST follow one consistent style (timestamped or sequential).
  • If multi-tenant schemas are used, keep public and tenant migrations separated.