n8n SQLite to PostgreSQL migration – step by step with zero downtime

Step by Step Guide to n8n Database Migration – SQLite to PostgreSQL / MySQL

---

⚠️ Before You Run a Single Command: The 3 Things That Kill 90% of n8n Migrations

Most failed migrations aren’t caused by bad commands – they’re caused by three silent errors engineers don’t catch until workflows break in production. Spend 60 seconds here first.

Silent Killer	What Goes Wrong	How to Catch It Now
Encryption key mismatch	Credentials load but fail silently – all OAuth tokens and API keys are unreadable in the new DB	Confirm N8N_ENCRYPTION_KEY is set identically in both environments before migrating
Silent SQLite fallback	n8n appears to start fine but is still writing to SQLite – you don’t notice until the Postgres DB is empty	Use DB_TYPE=postgresdb exactly – not postgres, not postgresql. Wrong value = silent fallback
Wrong table import order	Foreign key violations during import cause partial data load – some workflows missing, credentials orphaned	Import order: credentials_entity → workflow_entity → folder → user → project → execution tables last

---

Terminal Logs

[INFO]  DB_TYPE=postgresdb ✓
[INFO]  Database: PostgreSQL ✓
[INFO]  Connection: OK ✓
[ERROR] Credential decryption failed for ID 14
[ERROR] Credential "Slack API" cannot be decrypted
[ERROR] Credential "OpenAI" cannot be decrypted
# Workflows active. Credentials dead.
# N8N_ENCRYPTION_KEY was never carried over.

Most migration guides tell you to dump the SQLite file, point n8n at Postgres, and restart. That’s technically correct and practically incomplete. The three failure modes above don’t produce loud errors – they produce workflows that look fine but silently fail, or a Postgres DB that appears connected while n8n is still writing to SQLite. This guide covers the full procedure and every trap between you and a clean production database.

Jump to section

● Which path? →
● Why migrate
● Checklist
● Step-by-step
● Silent killers
● Troubleshooting
● CI/CD
● FAQ

Sound familiar?

You migrated. n8n started.
But something is off.

Credentials failing, executions behaving strangely, or you’re not even sure the data went to PostgreSQL at all. The problem is almost never the migration command itself – it’s one of three things that happen before or after it. The answer is below.

Which Migration Path Is Right for You?

Before touching a single command, pick your path. Using the wrong method for your setup creates problems that look like migration failures but are actually setup mismatches.

Who this is for: Production engineers who need to run n8n at scale and must replace the default SQLite store with a robust relational database. The broader performance context – why SQLite fails under load, what queue mode requires, and how to size your DB for workers is covered in the n8n Performance & Scaling Guide. If you’re not sure whether you actually need to migrate, start there.

1. Why Migrate? – Scaling‑Driven Trade‑offs

Concurrency & Size Limits

Operations & Performance

EEFA: Switching DB is a breaking change – always test in a staging environment before touching production data. Worth noting: if you’re already seeing executions pile up or workflows stuck in a running state before this migration, that may be a queue issue independent of the database. The n8n stuck executions guide covers how to tell the difference – some of those symptoms survive a DB migration if the real cause is elsewhere.

2. Pre‑Migration Checklist

3. Step‑by‑Step Migration Procedure

3.1 Stop n8n Gracefully

# Systemd
sudo systemctl stop n8n

# Docker Compose
docker compose stop n8n

EEFA: Do not use kill -9. A graceful stop flushes pending executions and prevents SQLite corruption. If n8n isn’t responding to a normal stop because workflows are stuck, read through the stuck executions guide before forcing a kill – corrupting the SQLite file mid-migration can mean permanent data loss.

3.2 Export SQLite Data (optional JSON audit)

sqlite3 ~/.n8n/n8n.sqlite ".mode json" ".output n8n_export.json" \
  "SELECT * FROM WorkflowEntity;"

The JSON export is handy for audit trails; for large DBs prefer a binary dump (.dump).

3.3 Create Target Database

PostgreSQL – Create user & database

sudo -u postgres psql <<SQL
CREATE USER n8n_user WITH PASSWORD 'StrongP@ssw0rd!';
CREATE DATABASE n8n_db OWNER n8n_user;
GRANT ALL PRIVILEGES ON DATABASE n8n_db TO n8n_user;
SQL

MySQL – Create user & database

mysql -u root -p <<SQL
CREATE DATABASE n8n_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'n8n_user'@'%' IDENTIFIED BY 'StrongP@ssw0rd!';
GRANT ALL ON n8n_db.* TO 'n8n_user'@'%';
FLUSH PRIVILEGES;
SQL

3.4 Migrate Data

Option A: Direct migration with the official helper (recommended ≤ 10 k rows)

npm i -g n8n-migration-tool

# PostgreSQL target
n8n-migration-tool \
  --source sqlite \
  --source-path ~/.n8n/n8n.sqlite \
  --target postgres \
  --target-url postgresql://n8n_user:StrongP@ssw0rd!@db-host:5432/n8n_db

# MySQL target
n8n-migration-tool \
  --source sqlite \
  --source-path ~/.n8n/n8n.sqlite \
  --target mysql \
  --target-url mysql://n8n_user:StrongP@ssw0rd!@db-host:3306/n8n_db

EEFA: Run with --dry-run first to see row counts and verify no errors.

Option B: Manual CSV dump & import (for > 10 k rows)

1. Export each table to CSV

   sqlite3 ~/.n8n/n8n.sqlite ".mode csv" ".output workflow.csv" \
     "SELECT * FROM WorkflowEntity;"
   

   (Repeat for CredentialEntity, ExecutionEntity, etc.)

2. Create tables in the target DB – n8n ships a schema file schema.sql.

   # PostgreSQL
   psql -U n8n_user -d n8n_db -f schema.sql
   

   # MySQL
   mysql -u n8n_user -p n8n_db < schema.sql
   

3. Import CSV files – the order matters. Postgres enforces foreign key constraints on import, so if you load execution rows before the workflow rows they reference, you’ll get constraint violations and partial data.

   # Community-verified import order — do not reorder:
   # 1. credentials_entity
   # 2. workflow_entity
   # 3. folder
   # 4. user
   # 5. project
   # 6. shared_workflow
   # 7. shared_credentials
   # 8. tag_entity
   # 9. workflows_tags
   # 10. execution_entity
   # 11. execution_data (always last)
   
   # PostgreSQL — one command per table in order above:
   psql -U n8n_user -d n8n_db -c "\copy credentials_entity FROM 'credentials.csv' CSV HEADER;"
   psql -U n8n_user -d n8n_db -c "\copy workflow_entity FROM 'workflow.csv' CSV HEADER;"
   # ... continue in order above
   

   # MySQL
   LOAD DATA INFILE '/path/workflow.csv' INTO TABLE WorkflowEntity
   FIELDS TERMINATED BY ',' ENCLOSED BY '"' LINES TERMINATED BY '\n' IGNORE 1 ROWS;
   

EEFA: Ensure CSV files are UTF‑8; otherwise special characters in workflow names may corrupt. If you’re moving years of execution data, consider setting EXECUTIONS_DATA_MAX_AGE=90 on your SQLite instance first and restarting to let n8n prune old rows before you export. Cutting 2 million rows of execution history down to the last 90 days can turn a 3-hour migration into a 10-minute one.

Option C: Official export:entities CLI (n8n v1.67+ – now the recommended path)

Starting with v1.67, n8n ships a built-in export/import CLI that’s now the officially supported migration method. It handles table order automatically and produces human-readable JSON you can inspect before committing to the import.

# Step 1: Export all entities from the SQLite instance (n8n must be stopped)
n8n export:credentials --all --output=./credentials.json
n8n export:workflow --all --output=./workflows.json

# Step 2: Set your Postgres env vars (see Section 3.5 below), then start n8n briefly
# to create the schema in the new DB, then stop it before importing data:
n8n start &
sleep 15
kill %1

# Step 3: Import into the PostgreSQL instance
n8n import:credentials --input=./credentials.json
n8n import:workflow --input=./workflows.json

Copy the encryption key before you do anything else. This step is not recoverable if you miss it.

Every other mistake in this guide can be fixed after the fact – wrong DB_TYPE, wrong import order, wrong URL format. The encryption key cannot. If n8n encrypts your credentials in the new database using a different key than the one used in SQLite, those credential values are permanently unreadable without the original key. Export it first, confirm it’s in your new env, then proceed.

3.5 Reconfigure n8n to Use the New DB

Edit (or create) your .env file:

# PostgreSQL configuration
# DB_TYPE must be exactly "postgresdb" — not "postgres", not "postgresql"
# Any other value causes a silent fallback to SQLite with no warning in the logs
DB_TYPE=postgresdb
DB_POSTGRESDB_URL=postgresql://n8n_user:StrongP@ssw0rd!@db-host:5432/n8n_db

# Carry the encryption key from your old environment — do not generate a new one
N8N_ENCRYPTION_KEY=your-existing-key-here

# MySQL configuration (alternative)
# DB_TYPE=mysqldb
# DB_MYSQLDB_URL=mysql://n8n_user:StrongP@ssw0rd!@db-host:3306/n8n_db

EEFA: Never commit plain credentials. Use Docker secrets, Kubernetes Secrets, or a vault. One other thing worth flagging: if n8n returns an SSL error when connecting to your new Postgres host immediately after this config change, that’s a TLS handshake issue at the connection layer – not a migration failure. The SSL certificate error guide covers the exact fix, and it’s separate from anything you’ve done in the migration steps.

3.6 Restart n8n & Verify

# Systemd
sudo systemctl start n8n

# Docker Compose
docker compose up -d n8n

Verification steps

1. Open the n8n UI → Workflows → All – all entries should be present.
2. Open a few workflows and click Execute – ensure they run without DB errors.
3. Check Execution List for historic runs.
4. Open Credentials and test 2–3 connections – this is where encryption key mismatches surface. If a credential returns a decryption or authentication error here, go directly to Silent Killer #1 in Section 4.

4. The 3 Things That Break 90% of n8n Migrations

These don’t throw loud errors. They produce workflows that look migrated but fail at runtime, or a Postgres DB that appears connected while n8n quietly continues writing to SQLite. Each has a distinct log signature that tells you exactly what went wrong.

🔑 Silent Killer #1 – Encryption Key Mismatch

# Retrieve auto-generated key from original host
cat ~/.n8n/.cache/n8n-encryption-key

# Set it in the new environment before restarting
N8N_ENCRYPTION_KEY=paste-key-here

[INFO]  Database: PostgreSQL ✓
[INFO]  Connection pool: OK ✓
[ERROR] Credential decryption failed for ID 14
[ERROR] Error: Invalid credentials — unable to decrypt stored value

EEFA: “Missing credentials after migration” in the troubleshooting table below is almost always this. The credentials aren’t missing – they’re present but encrypted under a key that no longer matches. Re-entering credentials manually works as emergency recovery, but setting the correct key is the actual fix. If you regularly rotate credentials across infrastructure changes, the API key not recognized guide covers how credential state drift in n8n compounds over time and how to prevent it.

🗄️ Silent Killer #2 – The DB_TYPE Value That Sends You Back to SQLite

# ❌ These all cause silent SQLite fallback:
DB_TYPE=postgres
DB_TYPE=postgresql
DB_TYPE=Postgresdb   # case-sensitive

# ✅ Correct:
DB_TYPE=postgresdb

# After restart, verify in n8n logs:
# [INFO] Database: PostgreSQL  ← what you want to see
# [INFO] Database: SQLite      ← still falling back, fix DB_TYPE

EEFA: After correcting DB_TYPE and restarting, immediately run SELECT COUNT(*) FROM workflow_entity; against your Postgres DB. If the count matches your workflow count from SQLite, you’re live on Postgres. If it’s zero or missing rows, the connection URL likely has a special character in the password that needs URL-encoding – ! becomes %21, @ becomes %40.

📋 Silent Killer #3 – Wrong Table Import Order

EEFA: If you’re using DBeaver or another GUI tool for the import, you can temporarily disable constraint checks to allow any import order – SET session_replication_role = replica; in Postgres, or SET FOREIGN_KEY_CHECKS=0; in MySQL. Re-enable after import. Just make sure the data itself is internally consistent before turning constraints back on, or you’ll end up with orphaned records that break n8n in harder-to-diagnose ways later.

5. Post‑Migration Validation & Troubleshooting

Every migration failure is diagnosable.

Once you know whether you’re dealing with an encryption key problem, a DB_TYPE typo, or an import order issue, the fix is mechanical – not a guessing game. The table below maps every post-migration symptom to its actual cause.

EEFA: Encrypted credential values are not portable across different encryption keys. After migration, if you cannot recover the original key, re-entering credentials manually is the only path forward. If you’re moving to queue mode after this migration and seeing workers fail to pick up jobs or executions hanging – that’s a connection pool sizing issue, not a migration artifact. The n8n Performance & Scaling Guide has the right pool configuration for multi-worker queue setups.

6. Automating Future Migrations (CI/CD Friendly)

# .github/workflows/n8n-db-migrate.yml
name: n8n DB Migration

on:
  workflow_dispatch:
    inputs:
      target:
        description: 'postgres|mysql'
        required: true
        default: 'postgres'

jobs:
  migrate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Install migration tool
        run: npm i -g n8n-migration-tool

      - name: Run migration
        env:
          SQLITE_PATH: ${{ secrets.SQLITE_PATH }}
          PG_URL: ${{ secrets.PG_URL }}
          MYSQL_URL: ${{ secrets.MYSQL_URL }}
        run: |
          if [[ "${{ github.event.inputs.target }}" == "postgres" ]]; then
            n8n-migration-tool --source sqlite --source-path $SQLITE_PATH \
              --target postgres --target-url $PG_URL
          else
            n8n-migration-tool --source sqlite --source-path $SQLITE_PATH \
              --target mysql --target-url $MYSQL_URL
          fi

Benefits

• Version‑controlled migration steps.
• Secrets managed by the CI platform – no plaintext credentials in the repo.
• Easy rollback by re‑running the workflow with the previous DB URL.

Frequently Asked Questions (FAQ)

Conclusion: The Migration Itself Is the Easy Part

Migrating n8n from SQLite to PostgreSQL or MySQL eliminates the single‑writer bottleneck, lifts size constraints, and unlocks replication and hot‑backup capabilities essential for production workloads. By following the checklist, using the official migration tool (or the v1.67+ CLI path for newer installs), and re‑configuring n8n’s environment variables, you get a clean transition with minimal downtime. The procedure itself – stop, export, create DB, import, reconfigure, restart – takes under an hour for most setups.

What turns a 30-minute migration into a 2am incident is always one of three things: an encryption key that wasn’t carried over, a DB_TYPE value that was close but not exact, or a table import order that silently dropped half the data. All three are preventable. None of them make noise when they fail – which is exactly why they keep catching people off guard. Remember to re‑enter encrypted credentials after the move if you can’t recover the original key, tune connection pools for your expected concurrency, and validate workflow execution before calling it done.

If you moved to Postgres specifically to scale up – adding more workers, running queue mode, handling higher execution volume – the n8n Performance & Scaling Guide covers what comes next: connection pool sizing, queue mode architecture, and how to prevent the database from becoming your bottleneck again after the migration is done. And if the migration surfaces authentication issues in your workflows because services need to re-authenticate, the token expired error guide covers the OAuth refresh patterns that commonly come up when credentials are re-entered after a DB change.