One database per site
addison, cyan and dallas-images are separate Vercel projects, and each has its own Neon Postgres database. Nothing is shared between them, so photos, users and categories have no site column.
The one exception is site_settings, which is keyed by site_key and holds each site’s configuration.
Check which database you are on
Runpnpm db:info before anything destructive.
system_identifier, row counts for photos, site_settings and users, and the site keys present in site_settings. The system_identifier comes from the Postgres control file and is unique per instance, so two connection strings that report the same identifier are the same database however different the URLs look.
Where the schema lives
Drizzle is a typed query layer over the shape the patches create. It does not create or alter anything:
drizzle-kit generate and drizzle-kit migrate are deliberately not wired up, so DDL has exactly one owner.
Querying
Use Drizzle for new or edited code.getSql with tagged-template SQL can stay as they are. Convert one when you are already editing it for another reason. Both clients use the same driver and connection string, so you can mix them inside one request.
Adding a column or table
1
Write a patch
Add the next numbered
.sql file to db/patches. Make it idempotent, for example ADD COLUMN IF NOT EXISTS or CREATE TABLE IF NOT EXISTS. No edit to the migration script is needed.2
Run the safety check
pnpm lint runs the same check as pnpm check:migrations. It fails on DELETE FROM, TRUNCATE, DROP TABLE and DROP COLUMN, and on INSERT without ON CONFLICT. An UPDATE also fails unless the comment block directly above it contains a -- migration-safety: marker explaining why it is safe. The same marker can waive a destructive statement, and the check then lists it as explicitly waived.3
Migrate every database
Run
pnpm db:migrate once per site, as described below.4
Regenerate the Drizzle schema
Run
DATABASE_URL='...' pnpm db:pull against a migrated database, then reapply the two manual edits described in the note below.pnpm db:pull overwrites db/schema.ts and db/relations.ts. Afterwards, add the .js extension to the ./schema import in db/relations.ts, or every ORM endpoint fails in production with ERR_MODULE_NOT_FOUND. Then re-apply the edit that breaks the reference cycle between recipes, recipeVersions, brandKits and brandKitVersions, without which db/schema.ts does not compile; the comment at the top of db/schema.ts describes it. The pull also writes a db/meta/ folder and a db/0000_*.sql file, which are gitignored and safe to delete.Running migrations
pnpm db:migrate applies db/schema.sql, then every file in db/patches in filename order. Every patch is idempotent, so re-running the whole set is safe.
With no DATABASE_URL on the command line, it migrates whatever your local env files point at, which is one site. To target a specific site, pass that site’s production connection string:
DATABASE_URL given on the command line takes precedence over .env.local. To loop over all three sites from local env files:
Migrate before you deploy
Migrate every database before you deploy code that reads a new column. The reason isPHOTO_COLUMNS in api/_lib/photos.ts. It is the column list selected by both api/photos/index.ts and api/shell.ts. If you add a column to it and deploy before a site’s database has that column, every query built from it fails, and every photo endpoint on that site returns errors until the database is migrated.
The Vercel build command runs pnpm db:migrate before pnpm build on production deploys only; preview deploys skip it. Treat that as a backstop for the site being built, not as a substitute for migrating all three databases first. See Deploying for the release steps.
Local setup
Environment files and the dev stack that reads them.
Site settings
The per-site configuration stored in
site_settings.