Skip to content

DATABASE.md

Latest commit

 

History

History
79 lines (52 loc) · 2.43 KB

DATABASE.md

File metadata and controls

79 lines (52 loc) · 2.43 KB

Database - Drizzle ORM

Schema: api/src/db/schema.ts Migrations: api/drizzle/ Config: api/drizzle.config.ts

Commands

pnpm db:push              # Push schema directly to local DB (dev only)
pnpm db:generate          # Generate a migration file from schema changes
pnpm db:migrate           # Apply migration files to database (dev)
pnpm db:studio            # Open Drizzle Studio at https://local.drizzle.studio

Development Workflow

Use db:push to experiment freely, then db:generate once you're happy with the result.

1. Experiment with db:push

db:push syncs your schema.ts directly to your local database — no migration files, no history.

# Edit schema.ts, then push
pnpm db:push

2. Finalize with db:generate

Once the schema is final, generate a migration:

pnpm db:generate
# or with a custom name:
pnpm db:generate -- --name add-user-roles

This diffs schema.ts against the last snapshot and creates one clean SQL file with only the net changes.

3. Review and commit

cat api/drizzle/0001_*.sql
git add api/drizzle/
git commit -m "migration: add project description column"

After db:generate, you do NOT need to run db:migrate locally — your database is already up to date from db:push. The migration file is for production and fresh setups.

Undoing a generated migration

If you generated a migration you don't want (before deploying):

  1. Delete the SQL file (e.g., api/drizzle/0001_*.sql)
  2. Delete its snapshot (e.g., api/drizzle/meta/0001_snapshot.json)
  3. Remove its entry from api/drizzle/meta/_journal.json

Resetting your local database

docker compose down -v          # removes postgres volume
docker compose up postgres -d   # fresh database
pnpm db:push                    # apply current schema

Production

Migrations run automatically at container startup via node dist/migrate.js && node dist/index.js. If migrations fail, the server won't start.

The migrator reads SQL files from api/drizzle/, checks __drizzle_migrations for what's already applied, and runs only new ones.

The production image uses node dist/migrate.js (runtime), NOT drizzle-kit migrate (dev dependency).

Troubleshooting

Can't connect: Check DATABASE_URL in api/.env, ensure postgres is running (docker compose up postgres -d).

Migration files not found: Run commands from the project root. Check api/drizzle/ exists.