nkapp backup / restore

Nanokit’s backup system provides manual and automatic database backups for self-hosted databases, local filesystem storage, and S3-compatible object storage.

Managed provider-snapshot backups (e.g. Neon) are planned (roadmap.v3) and not selectable today — see Providers → Roadmap.

Usage

# Take a manual backup
nkapp backup [database] [options]
 
# List the backup catalog
nkapp backup list [options]
 
# Restore from a backup
nkapp restore <database> --backup <id|latest> [options]

Commands

nkapp backup [database]

Take a manual backup of a database. When [database] is omitted, defaults to the first configured database in nanokit.yml.

nkapp backup app -e production
nkapp backup app -e production --note "before schema migration"

Options:

On success, prints the backup ID, compressed size, and storage location.

nkapp backup list

List the backup catalog for an environment, newest first.

nkapp backup list -e production
nkapp backup list -e production --database app

Options:

nkapp restore <database>

Restore a database from a backup.

nkapp restore app --backup latest -e production
nkapp restore app --backup bk_20260613_030012 -e production -y

Options:

Safety: before overwriting the database, restore automatically takes a pre-restore safety backup so you can undo the restore if needed.

[!IMPORTANT] Phase 1 — in-place only. Restore currently overwrites the live database in place (--in-place). Restoring into a new, isolated database branch is planned but not yet available.

Backup Mechanism

The mechanism is selected per-database based on the engine and provider:

All dump-based backups are:

• gzip-compressed before storage.
• SHA-256 checksummed — the checksum is verified before any restore is applied.
• Optionally age-encrypted (see encryption config below).

Storage Targets

Backups can be stored on the local filesystem (default) or an S3-compatible object store.

Configuration (nanokit.yml)

Backup Targets

Define one or more named storage destinations at the top level:

backupTargets:
  primary:
    type: s3            # local | s3
    bucket: nk-backups
    region: eu-south-1
    prefix: my-project
    # For non-AWS S3-compatible stores, supply an endpoint:
    # endpoint: https://nyc3.digitaloceanspaces.com
    # Credentials are read from the environment or a vault:// reference —
    # never put plaintext secrets in nanokit.yml.
    # AWS S3:       AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY
    # DO Spaces:    SPACES_ACCESS_KEY / SPACES_SECRET_KEY

Per-Database Backup Config

databases:
  app:
    engine: postgres
    backup:
      enabled: true
      target: primary          # references a key in backupTargets
      mechanism: dump          # dump | both  (snapshot is neon-only — planned, roadmap.v3)
      schedule: "0 3 * * *"   # cron expression — automatic scheduled backups
      retention:
        keep_last: 7           # keep the N most recent backups
        min_keep: 3            # always keep at least this many regardless of age
      encryption:
        mode: age
        key: vault://secret/nk/backup-key   # never inline the key
      preDeploy: true          # take a backup before every nkapp deploy / up

Full Example

backupTargets:
  primary:
    type: s3
    bucket: nk-backups
    region: eu-south-1
    prefix: my-project
 
databases:
  app:
    engine: postgres
    backup:
      enabled: true
      target: primary
      mechanism: dump
      schedule: "0 3 * * *"
      retention: { keep_last: 7, min_keep: 3 }
      encryption: { mode: age, key: vault://secret/nk/backup-key }
      preDeploy: true
 
  cache:
    engine: redis
    backup:
      enabled: true
      target: primary
      mechanism: dump
      # Note: redis restore is not yet available (see Limitations)

Backup Modes

Manual

Use the nkapp backup and nkapp restore commands to trigger backups and restores on demand (see Commands above).

Automatic — Scheduled (schedule)

When a schedule cron expression is set, Nanokit runs backups on that cadence. Retention rules (keep_last / min_keep) are applied after each scheduled run.

Automatic — Pre-Deploy (preDeploy: true)

When preDeploy: true is set, Nanokit takes a backup of the database before the reconcile phase of nkapp deploy or nkapp up. This gives you a safe rollback point before schema migrations or service changes are applied.

Hub Integration

All backup operations are also available in the Hub → Backups panel:

• Browse the full backup catalog with metadata (size, timestamp, note, checksum status).
• Backup now button — triggers a manual backup for any configured database.
• In-place restore — select a backup and restore with a single click (same safety-backup flow as the CLI).
• Last-backup-age indicator — at-a-glance freshness status per database.
• Per-database backup config and backup-target management UI.

Limitations (Phase 1)

The following are known limitations of the current implementation:

• Restore is in-place only. --in-place is the only available mode. Restore into a new isolated database branch is planned.
• Redis restore is not yet available. Dump (snapshot export) works, but restoring from a dump is not yet implemented.
• MySQL restore is not yet available via nkapp restore. Manual restore can be performed with nkapp shell.

See Also

• nkapp db — database branching, forking, and context switching
• Databases — database configuration reference