Export and import

move committed events between Chronacta instances or streams without opening the data directory directly.

gRPC (`IntegrationService`)

ExportStream(stream_id, from_version) — server stream of StoredEvent
ExportAll(from_position) — server stream ordered by global position
ImportEvents(client stream) — send ImportOptions once, then event records; returns summary

Permissions: export → stream.read, import → stream.append.

JSONL file format

One JSON object per line (CLI default when -format jsonl):

{
  "format_version": 1,
  "stream_id": "orders-1",
  "event_type": "OrderCreated",
  "data": {"order_id": "1"},
  "metadata": {},
  "schema_name": "",
  "schema_version": 0,
  "source_event_id": "uuid-from-export",
  "idempotency_key": "",
  "source_stream_version": 1,
  "source_global_position": 42
}

source_* fields are informational. Import assigns new stream versions and global positions.

Binary file format

Magic header EVFX (8 bytes: magic uint32, format version uint16, reserved uint16), followed by length-prefixed records. Each record payload is JSON with the same fields as JSONL.

Use -format binary on export; import accepts -format auto (default) and detects binary by magic.

[EVFX header 8b][uint32 len][json payload][uint32 len][json payload]...

Duplicate policy

Policy	Behavior
`reject_existing_stream` (default)	Error if the target stream already exists before import
`append`	Append with `ExpectedVersionAny`
`skip_by_event_id`	Skip when `source_event_id` is already in the stream

dry_run=true validates and counts without appending.

Import never silently overwrites an existing stream under the default policy.

CLI workflow

# Export one stream (JSONL default)
./bin/chronacta export stream -stream orders-1 -output orders.jsonl

# Export binary (smaller/faster for large migrations)
./bin/chronacta export stream -stream orders-1 -output orders.bin -format binary

# Import with auto-detect
./bin/chronacta import -file orders.bin -duplicate-policy reject_existing_stream

Example binary

With a running server:

./bin/chronacta-example-export-import

Uses CHRONACTA_SERVER (default 127.0.0.1:2113).

Binary export/import is available via -format binary. NATS bridge is enabled with CHRONACTA_NATS_URL — see nats-bridge.md. Append idempotency keys are documented in duplicate-policy.md.