Database Migrations

Atlas (Ariga) manages database schema migrations with integrity verification.

Source of Truth

File	Role	Editable?
backend/src/db/schema.ts	Schema definition (Drizzle ORM)	YES — edit this only
backend/atlas/migrations/*.sql	Generated SQL migrations	NEVER edit
backend/atlas/atlas.sum	Merkle hash integrity file	NEVER edit

Migration Workflow

1. Edit backend/src/db/schema.ts
2. Run make db-generate NAME=description (see Makefile Commands)
3. Verify generated SQL in backend/atlas/migrations/
4. Commit both the migration file and atlas.sum

Atlas uses an ephemeral dev database (atlas_dev on the Docker Compose Postgres) to compute schema diffs.

Current Migrations

Migration	Size	Content
20260326170903_baseline.sql	204KB	Full baseline schema
20260327_hubspot_sync_fields.sql	—	HubSpot sync metadata
20260328_enum_mappings.sql	—	Enum mapping tables
20260401_workflow_engine.sql	188KB	Workflow engine schema
20260405_product_sync.sql	—	HubSpot product sync
20260410_quote_line_item_sync.sql	—	Quote and line item sync

Squash migrations within a PR. Name them descriptively via the NAME parameter.

Validation

• Local: make db-validate or atlas migrate validate
• CI: migration-tests.yml checks syntax, ordering, and destructive operations (see CI-CD Workflows)
• atlas.sum prevents tampering — any manual edit to migration files is detected

Deployment Strategy

Environment	Method	Connection
Local / Test	Container startup	Standard DATABASE_URL
Cloud (dev/staging/prod)	Fly.io release_command	DATABASE_URL_MIGRATION (migration-user, direct)

The migration-user has schema_admin privileges for DDL operations. The app-user (via PgBouncer) handles runtime queries. See Database Architecture for connection details.

Key Files

• backend/src/db/schema.ts
• backend/atlas/migrations/
• backend/atlas/atlas.sum
• .github/workflows/migration-tests.yml

See Also

• Database Architecture — PostgreSQL setup and connection pooling
• Database Seeding — populating data after migrations
• Makefile Commands — make db-generate, make db-validate
• CI-CD Workflows — automated migration testing