Database Setup

Drevnix supports two database backends. Schema migrations run automatically on every startup. No manual DDL required.

Choosing a database

SQLite is the right default for most deployments, including production. The Drevnix workload is read-heavy — auth checks and permission lookups on every pull, with infrequent writes for audit log entries. SQLite in WAL mode handles this pattern extremely well and will not be a bottleneck in any realistic single-instance setup.

Only switch to PostgreSQL if you have a specific operational requirement:

• You need to run multiple Drevnix instances simultaneously behind a load balancer
• You already run a managed PostgreSQL service (RDS, Cloud SQL, Supabase) and want unified backups, monitoring, and managed cloud database tooling
• Your organisation requires database-level HA with automatic failover

If none of those apply, SQLite is the simpler and equally capable choice.

SQLite

JDBC_URL=jdbc:sqlite:/data/drevnix.db?journal_mode=WAL&synchronous=NORMAL&busy_timeout=30000&foreign_keys=on

The query parameters matter:

Parameter	Value	Why
journal_mode=WAL	WAL mode	Allows concurrent reads during writes. Essential for any real workload
synchronous=NORMAL	Normal sync	Safe durability without the overhead of FULL sync
busy_timeout=30000	30 seconds	Retries instead of immediately failing when the DB is locked
foreign_keys=on	Enabled	Enforces referential integrity at the SQLite level

Mount /data as a Docker volume so the database file persists across container restarts and replacements:

docker run -v drevnix-data:/data drevnix/drevnix:latest

When SQLite is not enough:

• Do not run multiple Drevnix instances against the same SQLite file. SQLite has no concurrent write support and will produce errors under simultaneous writes from separate processes. If you need horizontal scaling, use PostgreSQL.
• SQLite has no built-in replication. If you need database-level failover, use PostgreSQL with a managed HA setup.

PostgreSQL

Use PostgreSQL when you need multi-instance deployments or HA at the database layer. PostgreSQL 14 or later is required.

Connection URL format

Credentials are embedded directly in the URL:

jdbc:postgresql://<user>:<password>@<host>:<port>/<database>

With SSL (recommended for remote databases):

jdbc:postgresql://<user>:<password>@<host>:<port>/<database>?ssl=true&sslmode=require

Example

JDBC_URL=jdbc:postgresql://drevnix:your-db-password@db:5432/drevnix

AWS RDS example

JDBC_URL=jdbc:postgresql://drevnix:[email protected]:5432/drevnix?ssl=true&sslmode=verify-full

Required permissions

The database user needs CREATE, SELECT, INSERT, UPDATE, DELETE on the Drevnix schema. Drevnix creates all tables itself on first startup.

Automatic schema migrations

Drevnix uses Flyway for schema migrations. On every startup it compares the current schema version to the bundled migrations and applies any outstanding changes automatically.

Migrations are forward-only. There is no rollback. Back up your database before upgrading to a new version of Drevnix.

Backup

• SQLite: Stop Drevnix, copy the database file, then restart. Or use the SQLite .backup command for a hot backup.
• PostgreSQL: Use pg_dump or your cloud provider’s automated snapshot feature. Test restores regularly.