SQLite or Postgres, local disk or S3?

PrintStash defaults to SQLite for metadata and local disk for managed files. Postgres and S3-compatible object storage are optional. Most home installations should start with the defaults and change one layer only when there is a clear reason.

Use SQLite for a normal single server

PrintStash is usually a low-concurrency application: a few people browse the library while imports, scans, and printer updates write in the background. SQLite suits that shape and keeps the database in one persistent volume.

It also reduces the number of services you have to monitor. A full PrintStash backup captures a consistent copy of the SQLite database with the managed blobs and thumbnails.

Choose SQLite when:

• one PrintStash API instance owns the database;
• the library serves a household or small workshop;
• easy backup and recovery matter more than fitting an existing database platform.

Keep the database volume on reliable local storage. Do not put a live SQLite file on a flaky SMB mount.

Use Postgres when it solves an operational problem

Postgres makes sense when you already operate it, want database-level monitoring and backup tooling, or expect more concurrent writes than a home setup normally produces. PrintStash still supports one API process per vault, regardless of database, and startup refuses a second process.

Both engines expose the same application features. Choose Postgres for its operational properties, not for different PrintStash behavior.

Start the bundled profile with:

docker compose --profile postgres up -d

Review the current environment variables and backup plan before moving an existing installation.

Keep files on local disk unless object storage helps

Local storage is the simplest managed-vault backend. Uploads, previews, and downloads stay close to the API, and standard host backup tools understand the volumes.

S3-compatible storage is useful when managed blobs should live independently of the Docker host, or when your platform already provides an object store. PrintStash supports services such as S3, R2, and MinIO through the same backend settings. Downloads use short-lived presigned URLs instead of streaming every blob through the API.

Object storage adds credentials, bucket policy, network dependency, and provider cost. Use it when those costs solve a specific storage or hosting problem.

Shared volumes are a separate choice. They let PrintStash index an existing local or NAS folder in place. Those source files are not managed-vault blobs and are not copied into a full PrintStash backup.

Separate live storage from backup storage

The vault storage backend and the backup mirror use different settings. A local-disk vault can mirror backup archives to an S3-compatible bucket, which is often more useful than moving the live library to object storage.

Built-in backups are created on demand for SQLite installs. If you want nightly archives, call the backup API from cron, systemd, or another scheduler. PostgreSQL installs need pg_dump and an operator-managed restore procedure. Test a restore on a separate stack and back up shared-volume source folders with your normal NAS tooling.

Migrations happen when the containers start

Current images run database migrations through the container entrypoint. The same process supports SQLite and Postgres. Normal upgrades are therefore:

docker compose pull
docker compose up -d

Take a full backup first, read the release notes, and check the API logs after startup. The upgrade guide includes recovery steps for older installations with unusual migration history.

For most users, SQLite plus local disk and an off-host backup copy is the practical starting point. Add Postgres or S3 when you are prepared to operate the extra dependency.