Exporting and importing
Move a realm, a database or some collections between instances as a package, seed staging with anonymized data, or extract a report.
backd export writes the documents and files of a realm to a package: a plain directory (or one .tar.gz) you can read with ordinary tools. backd import reads one into a realm, after checking all of it against the target’s own configuration. Together they are the supported way to take data out of backd, move it between instances, seed a staging copy or hand someone a report, without mongodump. They go through the admin API, so they need no access to MongoDB, or run directly on MongoDB when no server is available.
| I want to… | Read |
|---|---|
| Move an app, with its users, from one instance to another | Moving an app between instances |
| Fill a staging instance with realistic data that holds no real person’s details | Seeding staging |
| Give an analyst a table of some fields | Reporting extracts and CSV |
| Export or import with the server stopped, or read a backup | Direct mode |
| Look up the package format, every flag, the admin API or an error | Reference |
| Keep packages and keys safe | Keeping packages safe |
Export or backup?
An export is for moving data, not for recovering a deployment: it leaves out the system data a restore needs (sessions, API keys, secrets, the audit trail) and reads the collections one after another, not as one snapshot. For disaster recovery use Backup and restore; to read a backup as a package, restore it into a throwaway MongoDB and use direct mode.
At a glance
backd export --realm clinic --include auth --out ./clinic-2026-10-09 --archive
backd import --realm clinic --from ./clinic-2026-10-09.tar.gz --dry-run
backd import --realm clinic --from ./clinic-2026-10-09.tar.gz
Lossless. A package keeps ids,
_meta(creation and update times, version, owner, trash state) and files, so references and file links stay valid after an import.Validated before anything is written. An import checks the package’s checksums, then every document against the target realm’s schemas, file limits, indexes and existing documents;
--dry-runstops there.Resumable. Running a command again after an interruption finishes the job.
Audited. Every export and import is recorded (
export,importand their ends), with counts and never content.Authentication data only when asked. Users, password hashes, second factors and push devices travel only with
--include auth; secrets, sessions and tokens never do.Needs full admin access and, for a signed-in session, a fresh proof of identity. With an admin API key nothing more is asked.
Encrypted fields stay ciphertext unless you give their keys: the server never decrypts for an export. See Encrypted fields.
Export a realm with its files and users, check the import with a dry run, import it, and verify the result.
Seeding stagingTurn an export into a staging copy that holds no real personal data: erase-policy rules, an override file, a known password, and what stays.
Encrypted fieldsHow encrypted fields travel in an export: always as ciphertext, opened only by whoever holds the keys, offline if you like; what an import does with them, and how to recover after losing a realm’s secrets.
Reporting extracts and CSVExport some fields of a collection, filtered, as a CSV table for a spreadsheet: what it keeps, what it flattens and why it can never be imported.
Direct mode: without a running backdbackd-server export and import work straight on MongoDB and CONFIG_DIR when the server is stopped or unreachable: what the master key is for, and how to read an old backup.
ReferenceThe export package format and manifest, every flag of backd export and import, the admin API endpoints and what to do about each error.
Encrypted fields formatThe specification of how backd stores and exports encrypted fields: keys, wrapping, values, associated data, blind indexes and normalization, with test vectors for other tools.
Keeping packages safeWhere to keep an export package and its key, why to avoid raw keys in commands, and when to delete both.