db

Houses database migrations, types and configuration for running a local PostgreSQL instance.

Targets

Start Local Database

Boots an in-process pglite (no Docker), applies all migrations, seeds it, and serves it over the Postgres wire protocol on port 54332 — the same port the old container used, so DATABASE_URL is unchanged.

It runs in the foreground: leave it in a terminal and press Ctrl-C to shut it down. There is no background container to forget to stop.

pnpm exec nx run db:start
Copy

Because pglite holds no state on disk, every start is a clean reset — migrations and seed are re-applied from scratch on each boot. To pick up a new migration, Ctrl-C and start again. (This is why there is no separate reset or stop target.)

Seed scripts (seed/*.sql) are applied automatically on every start. To boot without them:

pnpm exec nx run db:start:skip-seed
Copy

Generate a Migration

This will generate a blank migration file within the migrations directory.

pnpm exec nx run db:migrate-new <name>
Copy

Execute Outstanding Migrations

pnpm exec nx run db:migrate-up
Copy

Roll Back Migration

pnpm exec nx run db:migrate-down
Copy

Migrations Status

pnpm exec nx run db:migrate-status
Copy

Live Schema Dump

pnpm exec nx run db:migrate-dump
Copy

Seed Data

To add seed data to the database, you can create .sql scripts within the seed directory.

Running the start target on this project will automatically seed the database using these seed scripts.

This data will only be inserted into the local instance.

Pulumi

The pulumi/ directory is a standalone Pulumi program (cfx-db) that owns the RDS PostgreSQL primary and its read replicas per stack.

createDatabase provisions:

• a primary aws.rds.Instance (encrypted, Performance Insights on, deletion protection + final snapshot in prod)
• readReplicaCount replica instances via replicateSourceDb, all sharing the primary's VPC security groups / parameter group

Stack outputs published for consumers (Doppler, other Pulumi stacks via StackReference):

• primaryEndpoint, primaryAddress, primaryPort, primaryArn, primaryIdentifier
• replicaEndpoints, replicaAddresses, replicaArns, replicaIdentifiers

Replica addresses should be passed as readReplicaSqlClients into createDrizzle so reads round-robin across them while writes/transactions stay on the primary.

Stack config

Non-secret knobs live in Pulumi.dev.yaml / Pulumi.prod.yaml: engine version, instance class, storage, multi-AZ, backup retention, subnet group, parameter group, security groups, replica count. masterPassword is a Pulumi secret — set it per-stack before the first deploy:

cd packages/db/pulumi
pulumi stack select dev
pulumi config set --secret masterPassword <generated-password>
Copy

Preview / Deploy

pnpm exec nx run db:pulumi-preview        # dev (default)
pnpm exec nx run db:pulumi-preview:prod
pnpm exec nx run db:pulumi-up             # dev
pnpm exec nx run db:pulumi-up:prod
Copy

The existing primary database is currently managed outside this package. Before running pulumi up for real, import the current RDS instance into cfx-db/<stack> (either via pulumi import or the import: resource option) so this stack adopts it instead of provisioning a duplicate.