n8n PostgreSQL vs SQLite: choose the topology and recovery artifacts

Conditional verdict: architecture before a database label

Self-hosted n8n uses SQLite by default. That is a starting point, not a promise that every workload belongs on SQLite. If the design uses distributed queue components, n8n's documented topology calls for PostgreSQL; every participating component must reach the same database. The queue article owns that dataflow and worker decision.

For a compatible single-instance design, SQLite keeps the database local and avoids a separately operated service. Its boundary is copy consistency: a normal file copy while writes continue may capture mismatched state. PostgreSQL adds database-native backup choices and a service boundary, along with connection, privileges, TLS, version, storage and restore ownership. Neither database is inherently faster for your workload or sets a safe disk size.

Official Compose guidance describes SQLite for trying things and PostgreSQL for more than a handful of users or around-the-clock workflows. Treat that as qualitative context, not a numeric user cutoff or performance threshold. Record execution classes, retained history, locations and observed growth. If nobody can explain how writes stop or how a copy is validated, keep the design in discovery.

Supported database and topology matrix

This table puts support, topology and recovery responsibility in one decision. “Supported” is scoped to captured n8n database documentation; recheck the exact release before deployment.

The captured policy said 17/18 were the two latest actively maintained majors and 16 was retained for compatibility in July 2026. PostgreSQL majors age out and n8n's range changes. Recheck n8n's database page and selected release notes rather than carrying these numbers into a new build.

Container paths are image-specific. A reference Compose PGDATA value describes that image layout; it does not convert an existing directory. Record PostgreSQL image, data path, database major and n8n release separately.

Connectivity, schema and privileges are design inputs

Fill this worksheet from the actual target instead of copying sample values:

n8n needs permission to create and modify its schema. The captured docs show a broad database grant example; that does not instruct every operator to grant superuser rights. Have the database owner validate required privileges for the release and migration path.

TLS variable conflict remains OPEN: captured narrative names DB_POSTGRESDB_SSL_CA, while its shell example uses DB_POSTGRESDB_SSL_CA_FILE. Do not infer which the release consumes or paste either into production configuration based here. Confirm the selected release's environment reference and test certificate validation. This page deliberately gives no runnable TLS line.

There is no universal connection-pool or database RAM figure. Attribute demand to the chosen main, webhook and worker topology, then measure it. The queue article owns that accounting.

Changing database settings is not an SQLite data migration

Setting a PostgreSQL type and connection values tells n8n where to initialize or connect. It does not automatically copy SQLite workflows, credentials, users, settings or history. Schema initialization and application-data portability are separate operations.

Record source/target release, database, credentials owner and paths. Avoid concurrent writers pointed at old and new databases during a handoff: split history is difficult to reconcile, and a successful process start proves neither completeness nor ownership. PostgreSQL major upgrades are also separate from n8n image-tag changes. Article 5 covers the versioned service and volume inventory, not data transfer.

Pruning and SQLite VACUUM change the disk question

Retention is a business/debugging decision as well as a storage setting. Documentation captured for this draft lists pruning enabled by default, maximum age 336 hours (14 days), maximum count 10,000 and one-hour hard-delete buffer. These are release-sensitive defaults, not recommended retention. Recheck selected-release values.

Pruning targets finished executions. New, running and waiting executions are ineligible; annotated executions (for example, tagged or rated) are not pruned. The count limit may not land exactly on 10,000. Binary cleanup follows the active binary mode; changing modes does not mean old objects elsewhere are swept.

Complete the worksheet from observations over dated intervals; do not use a GB-per-execution multiplier.

SQLite pruning can leave pages reusable inside the file without shrinking its host footprint. File size and filesystem free space are distinct readings. VACUUM can reclaim file space but has prerequisites and can need additional room; do not schedule it as casual cleanup. Verify release option, lock/write implications, free-space needs and maintenance window first.

Deleting an execution row and expiring its external object are separate lifecycle events. Ask the storage owner which process deletes objects and whether retained copies expire independently.

Build a measured working-set and copy-space worksheet

Record observed size, units, date, growth interval and owner for each item. A planning sum is database working set + retained executions/binaries + .n8n and other actual paths + temporary dump/restore copies + independent recovery copies. Each term may occupy a different filesystem or service; do not collapse it into one unqualified disk number.

For SQLite, track internal free pages separately from filesystem availability. For PostgreSQL major changes, plan for source, target and logical dump/workspace as the selected method requires. PostgreSQL documents distinct logical dump and in-place upgrade categories; confirm method-specific requirements before reserving capacity. Send itemized quantities to the cost walkthrough. File size does not imply RAM or speed.

Consistent-copy matrix: database plus neighboring artifacts

A recoverable app state spans more than database rows. The matrix shows likely coverage and separate obligations. Use evidence for the actual platform/release; persistent volume does not mean backup.

n8n backup guidance describes .n8n as relevant because it contains SQLite and key material and may contain binary/execution data in filesystem modes. With PostgreSQL, the DB backup covers database state while .n8n still matters for the key and local artifacts. Add custom-node folders and external stores only when actually used. Article 10 owns coordinated copy, import, cutover and restore.

Read-only inventory and copy-acceptance receipt

This bounded Bash discovery reports filesystem capacity, candidate configuration names and metadata only. It does not read environment values, database contents or secret files. Run as an account authorized to inspect the named project; review output because path names can be sensitive.

#!/usr/bin/env bash
set -u
PROJECT_DIR="REPLACE_WITH_REVIEWED_PROJECT_DIRECTORY"
if [ ! -d "$PROJECT_DIR" ]; then
  printf '%s\n' "STOP: project directory missing" >&2
  exit 2
fi
printf 'Project: %s\n' "$PROJECT_DIR"
df -h -- "$PROJECT_DIR"
printf '%s\n' 'Configuration filenames only:'
find "$PROJECT_DIR" -maxdepth 2 -type f -name 'compose.yaml' -print
printf '%s\n' 'Candidate directory metadata only:'
for path in "$PROJECT_DIR/.n8n" "$PROJECT_DIR/data" "$PROJECT_DIR/postgres"; do
  if [ -e "$path" ]; then stat -c '%F %U:%G %a %n' -- "$path"; else printf 'ABSENT %s\n' "$path"; fi
done
if command -v docker >/dev/null 2>&1; then docker volume ls --format '{{.Name}}'; else printf '%s\n' 'Docker CLI unavailable'; fi
printf '%s\n' 'STOP: map volumes to services using an approved secret-safe config review; do not print env values.'

This cannot prove active mounts, database contents, external objects or consistency. Before any copy, an operator records the instance/release and DB versions; actual mapped paths; external stores; key custodian; authorized backup owner; and evidence-backed writer-quiescence or platform procedure with a named stop signal. List each artifact, destination, access boundary, free-space check and deletion owner, including a copy independent of the source host/account.

1. At one recorded cutoff, tie database and neighboring artifacts together. Capture operation status and artifact metadata/checksum where suitable; file existence does not prove consistency.
2. Restore to an isolated compatible target under Article 10's acceptance gate. Check startup, expected workflows/settings, credential decryption, intended history/binaries and restart persistence. Do not activate production workflows during acceptance.
3. Record result, operator, date, missing coverage and next action. A receipt with unresolved artifact rows is partial, not a recovery pass.

Stop: if writers cannot be quiesced, snapshot consistency is undocumented, key unavailable, space short or an object store omitted, do not label the copy a recovery point. Preserve source and resolve the gap. Abandon an unaccepted attempt; resume the original only after confirming original data paths remain intact. Never switch production to a partial target.

Upgrade, rollback and recovery gate

Put current/target n8n tags, source/target DB major/minor, image-specific data path, filesystem layout, dump/global method, key custodian, rollback compatibility and restore evidence in one matrix. Match the exact n8n tag to release notes and migration guidance. Captures conflict on n8n 3.0: release notes say released 2026-10-27 while breaking changes label 3.0.0 early access. Resolve the selected tag and channel directly; never use blind latest.

A new PostgreSQL image tag or PGDATA does not convert populated data across major versions. PostgreSQL documents distinct logical dump/restore and in-place upgrade categories with different compatibility and rollback conditions. Select from actual versions and matching official documentation; retain source until target acceptance.

n8n schema can move forward with an app release. Do not assume an older app can read a DB after newer schema migration. If final-cutoff copy cannot restore with credentials decryptable and intended data present, stop before destructive migration or source deletion. No restore duration, RPO or RTO is claimed.

Acceptance records DB consistency, app/key match, workflows and credentials, intended users/settings/history, binary/object availability and persistence after isolated restart. Article 10 owns owner assignment, ID behavior and production cutover.

Hand-off to deployment, recovery and provider evidence

Article 5 turns choice into versioned service, volume, environment and privilege inventory; do not copy a TLS variable until the selected-release reference resolves its conflict. Article 10 owns transfer/full-state operation, acceptance, cutoff and rollback. The key guide covers key custody.

Ask a provider for exact facts: supported DB product/version; private reachability/firewall; storage expansion/filesystem limits; temporary dump/restore room; whether snapshots are crash- or application-consistent and which disks they include; independent destination and restore owner; external-store/edition costs; and what survives stop, cancellation or deletion. Treat each as unresolved until documented.

Compare terms with backup versus snapshot policy and cancel, stop and delete terms. Price selected artifacts using the cost tool and cost walkthrough. No provider-managed database or snapshot claim is inferred here.

Translate community symptoms into checks: identify DB/release, inspect logs without secrets, compare matching docs and stop if consistency is uncertain. Reports frame questions; they do not establish incidence or comparative performance. See methodology.

Sources and updates

Documentation captures checked 2026-11-06. Recheck version-sensitive statements for the selected n8n and PostgreSQL releases before operating.

• n8n, Choose n8n's database — default, support, privileges and TLS wording conflict.
• n8n, Queue mode — distributed topology.
• n8n, Backup and restore — app artifact scope.
• n8n, Manage execution data — pruning exceptions and SQLite space reuse.
• PostgreSQL, Upgrading a cluster and SQL dump — distinct upgrade/backup categories; use matching major docs.
• Docker, Volumes — persistence behavior, not restore acceptance.

Source capture is not deployment, copy, restore rehearsal, performance test or provider verification. No live system changes were made.