Migrate n8n from SQLite or MySQL to PostgreSQL: what the move involves
Moving a self-hosted n8n instance from SQLite or MySQL to PostgreSQL is a planned database move that uses n8n's own export:entities and import:entities commands. Copying database tables directly between engines is not a route to rely on for this change. For MySQL and MariaDB users, the export and import path is the required route since n8n 2.0, and teams planning queue mode usually need PostgreSQL too, because queue mode workers read and write workflow data there. Effort depends on instance size, the number of credentials, custom code and how many integrations depend on the instance, so confirm each of these before anyone commits to a schedule.
Most of the preparation happens before any data moves. Build an inventory of workflows, credentials, users, environment variables, custom nodes and anything outside n8n that calls it, such as webhook senders, scheduled partners and reporting jobs. Each external caller is a cutover risk, because some may need a new URL or a configuration change. Confirm with n8n's documentation which n8n version the export and import commands expect on the source and target sides, and keep both sides on matching versions. Then choose the PostgreSQL major version. The supported versions in the PostgreSQL versioning policy are 14 through 18, and 14 reaches end of support on November 12, 2026, so a new target should be on a version that will still be supported for its expected service life.
Encryption key handling is the step most likely to cause lasting damage if it is handled loosely. n8n stores credentials encrypted with the instance's encryption key, so the target instance must be configured with the key that matches the exported data. Locate the key on the source, record it in your secrets store and confirm the exact procedure in n8n's documentation before the import. If you plan queue mode, the same key must also be shared with every worker and webhook processor, which means the key handling decision affects the whole topology, not only the database. A lost or mismatched key can leave imported credentials unreadable, and the workflows that depend on them will then fail.
The cutover itself is short only when the preparation is complete. Freeze workflow edits during the window, run the export on the source, import into PostgreSQL and then compare workflow and credential counts with the source inventory. Test a manual run, a webhook and a scheduled trigger for each critical workflow, and confirm that external callers reach the new endpoint. Keep the SQLite or MySQL database unchanged until the new instance has passed these checks, so that a rollback remains possible. Cost comes from internal staff time, the PostgreSQL service, backup and monitoring, and any partner work. Ask a partner for a written, fixed scope that lists the inventory, the verification tests and the rollback plan.
What maps cleanly from SQLite or MySQL to PostgreSQL in n8n
This table compares the instance capabilities n8n keeps on SQLite or MySQL with their PostgreSQL side and migration handling. Read the second column first, since it shows what the documented export and import path covers and what you must recreate or verify by hand. Confirm the exact entity list against n8n's current documentation before planning, because it can change between releases. The main takeaway is that the database move does not carry everything, so environment settings and file-based items need separate checks.
| Capability | Export and import path | PostgreSQL side and notes |
|---|---|---|
| Workflows | Covered, confirm against current entity list | Imported into PostgreSQL. Check active state and re-activate triggers after import. |
| Credentials | Covered, confirm against current entity list | Encrypted with the source encryption key. Keep that key available or plan to re-enter credentials. |
| Executions history | Confirm whether included | Can be large. Decide before export whether history must move or can stay on the old database. |
| Users and roles | Confirm whether included | Verify sign-in for each account, owner access and role assignments after the import. |
| Tags | Confirm whether included | Verify tag assignments on workflows after import. |
| Variables | Confirm whether included | Verify values by hand if they are not in the export. Do not assume they carried over. |
| Environment settings | Not covered by entity transfer | Set database connection, encryption key, instance URL and any queue mode settings in the new environment. |
| Webhooks and triggers | Workflow definitions covered, live endpoints need checks | Confirm production webhook URLs and re-register triggers during cutover. |
| Community nodes | Not covered by entity transfer | Reinstall community nodes on the new instance and verify their versions. |
| Binary data storage | Not covered by entity transfer | Files kept on local disk or external storage must be copied or re-pointed separately. |
Which n8n export and import paths are documented
The documented route for moving n8n onto PostgreSQL uses n8n's own export and import commands. These cards cover what each step reads and writes, which versions to confirm, and which common shortcuts sit outside the documented path. Check every command against the documentation for your exact n8n version before you plan the cutover.
Export from the source instance
The documented first step is the export:entities command, run on the instance that currently holds your data. It reads the entities n8n keeps in the source database, such as workflows and credentials, and writes them to export files on disk. Confirm the command options, the output location and the exact entity types included for your version. Keep the export files in a protected location, because credential data is sensitive and must be handled as such.
Import into the PostgreSQL instance
The import:entities command runs on a fresh n8n instance already configured to use PostgreSQL. It reads the export files produced by the source step and writes those entities into the PostgreSQL database that n8n manages. Run it against an empty target, and confirm the target configuration before the first start so that imported data is not written over existing records.
Confirm the n8n version on both sides
Run both steps on n8n versions that the release notes document as compatible with each other. Read the release notes for the source and the target, and record both version numbers in your runbook. Confirm with the release notes whether the source must be upgraded before the export, and schedule that upgrade as its own step with its own rollback point.
MySQL and MariaDB source instances
Since n8n 2.0, the export and import path has been the documented route for MySQL and MariaDB users moving to PostgreSQL. If your current database is MySQL or MariaDB, plan the migration around this path and rehearse it on a copy of the data before any production cutover. Confirm the supported database versions in the documentation for your n8n release.
Raw SQL dumps are not a migration path
Dumping n8n's tables with mysqldump, sqlite3 or a similar tool and loading them into PostgreSQL is not a documented migration path. The export and import commands handle n8n's internal data structure, and a hand-converted dump can silently miss or misplace records. Use the documented commands, and treat any custom SQL conversion script as unsupported.
PostgreSQL tools apply after the database exists
pg_dump and pg_upgrade back up or upgrade PostgreSQL databases, so they become relevant only once a PostgreSQL instance already holds n8n data. They do not read SQLite files or MySQL databases. Use them later for backups or PostgreSQL major version upgrades, and keep the n8n export and import commands as the route for the database change itself.
How the encryption key carries over to PostgreSQL and workers
The encryption key is the one setting that can make a successful migration look broken. n8n encrypts stored credentials with the instance encryption key, so the new PostgreSQL-backed instance must use the same key as the source instance. Without it, the workflows and entities import cleanly, but the credentials they depend on cannot be decrypted and every affected connection fails at run time. Before you plan the cutover, confirm with the current n8n self-hosting documentation how the key is set in your version and where that configuration lives in your deployment, whether that is a configuration file, an environment setting or a secrets mechanism your platform team already uses.
Record the key from the source instance before you run the export, and store it in your secrets manager with restricted access and a clear owner. Do not assume the key travels with the exported data. Treat the export files and the key as two separate artifacts, and confirm in the n8n documentation what the export and import commands do and do not carry. After the import, verify the key on the new instance by opening a workflow that uses a known credential and running it in a test execution. A passing test with a real credential is stronger evidence than checking that the configuration value looks right.
If the key is lost or changed, the encrypted credentials already in the database cannot be recovered by replacing the key with a new value. Each credential will need to be re-entered by someone with access to the external system, and any workflow that depends on it will remain broken until that is done. Ask your team to inventory credentials by type and owner before cutover so the recovery effort is known in advance. Do not rotate the key during the migration window. Change one variable at a time, and schedule any key rotation as its own change after the new instance is stable and verified.
Queue mode raises the stakes because the key must be identical on every process that reads credentials. In queue mode, the main instance handles triggers and webhooks and passes executions through Redis to workers, and those workers read and write workflow data in PostgreSQL. The n8n queue mode documentation requires the main instance's key to be shared with all worker and webhook processor nodes. A mismatch can be hard to spot because the main instance may work while workers fail specific executions. Generate the configuration for all roles from one source, and add a key comparison and a test execution on each worker to your go-live checklist.
How to sequence inventory, a pilot, parallel run and cutover
This sequence moves an n8n instance from SQLite or MySQL onto PostgreSQL in stages that each end with a check. Each stage builds on the last, so a failed verification stops the work before any production trigger moves. The result is a cutover you can reverse until the old database is retired.
Inventory the source instance
Record the n8n version, database type and size, and every workflow, credential, custom node and community package in use. Note which workflows depend on webhooks or schedule triggers, which endpoints are exposed publicly, and whether queue mode with workers is running. Confirm where the encryption key is stored and take a full backup of the database and the n8n data folder. The platform owner and the implementation team complete this list together. It is done when every item has an owner and the backup location is recorded.
Stand up the PostgreSQL target
Provision PostgreSQL on a major version that is still supported on your planned go-live date. The PostgreSQL versioning policy lists versions 14 through 18 as supported, with different end dates, so confirm the current dates on the policy page before you choose. Configure authentication, TLS, storage and backups, including a point-in-time recovery plan that has been tested. Create a dedicated database and role for n8n. It is done when n8n can connect with that role from its host and a test restore has completed.
Export and import into a pilot
Run the entity export on the source and import the result into a pilot n8n instance connected to the new PostgreSQL database. Confirm the n8n version requirements for import in the n8n documentation before you start. Carry the same encryption key to the pilot unchanged, because stored credentials cannot be read without it. Disable all triggers in the pilot before its first start so nothing fires against live systems. It is done when the import completes without errors, the workflow and credential counts match the export output, and the pilot starts cleanly.
Verify workflows and credentials by execution
Run each business-critical workflow manually in the pilot and confirm that every credential authenticates against its external system. Test custom nodes and community packages, and check that expressions and scripts return the same results as on the source. Confirm that executions are written to the PostgreSQL database. Log each failure against the workflow and assign an owner. It is done when every critical workflow has a passing execution record and each open item has a fix or a sign-off from the workflow owner.
Run a parallel period with trigger ownership
Keep the source running while the target is prepared, and assign one owner for each trigger. Only one instance may own a given schedule or webhook at any time, because two active copies of the same trigger will both fire. Record each workflow's owner in a shared register and update it whenever ownership changes. Compare execution outputs between the two sides for the workflows that matter most. It is done when every trigger has a single recorded owner and the comparison shows no unexplained differences.
Freeze changes and cut over triggers
Freeze workflow edits, credential changes and n8n upgrades on both instances before the switch. Deactivate schedules and webhooks on the source, confirm that no executions are still running there, then activate the same triggers on the target. Update the webhook URLs in every calling system, and confirm that the DNS or proxy route points to the new instance. If you run queue mode, each worker and webhook processor must use the same encryption key and connect to the PostgreSQL target. It is done when a test event reaches only the target and the source shows no active triggers.
Decommission the old database after backup
Keep the source database and a final backup until the retention period in your change policy has ended, and confirm that the final backup can be restored in a test. Stop the source instance, disable its remaining jobs and remove its access. Retire the old database and its credentials only after those steps are complete. It is done when a test restore of the final backup has succeeded and the decommission record shows who approved removal.
What drives the cost and duration of the move
This table lists the factors that change how much work the move takes and who performs it. Read each row as a question to answer before requesting a quote, because several drivers multiply across environments and workflows. The main takeaway is that the workflow inventory, webhook map and queue mode decision shape the written scope more than database size alone.
| Driver | Who carries the work | One-time or recurring | What to ask for in a quote |
|---|---|---|---|
| Number of workflows and credentials | Your team confirms the inventory; the provider scripts export checks and import validation | One-time | Inventory method, counts by workflow and credential, and how each credential is verified after import |
| Custom code and community nodes | Provider tests each custom node and community node on PostgreSQL; your team approves results | One-time, with recurring retests when nodes update | List of installed nodes and versions, test scope per node, and the upgrade retest process |
| Inbound webhooks and external callers | Your team owns the calling systems; the provider maps endpoints and plans the cutover order | One-time, recurring if webhook URLs change | Webhook inventory, owner for each external caller, and the cutover window they need |
| Source database size and execution history retention | Provider plans export and import runs; your team sets the retention policy | One-time, longer for larger data sets | Row counts for the main tables, pruning plan for old executions, and expected export and import runs |
| Queue mode planned | Provider sets up PostgreSQL access, Redis, workers and the shared encryption key; your team runs the hosts | Recurring, through worker and Redis operations | Worker count, how the encryption key reaches each node, and the monitoring scope for workers |
| Number of environments | Each environment repeats export, import and checks; your team approves each one | One-time per environment | Whether development, staging and production move separately, and the order of moves |
| Parallel run requirement | Provider sets up output comparison; your team operates both instances and decides cutover | One-time, with a longer run window | Length of the parallel run, who compares results, and the rollback trigger |
| Audit and change-control requirements | Your change board approves; the provider writes change records and collects evidence | One-time for the move, recurring for each later change | Evidence contents, approval steps, and whether your auditor needs to review the plan before work starts |
What usually goes wrong during an n8n database move
Most failures in this move come from three places: the encryption key, traffic that still reaches the old instance, and assumptions about what carries over. Each card names one failure, the step that prevents it, and the check to run before cutover. Work through them during a rehearsal on a copy of the data, not for the first time on cutover day.
Credentials that stop decrypting
n8n encrypts stored credentials with the encryption key of the instance that created them. If the new PostgreSQL-backed instance starts with a different key, every imported credential becomes unreadable and workflows fail on their first authenticated call. Prevention: copy the original encryption key into the target environment before the first start, and store it in your secrets manager. Check: open one credential of each type on the target and run a test request before cutover.
Duplicate runs and changed webhook URLs
During a parallel run, schedule triggers and polling workflows on both hosts can each fire, so one message or record may be processed or sent twice. Prevention: keep triggers active on only one instance, deactivate schedule and polling workflows on the target until cutover, and record which host owns each trigger. Webhook addresses also change when the host name changes, so external senders keep calling the old URL. Check: list every webhook path, confirm the public base URL on the target, and update senders or DNS before the switch.
Execution history that does not carry over as expected
Teams often assume the move carries all execution history, with the same fidelity as workflows and credentials. Confirm in a test import which entity types move and which stay behind, using the n8n documentation for the version you run. Prevention: decide in advance whether old executions must be searchable after cutover, and if not, archive the source database before the switch. Check: compare workflow and credential counts and the most recent execution timestamp on both sides, and document what is intentionally left behind.
Custom code and community nodes missing on the new host
Workflows that call custom JavaScript, Python or community nodes depend on packages installed on the source host. The target may run a different build or lack the same packages, so these steps fail only when a workflow reaches them. Prevention: inventory custom code and community node packages from the source, reinstall them on the target at the same versions, and pin the n8n version on both hosts during the rehearsal. Check: run each workflow that uses these nodes on the target with test data and confirm every node loads and completes.
PostgreSQL version close to end of support
According to the PostgreSQL versioning policy, PostgreSQL 14 is supported until November 12, 2026, so a database built on it at cutover may need a major upgrade soon after the move. Prevention: choose a major version that is still supported for longer, such as 17 (supported to November 8, 2029) or 18 (supported to November 14, 2030). Check: confirm the support dates on the cutover date, and plan minor updates, which do not change the storage format, as part of normal operations.
Backups that were never restored in a test
A backup of the source database is only useful once a restore has been tested. Teams often take a dump before cutover and never restore it to a scratch server. Prevention: restore the source backup into a separate PostgreSQL instance, start n8n against it, and run a representative workflow end to end. Check: time the restore, confirm that stored credentials decrypt with the preserved key, and document the recovery plan for the target once it is live, including how continuous archiving will be configured.
Which PostgreSQL version to target and what it means for operations
Choose the PostgreSQL major version before you migrate, because it sets how long the n8n database stays under security support. PostgreSQL releases a new major version about once a year and supports each one for five years after its initial release. The currently supported versions are 18, 17, 16, 15 and 14. Version 18 reaches end of support on November 14, 2030, version 17 on November 8, 2029, version 16 on November 9, 2028, version 15 on November 11, 2027, and version 14 on November 12, 2026. A new deployment on version 14 would need another major upgrade within months, so it should not be the target.
Pick a version whose support runs well past the period you plan to operate this instance, and leave room for the next upgrade. Ask your team how long this n8n installation should run before its next database change, then compare that date with the end-of-support dates above. Version 18 is the newest supported release and gives the longest runway. Before you install it, confirm in n8n's own documentation which PostgreSQL versions your n8n release supports, and confirm that your operating system or managed hosting provider offers the packages you need.
Minor updates are the routine maintenance task. PostgreSQL minor releases arrive at least once every three months, and they never change the internal storage format. Applying one means replacing the server executables and restarting, so you only need a short maintenance window. Stop n8n first so no executions write during the restart, then bring it back up and check workflow runs. Put a minor update routine on the calendar, and test each one in a staging copy of the n8n database before it reaches production.
Major upgrades need a documented path chosen in advance. PostgreSQL describes three options: dump and restore with pg_dumpall, pg_upgrade, and logical replication. Dump and restore is the simplest, but downtime grows with database size. pg_upgrade reuses the data files, and PostgreSQL 18 retains planner statistics across major upgrades and adds parallel jobs and a --swap option. Logical replication works between different major versions and can limit downtime to several seconds, but it needs its own setup and cutover checks. Rehearse whichever method you pick against a copy of your n8n data.
Backups, connection pooling and high availability each need their own plan, because the PostgreSQL installation does not supply all of them. PostgreSQL provides continuous archiving and point-in-time recovery, but you must configure archiving and test restores yourself. Connection pooling is typically handled by an external pooler such as PgBouncer, and you should size it before adding queue mode workers, since each worker opens database connections. For high availability, PostgreSQL supports hot standby servers with synchronous or asynchronous replication, but it does not include software that detects a primary failure and promotes a standby. Automatic failover requires an external tool that you select, deploy and test. Also note that n8n's multi-main setup is limited to Enterprise self-hosted deployments.
What do buyers ask before hiring help for an n8n PostgreSQL migration?
How much does an n8n PostgreSQL migration cost?
The cost follows from the written scope, and DeployOpen does not publish a price list, so ask for a quote built from that scope. The main drivers are the number of n8n instances, the source database (SQLite, MySQL or MariaDB), the size of the data and execution history, whether queue mode with workers and Redis is in place, how many credentials need owner verification, the number of environments, and the change windows you must work within. The migration itself is a one-time piece of work. Ongoing support, upgrades and testing are separate, optional retainers. When you request a quote, ask for line items covering discovery, export and import runs, validation, cutover, rollback planning, documentation, and a clear list of exclusions.
How long does an n8n migration to PostgreSQL take?
Duration depends on the agreed scope, so there is no standard timeline to quote here. The biggest factors are the number of instances and environments, the volume of data to move, how many workers and webhook processors must be reconfigured, and how quickly your change board approves cutover. Credential verification and any rehearsal runs also add time, especially when credential owners are spread across teams. Ask for a written timeline with milestones, dependencies on your change calendar, and the points where your team must make a decision or provide access. A timeline that does not name these dependencies is not yet ready to plan against.
Can our team migrate n8n to PostgreSQL without an outside partner?
Many teams can, provided an administrator has working knowledge of PostgreSQL, container or host administration, and secrets handling. n8n provides its own CLI tooling for moving entities between databases, and MySQL and MariaDB users must use export:entities and import:entities since n8n 2.0. The steps that most often cause trouble are not the export commands themselves. They are encryption key handling across every main, worker and webhook process, updating endpoints and environment variables, confirming that scheduled and webhook-triggered workflows still run, and preparing a rollback. If your team has done this before, the work is manageable in-house. If not, a partner can reduce the risk of a failed cutover.
What does our team need to provide for a migration engagement?
Plan to provide administrative access to the n8n hosts, the source and target database servers, and the container or process manager, with credentials that allow export, import and service restarts. You also need approved change windows, named owners who can confirm that each credential works after migration, and a non-production test environment that closely matches production. Backups of the source database and the encryption key, held in your secrets process, must be available before work starts. Someone with authority over DNS, reverse proxy and webhook URLs should be reachable during cutover. These items should appear in the written scope as dependencies, with the owner and date for each.
Is a pilot required before moving n8n to PostgreSQL?
A pilot is not a fixed requirement of the migration, but a rehearsal on a copy of production is strongly advisable. A rehearsal runs the export and import against a restored copy of your instance, then checks that workflows load, credentials decrypt, executions write to PostgreSQL, and webhooks respond at the expected addresses. It also gives you a measured picture of how long cutover will take in your environment, which no general estimate can give you. Whether a pilot is included in the scope, and what it covers, should be stated in the written scope so that you can compare quotes on the same basis.
Does DeployOpen issue an audit report or certification for the migration?
No. DeployOpen plans and implements the work, and prepares systems, controls and evidence for compliance assessments. Audit reports, attestations and certifications are issued only by independent auditors or certification bodies. For a migration, useful evidence often includes change records, backup and restore test results, access lists for the database and hosts, records of who holds the encryption key, and validation results from the rehearsal and cutover. Ask your auditor which of these they expect and agree the format before work starts, so the evidence is captured during the migration rather than reconstructed afterward.
What goes wrong if the n8n encryption key does not match after migration?
Credentials stored in the database can no longer be decrypted, so workflows that call external systems fail even though the instance appears healthy. In queue mode, every worker and webhook processor must use the same encryption key as the main instance, so one mismatched process can fail only certain executions. Before cutover, confirm the key in every process, test a credential from each workflow group, and check worker logs for decryption errors. Record who holds the key and how it is rotated, since n8n's own documentation ties the key to credential access across all processes. Include this check as an acceptance step in the scope.
How DeployOpen scopes, delivers and supports the migration
DeployOpen plans the move from SQLite or MySQL to PostgreSQL as a fixed-scope piece of work, agreed in writing before any change is made to your n8n instance. The engagement covers exporting entities with n8n's own CLI tooling, importing them into a PostgreSQL target, handling the encryption key, and verifying the result in your own infrastructure.
How we scope
- The written scope names your source database, whether SQLite or MySQL or MariaDB, and the target PostgreSQL major version.
- It records every n8n instance, queue worker and webhook process that must be stopped, changed or restarted during cutover.
- Fixed-scope terms, deliverables and timelines are agreed in writing; ongoing support is available as a retainer.
How we build
- Export entities with n8n's export:entities command from the existing instance, then keep the exported files under access control.
- Import into a fresh PostgreSQL database with import:entities, checking workflow and credential counts against the source before cutover.
- Carry the encryption key across unchanged so credentials decrypt on PostgreSQL and every queue worker shares that key.
How we hand over
- Handover includes a cutover runbook, a rollback path to the original database and a record of checks performed.
- Documentation covers the key location, the backup points for both databases and the n8n settings that point at PostgreSQL.
- Your team receives the runbook and documentation, and decisions about key custody stay with your organization.
How we support
- Post-cutover support, upgrades and testing can continue under a retainer agreed separately from the migration scope.
- Ask whether the scope includes a PostgreSQL minor-release and major-upgrade plan, since PostgreSQL 14 support ends November 12, 2026.
- Confirm with n8n which versions support your target PostgreSQL release before scheduling the cutover window.
