Database and Auth

Postgres holds all application state. Better Auth handles sign-in and sessions and stores its data in the same database.

Postgres requirementsCopy Anchor Link

• Postgres 17.
• The vector and pg_trgm extensions must be available. The migration script creates them.
• An owner role that can create schemas, extensions, and roles.

Production runs on Neon. Any Postgres that meets these requirements works.

Connection URLsCopy Anchor Link

The app uses the first one it finds: MOGPLEX_RUNTIME_DATABASE_URL, then DATABASE_URL. Migrations always use DATABASE_URL.

Use a least-privilege runtime roleCopy Anchor Link

Running the app as the database owner works, but production should not. The migrations harden a service_role that can read and write data but cannot create databases, roles, or schema objects. The migrations leave the role without LOGIN, so enable it yourself through an owner connection:

alter role service_role with login password '<a strong, rotatable password>';

Then point MOGPLEX_RUNTIME_DATABASE_URL and MOGPLEX_RUNTIME_DATABASE_URL_UNPOOLED at service_role. Never put this password in a migration or a checked-in file.

Apply migrationsCopy Anchor Link

# Local: load .env.local
pnpm exec tsx --env-file=.env.local scripts/apply-neon-migrations.ts

# CI or production: DATABASE_URL already exported
pnpm exec tsx scripts/apply-neon-migrations.ts

# Preview without changing anything
pnpm exec tsx --env-file=.env.local scripts/apply-neon-migrations.ts --dry-run

The script does the following:

1. Creates a ledger table, neon_migrations.schema_migrations.
2. On an empty database (no tables in public), applies neon/baseline.sql and records every migration the baseline covers as applied.
3. Applies pending neon/migrations/*.sql files in filename order, each in its own transaction, and records each one.
4. Exits with code 1 on the first failure.

The app never changes the schema at startup. Run this script before first boot and before you deploy each upgrade.

Better AuthCopy Anchor Link

Better Auth is mounted at /api/auth/*. It trusts only the configured app URL as an origin.

Sign-in providersCopy Anchor Link

Configure at least one provider. A provider turns on only when both its client ID and secret are set.

GitHub sign-in is identity only. Repository access comes from a separate GitHub OAuth app and your GitHub App.

EmailCopy Anchor Link

Email and password sign-up requires address verification. Verification and password-reset emails go through Resend. If sending fails, sign-up fails. It does not skip the check.

If you skip Resend, use social sign-in only.