db

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

Targets

Start Local Database

This will start a local PostgreSQL Docker container, run all migrations against it, and seed it:

pnpm exec nx run db:start
Copy

Reset Local Database

This will wipe the local database, re-run all migrations and seed the database:

pnpm exec nx run db:reset
Copy

Seed Local Database

This will explicitly just seed the local database. This will rarely need to be run. You'll more likely want to run reset during development.

pnpm exec nx run db:seed
Copy

Stop Local Database

pnpm exec nx run db:stop
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 or reset targets 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.