Database and Provider Guide — Help Center

Codapult supports Turso/libSQL and PostgreSQL through parallel Drizzle schemas. The shared application interface keeps the product layer consistent while each provider offers a distinct deployment path.

Turso/libSQL

The default provider and the fastest path for local development.
A local file:local.db URL works without an external database service.
Cloud deployments require TURSO_DATABASE_URL and, for cloud databases, TURSO_AUTH_TOKEN.
SQLite/libSQL syntax, locking, connection behavior, and provider limits still apply.
The default rate limiter and in-memory jobs are process-local; they do not become distributed because the database is remote.

PostgreSQL

Use DB_PROVIDER=postgres and a DATABASE_URL connection string.
The PostgreSQL schema mirrors the SQLite schema but uses native PostgreSQL timestamps, booleans, JSON, indexes, and constraints where appropriate.
Run schema and migration commands with the same provider selected in the environment. Do not apply SQLite SQL to PostgreSQL or the reverse.
PostgreSQL production deployments need a connection plan, SSL configuration, backup policy, and migration owner.

Deployment alignment

Keep src/lib/db/schema.ts and src/lib/db/schema-pg.ts semantically aligned. Run npx @codapult/cli db schema-diff after schema changes.
Organization-owned queries must carry organization scope; provider parity does not prevent an application-level tenant isolation bug.
pnpm db:push is convenient for a fresh development database. For an established production database, review generated SQL and use the deployment migration workflow.
A generated migration is not a backup or rollback plan. Test the forward change and record the recovery or forward-fix procedure.
Database choice does not configure object storage, Redis, payment webhooks, SSO, or AI provider credentials. Configure and verify those adapters separately.

Choose your deployment path

Use local SQLite to start quickly, Turso when you want the same libSQL model with managed access, and PostgreSQL when your team or hosting platform requires PostgreSQL capabilities and operational tooling. Make the choice based on the workload and deployment model, not on a claim that one provider is universally better.

Turso/libSQL

The default provider and the fastest path for local development.
A local file:local.db URL works without an external database service.
Cloud deployments require TURSO_DATABASE_URL and, for cloud databases, TURSO_AUTH_TOKEN.
SQLite/libSQL syntax, locking, connection behavior, and provider limits still apply.
The default rate limiter and in-memory jobs are process-local; they do not become distributed because the database is remote.

PostgreSQL

Use DB_PROVIDER=postgres and a DATABASE_URL connection string.
The PostgreSQL schema mirrors the SQLite schema but uses native PostgreSQL timestamps, booleans, JSON, indexes, and constraints where appropriate.
Run schema and migration commands with the same provider selected in the environment. Do not apply SQLite SQL to PostgreSQL or the reverse.
PostgreSQL production deployments need a connection plan, SSL configuration, backup policy, and migration owner.

Deployment alignment

Keep src/lib/db/schema.ts and src/lib/db/schema-pg.ts semantically aligned. Run npx @codapult/cli db schema-diff after schema changes.
Organization-owned queries must carry organization scope; provider parity does not prevent an application-level tenant isolation bug.
pnpm db:push is convenient for a fresh development database. For an established production database, review generated SQL and use the deployment migration workflow.
A generated migration is not a backup or rollback plan. Test the forward change and record the recovery or forward-fix procedure.
Database choice does not configure object storage, Redis, payment webhooks, SSO, or AI provider credentials. Configure and verify those adapters separately.