self hosting

n8n Postgres Setup: Environment Variables, Permissions, and Queue Mode Readiness

Self-hosted n8n uses SQLite by default, but you can configure Postgres with database environment variables for more production-oriented deployments.

Match your incident first

Start with the symptom you can prove

Jump to checks

Worker starts but does not process jobs

First check: Compare queue mode, Redis host/db, DB_TYPE, and n8n image tag between main and worker.

Wrong fix to avoid: Do not scale more workers before proving one worker shares the same queue and database.

Verify: A new queued execution changes from waiting to running on a worker and finishes.

Redis connection refused or ENOTFOUND redis

First check: From the worker network, run a Redis ping using the same host and port configured for n8n.

Wrong fix to avoid: Do not point workers at localhost unless Redis is inside the same container.

Verify: redis-cli ping returns PONG and worker logs stop reconnecting.

Jobs stay waiting or active forever

First check: Check worker logs, queue depth, CPU/memory, and the oldest waiting execution.

Wrong fix to avoid: Do not delete production Redis data until you have a backup and know the impact.

Verify: A fresh test execution starts promptly and the old stuck execution is handled intentionally.

Use when: self-hosted, Postgres
First check: Separate whether n8n itself cannot start or only a workflow Postgres node cannot connect.
Time to check: 5-10 minutes
Next step: Match the symptom, then run the verification checks.

Independent third-party notes. n8n is a trademark of its owner and is referenced only for compatibility and troubleshooting context.

Quick Answer

Self-hosted n8n uses SQLite by default, but you can configure Postgres with database environment variables for more production-oriented deployments.

Does this match your symptom?

Postgres connection or query path is failing

n8n cannot reach Postgres, a Postgres node fails in production, or self-hosted database settings are mixed up with workflow credentials.

First check: Separate whether n8n itself cannot start or only a workflow Postgres node cannot connect.

Primary path n8n Postgres Connection Error: Internal DB vs Postgres Node Fixes Related check n8n Postgres Node: Query Safely and Debug Production Failures Related check n8n SQLite vs Postgres: When to Switch for Production and Queue Mode Still blocked? Generate a diagnostic brief

Problem Pattern

The user wants to move beyond default SQLite or prepare for queue mode and needs a checklist for database settings and operational risk.

Version awareness

Last reviewed 2026-05-21

Applies to: self-hosted n8n, Docker, queue mode, Redis, workers, Postgres
Official docs checked: n8n Supported Databases
Version-sensitive assumptions: n8n node parameters, credential names, and queue mode defaults can change between releases; confirm against your installed version before changing production.
What may change after upgrades: Node parameter names, credential scopes, webhook behavior, Docker image defaults, and queue worker expectations may shift after n8n upgrades.

Key Facts

Default database: Self-hosted n8n uses SQLite unless configured otherwise.
Postgres enablement: Set DB_TYPE=postgresdb and the DB_POSTGRESDB_* variables.
Postgres version: n8n supports actively maintained PostgresDB versions.
Permissions: The n8n database user needs permissions to create and modify schemas and tables.

Production Diagnostic Matrix

Turn checks into a brief

Exact symptom or log	Likely cause	First check	Wrong fix to avoid	Verification
Worker starts but does not process jobs	Worker is connected to a different Redis, different database, or wrong queue settings than the main instance.	Compare queue mode, Redis host/db, DB_TYPE, and n8n image tag between main and worker.	Do not scale more workers before proving one worker shares the same queue and database.	A new queued execution changes from waiting to running on a worker and finishes.
Redis connection refused or ENOTFOUND redis	Redis service name, port, network, password, or startup order is wrong.	From the worker network, run a Redis ping using the same host and port configured for n8n.	Do not point workers at localhost unless Redis is inside the same container.	redis-cli ping returns PONG and worker logs stop reconnecting.
Jobs stay waiting or active forever	Workers are offline, concurrency is saturated, Redis state is stale, or a workflow step never completes.	Check worker logs, queue depth, CPU/memory, and the oldest waiting execution.	Do not delete production Redis data until you have a backup and know the impact.	A fresh test execution starts promptly and the old stuck execution is handled intentionally.
Credentials fail only on worker	Main and worker do not share the same N8N_ENCRYPTION_KEY or credential-related env vars.	Compare only safe variable names and fingerprints, not raw secret values, across main and worker.	Do not recreate all credentials before checking encryption key consistency.	The same credential works in an execution handled by a worker.
Binary data unavailable on worker	Binary data mode, filesystem volume, or external storage settings differ between main and worker.	Check binary data mode and whether the same storage path/bucket is mounted for every process.	Do not switch binary modes during an incident without a migration plan.	A workflow that writes and reads a file succeeds when handled by a worker.
Worker logs version mismatch or unknown node type	Main and worker run different n8n images or custom node installations.	Compare image tags and custom node directories between all n8n containers.	Do not upgrade only one worker in a queue-mode cluster.	All containers report the same n8n version and the failing node type loads on the worker.

Still blocked after these checks?

Use the brief to decide whether to keep fixing this setup, move the workload to n8n Cloud, or rebuild the self-hosted path on cleaner infrastructure.

Compare tools

Recommended Steps

Create a Postgres database and user for n8n.
Grant the user enough permissions for n8n to manage its tables.
Set DB_TYPE=postgresdb.
Set host, port, database, user, password, and schema variables.
Start n8n and confirm it connects to Postgres.

Verification

n8n starts without database connection errors.
New workflows and credentials persist in Postgres.
Database logs show successful n8n connections.

First Commands / Checks

Run a low-risk Postgres connectivity check Use from a private terminal when database connectivity is the suspected failure.

psql "postgresql://n8n_app:REDACTED@postgres:5432/n8n" -c "select 1;"

Secrets note: Keep the real password and private host out of tickets, screenshots, and browser pages.
Verification: The command returns one row with value 1, or the error clearly says auth, DNS, SSL, or permission.

Safe Copyable Config

Docker Compose with Postgres for n8n data Use when SQLite is no longer enough or when planning queue mode later.

services:
  postgres:
    image: postgres:16-alpine
    restart: unless-stopped
    environment:
      - POSTGRES_DB=n8n
      - POSTGRES_USER=n8n_app
      - POSTGRES_PASSWORD=REDACTED_CHANGE_ME
    volumes:
      - postgres_data:/var/lib/postgresql/data

  n8n:
    image: n8nio/n8n:latest
    restart: unless-stopped
    depends_on:
      - postgres
    environment:
      - DB_TYPE=postgresdb
      - DB_POSTGRESDB_HOST=postgres
      - DB_POSTGRESDB_DATABASE=n8n
      - DB_POSTGRESDB_USER=n8n_app
      - DB_POSTGRESDB_PASSWORD=REDACTED_CHANGE_ME
      - N8N_ENCRYPTION_KEY=REDACTED_GENERATE_ONCE
      - WEBHOOK_URL=https://automation.example.com/
    volumes:
      - n8n_data:/home/node/.n8n

volumes:
  postgres_data:
  n8n_data:

What to change: Generate a strong database password and N8N_ENCRYPTION_KEY privately. Back up both Postgres and n8n binary data storage.
Secrets to keep private: POSTGRES_PASSWORD DB_POSTGRESDB_PASSWORD N8N_ENCRYPTION_KEY
Verification: n8n starts without migration errors. A restart preserves workflows and credentials decrypt successfully.
Common mistakes: Changing N8N_ENCRYPTION_KEY after credentials exist. Backing up only the n8n volume while the database holds production state.

.env.example with redacted production placeholders Use as a review checklist for self-hosted n8n environment variables.

N8N_HOST=automation.example.com
N8N_PROTOCOL=https
WEBHOOK_URL=https://automation.example.com/
GENERIC_TIMEZONE=UTC
DB_TYPE=postgresdb
DB_POSTGRESDB_HOST=postgres
DB_POSTGRESDB_DATABASE=n8n
DB_POSTGRESDB_USER=n8n_app
DB_POSTGRESDB_PASSWORD=REDACTED_CHANGE_ME
N8N_ENCRYPTION_KEY=REDACTED_GENERATE_ONCE

What to change: Replace domain and timezone. Generate private secret values outside the repo.
Secrets to keep private: Every value marked REDACTED and the real .env file.
Verification: Only expected variable names are present in tickets or docs. The real .env is not committed.
Common mistakes: Sharing full env dumps. Changing encryption key after credentials are created.

Warnings

Back up SQLite data before migrating an existing instance.
Do not expose Postgres publicly without network and credential controls.

Best For

Production-oriented self-hosted deployments.
Instances preparing for queue mode.
Teams that want explicit database backup and monitoring workflows.

Not For

Quick local tests where SQLite is enough.
Users who cannot administer database credentials, backups, and network access.
Queue-mode deployments that still plan to use SQLite.

Common Mistakes

Setting DB_TYPE but missing one of the Postgres connection variables.
Using a database user with unclear or excessive permissions.
Migrating without a backup of the current SQLite database.
Exposing Postgres publicly when only n8n should reach it.

Examples

Core Postgres environment variables Names and defaults can change; confirm against the official docs for your n8n version.

DB_TYPE=postgresdb
DB_POSTGRESDB_HOST=postgres
DB_POSTGRESDB_PORT=5432
DB_POSTGRESDB_DATABASE=n8n
DB_POSTGRESDB_USER=n8n
DB_POSTGRESDB_PASSWORD=change-me
DB_POSTGRESDB_SCHEMA=public

Database readiness checks Run these before pointing production n8n at a new database.

Database reachable from n8n container: yes
User can create and modify tables: yes
Backups configured: yes
Restore tested: yes
Network access restricted: yes

FAQ

Does n8n require Postgres?

No. Self-hosted n8n can use SQLite by default, but Postgres is usually a better fit for production and queue-mode planning.

Can I switch from SQLite to Postgres later?

Yes, but treat it as a migration. Back up the existing database and test the migration path before changing production.

Should Postgres be on the same VPS?

It can be for small deployments, but production setups should consider backup, monitoring, resource isolation, and access controls.

Sources

n8n Supported Databases Accessed 2026-05-07