n8n export, migration and disaster recovery: prove the target before you leave

A downloadable file is not a recovery plan

Four operations are often called “migration,” but each moves a different boundary. CLI entity exports are useful for selected workflows and credentials; a package can carry selected dependencies; full-instance recovery coordinates application and deployment state; a version migration changes the software or database that interprets that state. A snapshot is only a storage-layer artifact until its consistency, included volumes, access and restore have been demonstrated.

Queue workers add execution capacity; they are not backups or high availability. Multi-main is an edition-gated architecture, not a substitute for restoring state. Current n8n docs and release notes contain version and channel wording that has shifted around 3.0. Record the exact source and target tag, selected channel, matching release notes and migration report before acting. Never select an unexamined latest tag on a recovering production system.

Inventory the whole recovery set before choosing an export

Start with the running topology, not the export button. Under default SQLite with local storage, the n8n data directory can be the application-state basis described by n8n; an external PostgreSQL deployment also requires its database. External binary storage, custom nodes, deployment configuration and any service outside that boundary remain separate artifacts. A database dump alone is not a whole-instance recovery set.

Use this ledger to name each actual store, writer and proof signal. “Not selected” is a valid entry; an unknown path or owner blocks a complete claim.

Capture sizes and growth, consistency/quiesce needs, portability coverage, key dependency, independent-copy location, restore owner and observable verification signal. Include an artifact only if your topology uses it, but mark each row selected, rejected or unresolved. Binary retention and database backup design belong with database and backup boundaries; key recovery with key and credential rotation; exact service manifests with Compose ownership.

Fresh imports have an identity hazard: the person who completes first-owner setup may become the owner. Prepare an access-controlled target, decide who completes setup, and confirm owner/project semantics before importing. Never import into an unattended open setup screen.

Compare portability and recovery coverage

This matrix identifies what each operation can contribute and the gap you must close. Exact behavior is release-specific; a successful export proves only that the export operation completed.

For CLI backup/export, use separate directories for workflows and credentials: the captured n8n backup guidance notes a mixed import issue. A same master key is needed to decrypt encrypted credential exports. The documented plaintext option is sensitive material; this article does not provide a plaintext export recipe. Preview packages can carry variable values by default and may omit credentials the exporter cannot read. Review the package manifest and requirements, not just the requested ID list.

n8n recommends its CLI package workflow for new command-line work. The Server CLI import page says commands are planned for deprecation but not yet scheduled; that is not the same as already removed. Older linked documentation may be archived, so pair exact-version instructions with current release notes and selected-build help. n8n export and import · package export scope.

Choose the operation by source, target and desired state

Same-host upgrade, same-version new-host recovery and new-host plus new-version migration have different failure surfaces. Separate them unless a rehearsed plan has an acceptance boundary for each. A data export cannot transfer callback registrations, external authorization, custom packages or an instance key by implication. Record what needs reauthorization or reconstruction, including model/vector/search data only when those services are selected. Do not assume an edition feature, API scope or external service is available until checked for the selected target.

Runbook A — controlled workflow/package transfer

Use the selected release’s documented interface. This sequence is planning and acceptance only; its discovery block reads supplied inventory and metadata without connecting, exporting, mutating or displaying secrets. Work from an authorized account and protected workstation.

1. Preconditions. Name source and target owners, exact n8n tags/editions, DB modes, install paths, selected package/CLI availability, authorized target administrator, protected transfer location and recovery copy. Verify current release notes and migration report. Stop if either version or interface is unknown.
2. Read-only discovery. Inspect the selected deployment files and version inventory without displaying secret values. Record workflow/credential/dependency counts, projects, folders, variables, IDs, active status and external dependencies. Choose intentional entities. The preview package limit is 300 IDs per group; split and review larger groups. Project IDs cannot be mixed with workflow/folder IDs in the same package request.
3. Collision and authority review. Compare selected IDs with target records; approve each overwrite explicitly. Confirm initial-owner setup, project access, variable-value policy, API scopes, readable credentials and same-key availability. Unknown owner or key means stop.
4. Protected export. Quiesce selected workflows or define tolerated concurrent changes. Export separate entity groups/directories when using server CLI. For packages, inspect actual manifest and requirements. Restrict file access, avoid logs and retain a separate authorized recovery copy. Do not treat checksums as content-scope proof.
5. Controlled import. Use the selected release’s documented import interface. Preserve default-inactive behavior. Do not use active-state import semantics in queue or multi-main without checking that selected release. Install only approved, version-matched dependencies; resolve missing/unreadable credentials before activation.
6. Acceptance. Reconcile source selection to exported/imported counts and manifest; confirm folders/projects/owners/variables, collisions, credentials, dependency graph, IDs and active states. Run harmless representative executions with external writes disabled or pointed at a safe test target. Check outputs manually and confirm schedules/callbacks cannot create duplicate production runs.
7. Stop and rollback. Halt on missing credentials, unexpected skipped dependencies, target-owner uncertainty, unreviewed overwrite, version mismatch or failed harmless execution. Keep target inactive; restore its pre-import copy or remove only explicitly approved imported records using the selected interface. Do not overwrite the source to “undo” a transfer. Source remains authoritative until a named owner accepts the residual-gap ledger.

For source-backed Server CLI entity transfer, use distinct output directories: the captured backup guidance specifically warns that a combined directory can make separate credential import fail. These commands assume the selected release actually provides these CLI commands and the documented container/install context; verify its help before execution. They export only the selected Server CLI backup scope (workflows and credentials), not users, roles, execution history/logs, variables, settings or the key.

# HUMAN GATE A1: authorized source owner approved these exact entities,
# source/target versions and a protected destination; no plaintext/decrypted mode.
# Run inside the selected n8n server CLI context. Replace paths; do not use a shared directory.
set -eu
umask 077
out_root="REPLACE_WITH_AUTHORIZED_PROTECTED_EXPORT_ROOT"
workflow_dir="$out_root/workflows"
credential_dir="$out_root/credentials"
test ! -e "$out_root" || { echo 'STOP: output path already exists'; exit 2; }
mkdir -m 700 -- "$out_root"
mkdir -m 700 -- "$workflow_dir" "$credential_dir"
n8n export:workflow --backup --output="$workflow_dir/"
n8n export:credentials --backup --output="$credential_dir/"
# HUMAN GATE A2: operator separately verifies file inventory, counts, source IDs,
# destination collision list, target owner/project assignment and matching key custody.
# Copy these two directories only over the approved protected channel; verify receipt.
# On target, set these to the verified received paths; require they are distinct.
received_workflows="REPLACE_WITH_VERIFIED_PROTECTED_RECEIVED_WORKFLOW_DIRECTORY"
received_credentials="REPLACE_WITH_VERIFIED_PROTECTED_RECEIVED_CREDENTIAL_DIRECTORY"
test -d "$received_workflows" && test -d "$received_credentials" || { echo 'STOP: received directories missing'; exit 2; }
test "$received_workflows" != "$received_credentials" || { echo 'STOP: directories must be separate'; exit 2; }
# HUMAN GATE A3: target backup approved, target owner initialized, collisions approved,
# exact target release/DB version recorded, matching key verified in protected custody.
n8n import:workflow --separate --input="$received_workflows/"
n8n import:credentials --separate --input="$received_credentials/"
# STOP after import: workflows default inactive. Reconcile and accept before manual activation.

Original IDs are retained, so same-ID records can be overwritten. Credential import requires the matching key; initialize a named owner and confirm selected-release user/project assignment. Stop on unknown occupancy, unapproved collisions or unresolved key/owner custody. Restrict manifests and logs because names and IDs can be sensitive.

Package path alternative: n8n documents `n8n-cli package export` and import as Preview, not stable API endpoints. Use the selected CLI interface and package review gates; do not invent an HTTP endpoint. Requests separate project IDs from workflow/folder IDs and cap each group at 300. Values are included by default unless disabled; unreadable credentials become requirements. Inspect the manifest, archive, dependencies and permissions. Stop if import behavior differs from selected documentation. CLI command availability remains a release gate.

Stop/rollback: on any acceptance mismatch, leave the source authoritative and target inactive; restore its pre-import copy or remove only approved imported records through the documented interface. This is not a full-state backup.

Runbook B — full application-state restore

Chosen template topology: n8n and PostgreSQL run in a reviewed Compose project; n8n is stopped for file copying and PostgreSQL stays available only for a consistent logical dump. Restore to an isolated Compose project with new instance-anchored volumes. Managed databases, SQLite, Kubernetes, rootless/custom containers and external services are out of scope; stop and use that topology’s validated native method rather than adapting these commands.

1. Capture architecture read-only. Complete the artifact ledger, exact app/DB releases, local or external binary mode, mounts, custom nodes, key escrow reference, DB global-object needs, owners, last successful backup and last observed restore. Identify who can authorize restore.
2. Set objectives and cutoff. Write acceptable data loss (RPO) and target restore time (RTO) as measured objectives. Identify scheduled, manual, webhook and queue writers, retries and third-party calls. Select release-specific control/drain steps and coordinate a final cutoff. n8n cannot guarantee completion of asynchronous external operations.
3. Create a consistent independent set. For SQLite, use a documented stopped/consistent copy approach. For PostgreSQL, select a supported source/target method. pg_dump covers one database; cluster-wide roles/globals require separate consideration, such as a reviewed pg_dumpall scope. Copy external binaries/objects, custom files, deployment/network config and master-key escrow under separate access controls. Include temporary export and restore capacity in the cost model.
4. Isolate the target. Confirm supported app/database combination, storage capacity, exact mounts, controlled first-owner setup and private access. Keep schedules, production callbacks and integrations disabled or safely redirected. Never allow old and new writers to mutate the same restored database.
5. Restore in dependency order. Restore compatible DB and required globals; pair it with the matching .n8n/master material; apply reviewed deployment settings and permissions; restore custom/community dependencies and binary/object mappings; then configure proxy/TLS/network. Use commands approved for the exact selected release and database image. Do not infer conversion from a volume/tag change.
6. Verify before reopening. Confirm service and schema health, credential decryption after restart, users/projects/settings/variables, expected history, binary reads, custom-node loading and external-store access. Check workers/runners use compatible configuration. Run harmless sample workflows; inspect outputs and error paths. Re-establish independent backups before enabling schedules or public callbacks.
7. Stop/rollback gate. If an artifact, key, owner, version or acceptance check fails, keep target isolated and stop writes. Preserve the failed target for diagnosis if safe. Reopen source only after confirming it is the single consistent writer and documenting the cutoff/reconciliation decision. Keep the pre-change database and matching app/key artifacts together; an older runtime may not read a forward-migrated schema or key format.

Unknown target data, key or database ownership blocks restore; preserve it. This bounded template requires an authorized Linux operator host, reviewed Compose file, discovery-filled placeholders and approved maintenance window/output path. Secret variables are never printed or logged.

# TEMPLATE ONLY — stopped n8n + PostgreSQL containers; same compatible release.
# Never run against production until every STOP gate has a signed approval.
set -eu
umask 077
compose="REPLACE_WITH_REVIEWED_COMPOSE_FILE"
project="REPLACE_WITH_EXACT_SOURCE_COMPOSE_PROJECT"
n8n_service="REPLACE_WITH_DISCOVERED_N8N_SERVICE"
db_service="REPLACE_WITH_DISCOVERED_POSTGRES_SERVICE"
writer_services=("REPLACE_WITH_EVERY_DISCOVERED_N8N_WRITER_SERVICE")
test "${#writer_services[@]}" -gt 0 || { echo 'STOP: enumerate every writer first'; exit 2; }
backup_root="REPLACE_WITH_AUTHORIZED_PROTECTED_ABSOLUTE_DIRECTORY"
db_name="REPLACE_WITH_DISCOVERED_DATABASE_NAME"
db_user="REPLACE_WITH_DISCOVERED_DATABASE_ROLE"
test "${backup_root#/}" != "$backup_root" || { echo 'STOP: output directory must be absolute'; exit 2; }
test ! -e "$backup_root" || { echo 'STOP: output directory exists; preserve and review it'; exit 2; }
install -d -m 700 -- "$backup_root"
chmod 700 -- "$backup_root"
# HUMAN GATE B1: verify project/services/DB name and role without showing env or secrets.
# Record exact source image tags and volume/mount map in separate non-secret manifest.
docker compose -p "$project" -f "$compose" config --services >/dev/null
# HUMAN GATE B2: approve writer cutoff; stop all n8n writers/workers by discovered services.
docker compose -p "$project" -f "$compose" stop "${writer_services[@]}"
# PostgreSQL logical scope: pg_dump is this one DB only; globals are a separate artifact.
# Credentials come from the container's configured protected auth context; never pass a password on argv.
docker compose -p "$project" -f "$compose" exec -T "$db_service" pg_dump -U "$db_user" -d "$db_name" -Fc > "$backup_root/database.dump"
docker compose -p "$project" -f "$compose" exec -T "$db_service" pg_dumpall -U "$db_user" --globals-only > "$backup_root/globals.sql"
chmod 600 -- "$backup_root/database.dump" "$backup_root/globals.sql"
# Copy stopped n8n container data to a NEW protected output path, never overwrite a prior set.
# Resolve the actual container through Compose; never guess generated names.
container_id=$(docker compose -p "$project" -f "$compose" ps -q "$n8n_service")
test -n "$container_id" || { echo 'STOP: expected n8n container missing'; exit 2; }
docker cp "$container_id:/home/node/.n8n" "$backup_root/n8n-user-folder"
# HUMAN GATE B3: verify actual discovered container name/mount and all selected binary/custom paths.
# Copy selected bind mounts/custom-node paths and selected external binary/object data separately
# using their documented native tools; preserve mapping/permissions in the restricted manifest.
# Copy reviewed deployment/network config with secret references only, never secret values.
# Copy matching master material separately by its authorized escrow procedure; never cat/echo it.
# Reapply restrictive permissions; hash artifacts without printing their contents.
find "$backup_root" -type d -exec chmod 700 {} +
find "$backup_root" -type f -exec chmod 600 {} +
# STOP: transfer only via authorized protected channel. Preserve this source set off-host.

Restore gate (no universal restore command is asserted): keep the target isolated and use a new, unique Compose project name so generated container and named-volume names are anchored to that target instance. Record the resolved names from the selected Compose project; never share source volumes. Confirm exact target image tags and compatibility with the source artifacts and with one another; a matching-looking tag or path alone proves nothing. PostgreSQL restore owner, database creation, role/global handling, extension availability and image-specific data paths must be documented for the selected versions. Supply the selected operator-approved restore commands in the change record, review them with a second operator, and execute only after the explicit restore authorization gate. Restore the one-database dump and globals as separate scopes; do not feed globals into `pg_restore`. Restore `.n8n` with its matching protected master material, custom nodes, binary/external-store mapping and reviewed deployment config. Do not start schedules or public callbacks until acceptance.

For SQLite, managed PostgreSQL or external stores/custom paths, use that topology’s documented consistent-copy or native export method; this template supplies no universal commands. Mark STOP — topology-specific commands required until operator commands and approval are recorded. Preserve failed target data; reopen source only as sole writer after cutoff/reconciliation. Never use down -v or broad prune.

n8n 3.0 and PostgreSQL major migrations are separate version gates

n8n 3.0 migration and rollback

The captured v3 migration path is Docker-focused; npm-era deployments need a migration plan rather than a casual runtime/tag replacement. Preserve the documentation conflict beside version advice: the release notes describe 3.0 as released while other installation/channel labels have described it as early access. Verify the selected tag, channel, matching breaking-change notes, migration report and selected image before scheduling. Do not invent a minor version or assume channel text is authoritative by itself.

Inventory the documented changes relevant to your instance: binary storage path changes, removal of the in-memory default, unverified community packages disabled by default, altered/deleted nodes and expressions, and Code timeout/runner topology where applicable. The migration report identifies workflow/environment issues and can create a new saved version for supported replacements; it is not a backup or a compatibility guarantee. Human review and output tests remain necessary. Old published workflows may continue until the replacement is published, so decide which version will receive production traffic.

Database schema migration is forward-moving. Do not pin an older runtime against a migrated database and call that rollback. The captured key-format change also has an older-version read boundary and no conversion path documented; recovery means restoring the compatible database backup with its matching application/key state. Stage main, workers and runners consistently and accept the target before cutover.

PostgreSQL major migration

PostgreSQL documents logical dump/restore and pg_upgrade as distinct major-upgrade approaches. Choose after verifying exact source/target versions, image, topology, extensions and downtime constraints. A plain pg_dump backs one database; global roles and other cluster-level needs require explicit handling. Measure dump, transfer and restore stages in rehearsal; do not promise a duration from documentation alone.

A changed image tag or PGDATA path is not a major-version conversion. Paths are image-specific, and a changed mount can expose an empty data directory. Keep old and new storage intact until the new server and n8n have passed checks. Link the DB backup boundary article for supported topology and unresolved TLS fields; the Compose article owns the actual service manifest.

Sources checked 2026-11-06: n8n migration guide, n8n release notes, PostgreSQL upgrade methods and pg_dump scope. Confirm documentation and image paths for the selected versions.

Cutover, rollback and final-exit hold point

Gate sequence: control writers and set final cutoff → copy required artifacts independently → restore and accept that cutoff on target → cut over URLs/workflows → observe → consider deletion only after acceptance. Change DNS, callbacks and public endpoints under control; account for queue, cron, manual and third-party retry writers to prevent duplicate schedules. Record cutoff and accepted loss; do not infer RPO from a provider feature.

Before accepting webhook cutover, check canonical URLs, callback re-registration, proxy/TLS, production/test/waiting routes and external callers; route details belong to the webhook and TLS guide. Confirm matching key format and reauthorization before revoking old credentials; see credential recovery and rotation.

Assign an owner for old hosts, storage, backups, addresses and exports. Check provider billing/deletion terms before irreversible action; stopped resources may still be billed. See deletion checkpoints and snapshot questions. Snapshots are not presumed application-complete.

Disaster acceptance receipt and drills

Rehearse ledger-matched scenarios: workflow deletion, unreadable credentials/lost key, DB corruption, host or object/custom-path loss, failed app/DB upgrade, exposed backup, or provider/region outage. Record each scenario’s artifacts, restore path, objective, unresolved dependency and decision owner.

Use “not tested” where evidence is absent. A pass covers only the recorded topology, versions and workflows. Inaccessible required artifacts, failed decryption or an ownerless dependency leave the receipt unresolved and cutover on hold.

Cost, provider and policy evidence hand-off

Price the chosen recovery architecture after its artifacts and copy counts are known. Include independent retention, temporary dump/export/restore storage, old and new hosts/databases, transfer and egress, restore-region availability, application edition/API/license, staging and operator time, and cancellation residue. Unknown values are unresolved, not zero. Feed measured quantities into the n8n cost walkthrough or total-cost tool only after selecting alternatives.

At provider evidence, verify exactly which mounts and data planes are included, consistency behavior, off-host copy access, retention, restore permissions, region availability, egress/export charges, quotas, privileged-container constraints, support scope and deletion terms. A vendor snapshot may be useful infrastructure evidence; it does not establish that n8n users, keys, binaries and external dependencies recover correctly. The policy guides cover generic backup and exit questions; this page owns n8n artifact coverage and acceptance.

Keep an unresolved register with item, evidence needed, responsible party and decision date. If a required dependency remains unknown, retain the source and defer the final-exit decision. For the actual deployment topology, continue to the n8n hub, Compose baseline or methodology.

Sources and updates

• n8n backup and restore — topology-dependent recovery set and CLI backup scope; capture checked 2026-11-06.
• n8n export and import and package export — portability, Preview status and package limits; checked 2026-11-06.
• n8n migration docs and release notes — selected-release/version gates; checked 2026-11-06.
• PostgreSQL upgrading and pg_dump — major upgrade methods and database scope; checked 2026-11-06.
• About and Methodology — evidence scope and editorial method.

Source captures are dated 2026-11-06. Documentation paths, edition availability and release/channel labels can change; re-check the selected build and exact procedure before an operational change. No recovery drill or production migration is claimed by this article.