Choose a database

Jiandu supports SQLite and PostgreSQL 17 or 18. They implement the same application model, but they create different operational responsibilities. The choice does not change Jiandu's current single-process topology.

Recommendation

Start with SQLite unless one of these statements is already true:

• your organization operates PostgreSQL 17/18 as a backed-up, monitored service;
• policy requires the database to be separated from the application host;
• your platform has a mature managed-PostgreSQL recovery practice; or
• another reviewed operational requirement makes a network database preferable to one durable local file.

Choose PostgreSQL for its operational fit, not as a scaling switch. Jiandu still permits exactly one application process to own a database and blob namespace. Do not add replicas or parallel workers against either backend.

Choose SQLite when you plan to use the current Paperless import, which is unavailable with PostgreSQL. Make that choice before the import rather than expecting a later backend conversion.

Compare the tradeoffs

Concern	SQLite	PostgreSQL 17/18
Setup	Built in; no server or credential	Separate server, database, role, TLS, and secret file
Best fit	One durable Jiandu host	Existing database platform or managed service
Availability	Coupled to the application host/filesystem	Database can be independently operated, but Jiandu remains single-process
Backup tooling	Jiandu creates a consistent SQLite snapshot	Jiandu orchestrates matching-major pg_dump/pg_restore tools
Security boundary	Private file and parent directory	Network policy, dedicated login, TLS verification, and owner-only URL file
Tuning	WAL, full synchronous writes, bounded writer wait	Bounded connection pool plus acquire/connect timeouts
Supported versions	Runtime-linked SQLite	Server major 17 or 18 only
Current special limitation	Paperless import is available here only	Paperless import is unavailable

For a household-scale deployment, fewer dependencies usually make SQLite easier to keep reliable. PostgreSQL becomes simpler only when the database service, TLS chain, credentials, monitoring, client tools, upgrades, and restore drills are already routine for the operator.

The choice is durable

Jiandu has no supported SQLite-to-PostgreSQL conversion, PostgreSQL-to-SQLite conversion, or cross-backend restore. A portable document export is not a database converter and does not recreate accounts, permissions, processing state, or configuration.

Shared rules

Whichever backend you choose:

1. use one database only for one Jiandu installation;
2. keep the blob backend recoverable at the same logical point in time;
3. let Jiandu apply its own migrations at startup;
4. stop the old process before moving or recovering the installation;
5. run --check-config with the same paths and secret mounts as the service; and
6. prove backup and isolated restore before importing irreplaceable documents.

Do not let another application modify Jiandu tables. Read-only SQL exploration on a live database can still create load or hold transactions; prefer Jiandu's API and diagnostics.

Configure the selected backend

• SQLite explains path placement, WAL sidecars, busy timeouts, container volumes, and safe backup behavior.
• PostgreSQL covers database/role creation, URL secret files, certificate verification, pool sizing, supported managed-service patterns, and version-matched recovery tools.

After editing the configuration:

jiandu --config /etc/jiandu/jiandu.json --check-config

Then start Jiandu and request the public readiness endpoint. The offline check validates shape and secret files; readiness is the first check that connects to the selected database.

Before changing a database location or doing a same-backend recovery, follow database recovery. Keep the original installation stopped and recoverable until the destination passes application-level verification.