Antfly Lite Migration

Antfly Lite and normal Antfly share the same backup-bundle envelope. Use a portable AFB2 representation for cross-engine migrations, and use .aflite as the live Lite database file.

File Roles#

• .aflite is a live embedded Lite database.
• .afb is an Antfly Backup Bundle. Its manifest explicitly identifies a portable logical or native physical representation; Lite produces and consumes the portable representation.

Normal Antfly can restore directly from a Lite .aflite input, but that path is a convenience for promotion, not a reason to treat .aflite as the long-term backup format. Direct restore opens the Lite file read-only, streams portable restore records, and restores those records into the target Antfly table.

Create .afb backups when you need archival retention, object-storage uploads, repeatable migrations, or restore artifacts that are independent of the Lite storage engine.

Lite To Normal Antfly#

Use antfly lite promote when a normal Antfly target is running:

antfly lite promote app.aflite \
  --target http://localhost:8080 \
  --table docs \
  --location file:///tmp/antfly_backups

promote opens app.aflite read-only, stages a portable backup, restores that backup into the docs table, and leaves the Lite database in place.

If --location is omitted, Lite stages the portable backup under ~/.antfly/lite/backups. Use an explicit --location when the normal Antfly target needs a shared file://, s3://, or gs:// backup location.

You can run the same flow through normal restore:

antfly restore \
  --input app.aflite \
  --table docs \
  --url http://localhost:8080

Use this direct path for one-shot promotion from an application-local database. If --location is omitted, .aflite input restore stages the portable backup under ~/.antfly/lite/backups. For repeatable release or disaster-recovery workflows, create an explicit portable backup first:

antfly lite backup app.aflite --out app.afb
antfly restore \
  --input app.afb \
  --table docs \
  --location file:///tmp/antfly_backups \
  --url http://localhost:8080

Normal Antfly To Lite#

Create a portable backup from normal Antfly:

antfly backup \
  --table docs \
  --backup-id docs-export \
  --connection archive-writer \
  --format portable \
  --out docs.afb \
  --location file:///tmp/antfly_backups \
  --url http://localhost:8080

Restore it into a new Lite database:

antfly lite restore docs.afb --out docs.aflite

Import it into an existing empty Lite database:

antfly lite init empty-docs.aflite
antfly lite import empty-docs.aflite --from docs.afb

Use replacement only when the destination database can be overwritten:

antfly lite import docs.aflite --from docs.afb --replace

Importing from another .aflite file is a physical snapshot replacement, not a logical merge. Pass --replace when the target .aflite file already exists.

This workflow is useful for local development, debugging a production slice, building fixture databases, or shipping a seeded embedded application.

What Migrates#

The portable backup stream should carry logical Antfly state:

• documents and document keys
• schemas
• index definitions
• enrichment definitions and persisted state
• caller-supplied dense vectors, sparse vectors, graph artifacts, chunks, and assets that have already been written as query-visible artifacts
• enough metadata for restore to rebuild query-visible indexes consistently

Lite is a single-node, single-shard source. Restoring into normal Antfly maps that source into the target table's placement model. Restoring from normal Antfly into Lite collapses the selected table or backup slice into one embedded database file.

What Rebuilds#

Backup and restore are logical operations, not physical file copies. Restore may rebuild storage-engine-specific files such as text indexes, dense vector/HBC segments, sparse postings, graph reverse indexes, derived checkpoints, and free space metadata.

After restore, run:

antfly lite status docs.aflite
antfly lite run-until-idle docs.aflite
antfly lite check docs.aflite

For normal Antfly targets, use the target service's status and restore verification commands. Treat the migration as complete when pending index and enrichment maintenance is drained or explicitly deferred in status.

Inference And Enrichments#

Lite does not require local inference to be configured. Migration preserves enrichment definitions and persisted artifacts, but pending inference-backed work can only run where an inference mode is available.

Common cases:

• Caller-supplied artifacts migrate as stored data and remain queryable.
• Deferred enrichment work remains pending until a remote provider, local embedded runtime, hosted maintenance worker, or normal Antfly inference service is available.
• A Lite database opened without inference should report no_inference_configured_ok: true; this is expected for embedded apps that provide their own vectors or defer model-backed work.
• Before taking a migration backup, run antfly lite run-until-idle app.aflite when you want all locally available maintenance work reflected in the backup.

Snapshots Versus Backups#

antfly lite snapshot copies a stable live .aflite checkpoint:

antfly lite snapshot app.aflite --out copy.aflite

Use snapshots for local file copies, test fixtures, or application handoff where the destination is still Antfly Lite. Use full .afb bundles for archival backups, normal Antfly restore, object-storage transfer, and cross-version migration. Choose the portable representation for Lite or cross-engine restore; choose native for fast restore into a compatible normal Antfly runtime.

Version Policy#

Lite v1 is new code. The default .aflite open path accepts the documented v1 native format or fails with an explicit error. It does not auto-upgrade pre-release directories, LSM-container prototypes, or unknown file versions.

If a pre-release Lite experiment needs to be preserved, export it with the matching development build before moving to v1, then restore the resulting portable AFB1 or AFB2 bundle.