When Strapi data transfer between environments replaces manual copying
Strapi's transfer capability moves content, media and configuration from one Strapi instance to another, and it writes into the target instance, replacing the data it covers there. That matters most for a team that builds content types in development, tests them in staging and publishes to production, because each promotion depends on whether the same schema and data arrive in the same shape. A repeatable transfer turns that promotion into a procedure someone else can rerun, review and document. Without one, the team relies on a sequence of exports, imports and hand edits that only one engineer fully understands.
When teams need it: transfer fits when content types change often, staging must reflect production content for testing, or developers and editors work in separate instances and need to move content between them on a regular cycle. A database backup fits better when you need a complete point-in-time copy for recovery or investigation, because a backup restores everything in the database, including items a transfer would leave out. A manual process, such as re-entering a handful of entries, fits when volumes are tiny and the change is a one-off that will not recur.
The overwrite decision comes first: because the target is overwritten, the first decision is which environments may act as targets at all. Staging or development are usually the normal destinations. Production should normally receive data only through a reviewed change with a named approver. Before any run, confirm that the target is the instance you think it is, take a database backup of it, and record who authorized the run. Rehearse the full transfer on a copy of production so the team can see exactly what gets replaced before the real run.
Schema matching and access are the main preflight checks: the source and target content types, components and fields must match, or the transfer can fail or change data that does not line up. Compare schema in version control before each run, and treat any mismatch as a blocker. Transfer access relies on a token configured for the receiving side, so decide who creates it, how long it lives, its permission scope and where it is stored in your secrets process. The exact command, flags, token setup and list of excluded items should be confirmed in the current Strapi 5 documentation for the version you run, because Strapi ships minor releases frequently.
Questions to settle with your team or partner: confirm the Strapi version in use, the items the transfer includes and excludes, the rollback path if a run goes wrong, and who owns each step. Ask for the written procedure, the preflight checklist and the results of a rehearsal before anyone runs a transfer into a shared environment. Illustrative example: a team promotes a new article content type from staging to production, the production copy of that type is replaced, and a backup taken beforehand is the only route back if the content must be restored.
Transfer scope options and when each fits
This table compares the choices a team makes before running strapi transfer, from full versus partial transfers to local versus remote sources and snapshots. Read each row for the situation where it fits and the risk it carries, especially overwriting editorial work on the target. Time mostly follows media volume and entry count, so confirm both before choosing a scope.
| Option | When it fits | What it risks |
|---|---|---|
| Full transfer of all content types and configuration | Promoting a tested content model and its entries from staging to a new production instance that has no live editing yet | Replaces existing target content, so any production edits made after the last sync are lost unless backed up first |
| Selected content types only | Releasing a single tested content type change, such as a new component or collection, without touching other sections | Partial schema or relation mismatches can break entries that reference types left out of the transfer |
| Including media files | Moving images and documents that entries depend on, when the target has no copies of them | Media volume drives transfer time and storage use on the target, and files can overwrite or duplicate assets already there |
| Excluding media files | Schema or entry changes where assets already exist in the target storage provider or CDN | Entries may point to missing or mismatched files if the storage location differs between environments |
| Transfer from a local instance | Developer machines pushing a prototype model to a shared staging environment | Local data is often a test set, so editors' work on the remote may be overwritten and schema drift goes unnoticed |
| Transfer between two remote instances | Staging to production promotions under a controlled release process with transfer tokens scoped to each side | Token scope and network access must be managed carefully, and both instances must run compatible Strapi versions |
| Restoring a database snapshot instead | Recovery, or cloning an environment exactly including admin users, settings and history | Snapshots bring back everything at that moment, including data and users you did not intend to move, and cover only the database unless media is copied separately |
How to prepare, run and verify a Strapi transfer
This sequence moves content and media from a source Strapi instance into a target while recording what changed at each stage, so the team can roll back if a check fails. Because the transfer overwrites target content, the snapshot and the written sign-offs come before any data is written.
Confirm versions and schema match
An engineer confirms that the source and target run the same Strapi version, the same Node.js version and the same database engine, and that content type schemas are identical. Compare the schema files in version control and the content types shown in each admin panel. Check the Strapi documentation for your version for transfer compatibility notes. This step is done when both environments report matching versions and a written list of schema differences has been reviewed by the content owner.
Create a least-privilege transfer token
Create the transfer token on the target instance with only the access the transfer requires, following the token documentation for your Strapi version. Confirm the exact token types, scopes and command flags in the docs, because they can change between releases. Store the token in your secrets manager and keep it out of shared files and chat. This step is done when a test connection succeeds and the token is limited to the target environment it was created for.
Snapshot the target database and media
Take a full backup of the target database and a copy of the media storage before anything is written. The transfer overwrites target content, so this snapshot is the only rollback path. Record the backup identifier and the media storage version in the change ticket. Restore the database backup into a scratch instance to confirm it is usable. This step is done when the restore test completes and both identifiers are recorded.
Run a dry review of differences
Run the transfer's comparison or dry-run step against the target to list schema and content differences before any data moves. Confirm the command names and options in the Strapi docs for your version. Review the output with the content owner and the developer who changed the schema, and resolve every content type or field mismatch first. This step is done when the review shows no unexpected deletions and the owners have approved the list in writing.
Execute the transfer to the target
Run the transfer from the source to the target using the token and scope reviewed in the earlier steps. Schedule the run in a maintenance window agreed with the content owners and keep the full console log. Watch for errors, and if the run fails partway, stop and restore from the snapshot before retrying. This step is done when the command exits cleanly and the log records counts for each content type and media file.
Check entry counts and media links
Compare the number of entries per content type and the number of media files on the target against the source log. Open a sample of published pages or API responses and confirm that images and files load from the target media storage, not from the source. Investigate any gap and record its cause and owner in the log. This step is done when counts match or each gap has a documented explanation and a fix assigned.
Verify relations, locales and permissions
Open entries that contain relations and confirm that the linked items resolve on the target. If internationalization is enabled, check each locale variant of a sample of entries. Confirm that public and authenticated role permissions match the reviewed configuration, and test API responses for a sample of endpoints with each role. This step is done when the sign-off checklist is complete and the content owner accepts the target in writing.
Security and operational risks of moving live data
Moving live data between Strapi instances exposes credentials, personal information and published content in several places at once. The cards below cover the controls to set before the first transfer and the operating steps that protect editors, data and rollback options during cutover.
Treat transfer tokens as scoped secrets
A Strapi transfer token authorizes data movement into or out of an instance, so store it in a secrets manager and keep it out of repositories, CI logs and shared chat. Choose the narrowest scope the transfer needs and a short lifetime that ends when the window closes. Ask how tokens are revoked and whether a revoked token stops a transfer already in progress. Confirm these details against the documentation for your installed version.
Restrict network paths between instances
Limit which hosts can reach the admin and transfer endpoints on each instance, using firewall rules, private networking or an allowlist at the load balancer. Source and target should reach each other only on the ports the transfer requires, and only during the agreed window. Keep the admin panel off public routes where your setup allows. Record the paths in the change request so the security team can verify them before and after the move.
Keep personal data out of staging
Staging copies often contain production customer records, author details or form submissions that were never meant for a less controlled environment. Before the transfer, decide which content types and media hold personal information, then filter, anonymize or exclude them. Apply the same rule when content flows back from staging into production. Confirm with your data protection lead which fields count as personal data for each content type.
Freeze editorial changes during cutover
Because a transfer replaces existing content on the destination, edits made there while data moves can be lost. Announce a freeze window to editors, block content creation through roles or a maintenance notice, and confirm nobody is mid-edit before starting. Agree who can lift the freeze and how edits made in the source during the window will be handled. Make sure the freeze covers the same period as your rollback plan.
Record who ran each transfer
A transfer changes content across environments, so the team should know who started it, from which account, with which token, and when it finished. Keep a written run record in your change system with those details and the outcome. Do not assume the admin panel or the transfer command produces a complete trail of transfers. Audit log coverage depends on your Strapi plan and version, so confirm with the vendor exactly what is recorded before you rely on it.
Keep the rollback path ready
Before cutover, confirm you can restore the target database and media files to their state from before the transfer. Take a database backup and a media copy, test the restore on a separate instance, and time it so the outage window is known in advance. Strapi's migration documentation advises backing up the database first because downgrading is not supported, and the same caution applies here. Assign an owner who can start the restore without waiting on the person who ran the transfer.
Why the target overwrite needs a rollback plan
The transfer replaces the data on the target instance with the incoming data, so the target's previous content is gone once the run completes. Treat the operation as a one-way change to the target. Running the transfer again in reverse does not restore what was overwritten. Before anyone schedules the run, the team should agree in writing which environment is the target, who approves the overwrite, and what the target holds that nobody has copied anywhere else. That last check is the one most often skipped, because editors working directly on staging or production may have created material that exists only on the target.
A rollback plan starts with two backups taken immediately before the run: a database dump and a copy of the media library. Both are required. Strapi stores entries and relations in the database, while uploaded files live in media storage. Restoring one without the other leaves records pointing at files that are missing, or files with no matching record. Take the database backup with the native tooling for your engine, whether PostgreSQL, MySQL or MariaDB, and confirm that the dump is complete and readable before relying on it. Record the snapshot time, the Strapi version and the environment configuration alongside the backups so the restore can be matched to the software that created them.
A backup that has never been restored is an assumption. Test the restore on a separate instance before the production run is approved, not on the target itself. Restore the database and media copy into an environment built from the same Strapi version and Node.js version that will be used. Start the application and check that administrators can sign in, that entry counts for key content types match the source, and that a sample of images and files loads from the restored media path. Time the restore so the team knows how long the target will be unavailable if a rollback is needed, and keep the steps in a runbook that someone other than the author can follow.
Rollback depends on restoring backups, not on reverting the software. Strapi's v4 to v5 migration documentation tells teams to back up the database first because downgrading is not supported. The same logic applies to a transfer: the way back is to restore the snapshot, not to reinstall an earlier release. Plan for the content gap as well. Anything editors create or change on the target after the snapshot is lost when the snapshot is restored, so decide before the run whether the target will be frozen, who announces the freeze, and how work done during the window will be re-entered. Ask your implementation partner or internal Strapi lead to confirm which Strapi and database versions your transfer and restore path support, and write that answer into the plan.
Limits to confirm before you plan a transfer
These checks decide whether a transfer is possible and what it will change before any plan is written. Confirm each item in the current Strapi documentation and on a test instance you control before you assume it holds.
Strapi 5 versions and minor matching
Strapi 5 minor releases ship roughly weekly, for example v5.56.0 on September 30 and v5.57.0 on October 7, 2026. Confirm in the Strapi documentation whether the source and target instances must run the same minor version. Pin both environments to one tag for test runs, and confirm that your Node.js version is on an Active or Maintenance LTS release, as the installation docs require.
Schema matching for components, zones and relations
The target must define the same content types, components, dynamic zones and relations that the transferred data references. Check how the transfer handles a component or dynamic zone that exists on only one side, and how it treats a relation whose target content type is missing or renamed. Run a small export and import on a copy of your schema and inspect the result field by field.
Draft, published and localized content
Strapi 5 stores draft and published states for each document, and localized content adds one version per locale. Confirm whether the transfer carries drafts, published versions, or both, and whether each locale moves with its parent document. Also check how entries that exist only as drafts or only in one locale appear on the target after import.
Media provider handling
Media files depend on the upload provider configured on each instance. Confirm whether the transfer copies media files or only the records that point to them, and how your provider, whether local storage or an object storage provider, resolves those files on the target. Check that the target has write access and sufficient storage before the import starts.
Database engine support
Strapi 5 supports PostgreSQL 14 or later, MySQL 8.0 or later, MariaDB 10.3 or later and SQLite 3. It does not support MongoDB or other NoSQL databases. Confirm that the source and target use supported engines and versions, and test the transfer on the same engine family you run in production, since behavior may differ between engines.
Plan requirements for the feature
Strapi self-hosted plans include Community, Growth and Enterprise, and feature availability differs between them. Confirm on the Strapi self-hosted pricing page which plan includes the transfer feature for the edition you run. Ask your Strapi representative to confirm the requirement in writing if your environments use an Enterprise license or a custom agreement.
Questions teams ask before running Strapi transfers
What drives the effort of a Strapi transfer project?
The main drivers are schema differences, media volume, locales and relations, and the number of environments that must stay in sync. Content only moves cleanly when content types, components and fields match on both ends, so drift between development, staging and production usually adds the most work. Large media libraries extend copy time and need separate verification. Each locale and each relation between content types adds cases to test, because a missing referenced entry can break a page after the move. Every environment that must stay synchronized also needs its own repeatable runbook and checks. Ask any provider to walk through these four drivers against your actual instances before agreeing on scope.
Can our own team run Strapi transfers without a partner?
Yes, for simple content promotions that have a tested runbook and identical schemas on both sides. A typical example is promoting a set of entries from staging to production after a release that changed no content types. It becomes harder when schema drift exists, when custom plugins or custom APIs change what is stored, or when the team has never restored a backup to the target. A practical test is whether someone who did not write the runbook can complete a transfer in a test environment, verify the results and roll back from a backup without guessing. If that fails, a partner can help design the runbook and checks before the first production run.
What do we need to provide before a transfer project starts?
You provide test environments, backup access, content owners and a signed cutover window. A test environment should mirror the production schema, plugins and configuration closely enough that a dry run is meaningful. Your team must grant access to back up the target database and media storage and confirm that a restore has been tested. Named content owners need to freeze edits during the cutover, or the team must agree how late edits will be handled. Someone accountable for the business must sign off on the cutover window, because the target overwrite is destructive. Access to the code repository that holds schema and plugin definitions is also needed.
How is the cost of a Strapi transfer engagement determined?
A quote follows from a written scope, and DeployOpen does not publish a price list. The scope lists the environments involved, content types, locales, media volume, custom plugins, test rounds and cutover support. Most engagements are fixed-scope, so deliverables and timing are agreed in writing before work starts. One-time costs cover analysis, runbook design, dry runs and the cutover itself. Recurring costs appear only if you add ongoing support or retainers. Separately, your Strapi licensing or hosting costs depend on the plan you choose, so review Strapi's self-hosted pricing page for plan details. When you request a quote, ask which items are one-time, which recur and what changes the price if scope grows.
Which Strapi plan features does a transfer workflow depend on?
Confirm the plan requirements against Strapi's current documentation and pricing before you commit. Strapi's self-hosted pricing lists content history and releases from the Growth plan, and audit logs and review workflows as Enterprise features. If your transfer process depends on any of these, such as keeping an audit trail of who changed content before a cutover, check that your plan includes it. The transfer itself is a command-line process, so do not assume that a plan feature is needed for it. Ask your implementation partner to state which features the runbook uses, and to note any step that changes if you later move to a different plan.
What usually goes wrong during a Strapi content transfer?
The most common failures are schema mismatches, missing media, broken relations and an overwrite without a verified backup. A content type or component that differs between environments can reject entries or silently drop fields. Media files may not follow the entries, so images point to paths that no longer resolve. Relations can break when referenced entries are outside the transfer. Locale fields that do not match cause missing translations. Because the transfer overwrites data on the target, a missing or untested backup turns a small error into a data loss event. After each run, compare entry counts, sample published pages and check media links before declaring the cutover complete.
Should we run transfers before or after a Strapi 5 upgrade?
Align schemas on the same Strapi version first, then run transfers. Strapi v4 reached end of life on April 30, 2026, so teams still on v4 should plan the move to Strapi 5 as a separate project. Strapi 5 replaces the Entity Service API with the Document Service API and changes the API response format, so environments on different major versions are a poor basis for a content transfer. Back up the database before any migration, because Strapi's migration documentation states that downgrading is not supported. Confirm the exact transfer behavior between your versions in the current Strapi documentation, and ask your partner to test it in a non-production environment first.
How DeployOpen scopes and delivers Strapi environment transfers
DeployOpen plans and implements Strapi data transfer between environments inside infrastructure you control, so content, media and configuration move between development, staging and production under rules your team agrees in advance. Engagements are fixed-scope, with the transfer path, schema checks and handover agreed in writing before work starts.
How we scope
- We inventory the development, staging and production instances, their Strapi versions and database engines before naming a transfer path.
- The written scope lists which content types, media, and configuration items move, and which stay environment-specific.
- We agree who approves each overwrite on the target instance and where transfer tokens are issued, stored and revoked.
How we build
- We align content type schemas between source and target so the transfer compares matching definitions before any data moves.
- We configure transfer tokens with the minimum access each run needs, then test a full cycle in a non-production copy.
- We document the destructive overwrite step with backup and rollback checkpoints, and run a rehearsal before the first production transfer.
How we hand over
- You receive a runbook covering the transfer command, token handling, pre-transfer backups and the list of items that are not copied.
- We provide a verification checklist that compares record counts, media files and key entries on both sides after each transfer.
- Your team walks through a live transfer with us so operators can repeat the process without outside help.
How we support
- Ongoing support, upgrades and testing are available as a retainer if your transfer process needs regular maintenance.
- Retainer scope covers Strapi minor version changes that affect transfer behavior, reviewed against the release notes before adoption.
- Confirm with us in the quote how token rotation, schema drift checks and incident response are handled after go-live.
