Export & Import¶

database_export.py and database_import.py move a database’s contents through an open, human-readable JSON bundle. Together they give you a backup-and-restore path, a diff-and-inspect surface, and — above all — the guarantee that your data is never trapped in an opaque binary file: it round-trips through a format you can read, store, and rebuild from without a proprietary reader.

Tool	Direction	Produces / consumes
database_export.py	database → JSON	an export bundle (a directory)
database_import.py	JSON → database	a fresh `Database` / `CommitDatabase`

Note

The round-trip is state-level, not history-level. Exporting a CommitDatabase captures its materialised state at one commit — not the commit DAG. Re-importing builds a brand-new database whose history starts at a single import commit. Use export/import for portability and backup of a state, not to preserve or transfer commit history (for that, synchronise against a commit server).

database_export.py¶

Serialise a Database or CommitDatabase to a JSON bundle — embedded definitions, one document file per attachment, and blobs with their layouts.

# Plain Database — exports the current state
python3 tools/database_export.py project.vpr

# CommitDatabase — --commit-id is required (last / first / <id>)
python3 tools/database_export.py project.cdb --commit-id last

# Custom output directory
python3 tools/database_export.py project.cdb --commit-id last --output backup/

Options¶

Option	Description	Default
`--commit-id`	Commit to export (`last`, `first`, or an id) — required for a `CommitDatabase`, ignored for a plain `Database`	-
`--output`	Output directory	`<name>.export`
`--indent`	JSON indentation	`2`
`-v`	Report what was written	quiet

Bundle layout¶

The export directory is self-describing:

<name>.export/
├── manifest.json      # kind, commit id, definitions digest, counts
├── definitions.json   # the DSM definitions, as dsm-json
├── documents/         # one JSON file per attachment
│   └── <attachment>.json
└── blobs/             # binary blobs, keyed by id

database_import.py¶

Rebuild a database from an export bundle, preserving blob ids. The target type defaults to whatever the bundle recorded; override it with --as.

# Rebuild, matching the source type recorded in the bundle
python3 tools/database_import.py project.export rebuilt.cdb

# Force a target type
python3 tools/database_import.py project.export rebuilt.vpr --as database
python3 tools/database_import.py project.export rebuilt.cdb --as commit-database

Options¶

Option	Description	Default
`--as`	Target type: `database` or `commit-database`	match the bundle
`--label`	Commit label when creating a `CommitDatabase`	`import`
`--documentation`	Override the documentation stored in the new artefact	from the bundle
`--force`	Overwrite the output file if it exists	off
`-v`	Report what was imported	quiet

Warning

Importing into a CommitDatabase creates it with a single commit (labelled import by default). The original commit history is not reconstructed — only the exported state is.