Database

The database holds everything about your documents — the document records, annotations, tokens, and the audit log. (The PDF bytes themselves live in the object store.) The server supports two drivers.

SQLite (default)#

SQLite needs nothing to set up — it’s a single file on disk. This is the default, and it’s what the Quick start uses.

CLOUDPDF_DB_DRIVER=sqlite
CLOUDPDF_DB_SQLITE_PATH=/data/cloudpdf.db

Postgres#

Postgres is the choice for production and the only way to run multiple replicas. Point the server at any Postgres 14+ database — managed (RDS, Cloud SQL, Neon, Supabase) or one you run yourself.

CLOUDPDF_DB_DRIVER=postgres
CLOUDPDF_DB_URL=postgres://user:password@host:5432/cloudpdf

With Postgres, take migrations out of the boot path so replicas don’t race — run them as an explicit step and refuse to serve on a stale schema:

CLOUDPDF_AUTO_MIGRATE=0
CLOUDPDF_FAIL_ON_PENDING=1

See Migrations for the recommended flow per deployment method.

Moving from SQLite to Postgres#

A common path is to prototype on SQLite and move to Postgres as you grow. The move is a configuration change plus a one-time data migration:

1. Stand up a Postgres database.
2. Point a server at it and run cloudpdf-server migrate up to create the schema.
3. Migrate your existing rows (see MIGRATIONS.md in the server package for the export/import procedure).
4. Switch your running deployment’s CLOUDPDF_DB_DRIVER and CLOUDPDF_DB_URL, and scale up replicas.

Verify the connection#

db doctor connects, validates the schema, and prints version info — a quick way to confirm credentials and connectivity:

cloudpdf-server db doctor

Next steps#