Your first archive
Configure a source, preview a policy, run a bounded export and verify it.
Before you start
This reference covers the current 0.1.1 development workspace. Download a verified Windows x64 or Linux x64 release, then install an approved connector for your database. The base CLI does not include database drivers. Match the connector version to available signed release metadata; local development may be ahead of published assets. The walkthrough uses PostgreSQL public.orders with a single integer primary key and created_at timestamp. MySQL and MongoDB have the limits described in Supported databases.
coldctl --version
coldctl --help1. Initialize local state
init creates or upgrades local SQLite state. Use the same --data-dir for every command if you override the OS default. Stop existing workers before migrations.
coldctl init
coldctl statusInstall the database connector
Obtain root.json and its independently verified SHA-256 fingerprint from your release trust process. Replace VERIFIED_FINGERPRINT and RELEASE_VERSION. Download verification and offline installation are covered in Connector installation.
coldctl connector registry --url https://github.com/coldctl/coldctl/releases/latest/download/ --root root.json --root-sha256 VERIFIED_FINGERPRINT
coldctl connector install postgres --version RELEASE_VERSION
coldctl connector doctor2. Register and inspect a source
Set ARCHIVE_DB_PASSWORD through your environment or secret manager. Do not put a password in --url. The PostgreSQL role needs only the source privileges described in your deployment setup; source discovery/export are read-only.
coldctl source add postgres --name production --url "postgresql://archive_reader@db.example.com:5432/app" --password-env ARCHIVE_DB_PASSWORD
coldctl source test production
coldctl source discover production
coldctl analyze production3. Choose local storage
The directory is customer-controlled. destination test creates it if missing and performs a temporary write/read/delete probe. S3, Azure Blob and Google Cloud Storage are also supported; see Customer-owned archive destinations and Cloud storage authentication. Use the chosen destination name in your policy.
coldctl destination add local --name local-archive --path ./archives
coldctl destination test local-archive4. Define and preview the policy
This example selects records older than 365 days whose status is completed. Saving a policy does not validate the table. Planning reads metadata and estimates; it does not run exact counts or create archive files.
coldctl policy create --name orders-archive --source production --destination local-archive --schema public --table orders --time-column created_at --older-than-days 365 --equals-column status --equals-value completed --batch-size 500
coldctl policy validate orders-archive
coldctl archive plan orders-archive5. Export a bounded trial
Only assert immutable-rows when both row values and eligibility are stable, including no backdated inserts. The 1000-row invocation budget may leave a paused job; inspect its returned status. The source records are retained.
coldctl archive run orders-archive --source-stability immutable-rows --max-rows 1000
coldctl jobs list6. Resume and verify
Replace JOB_ID with the job UUID from jobs list. For a paused/incomplete job, first confirm the original stable source, then resume. --max-rows 0 removes the saved row budget. Verify requires a completed job.
coldctl jobs show JOB_ID
coldctl archive resume JOB_ID --confirm-original-source --max-rows 0
coldctl archive verify JOB_ID7. Observe in Cloud
Create a lifecycle token in Cloud Settings / Agent tokens and supply it as COLDCTL_CLOUD_TOKEN. Inspect the dry run before upload. Use your actual HTTPS Cloud origin; refresh the console after sync. No database rows are uploaded.
coldctl agent sync --dry-run
coldctl agent sync --cloud-url https://console.example.comContinue with long-running work
Use the durable local scheduler for an archive that needs multiple invocations. Add --delete-after-archive only when you explicitly authorize verified source deletion and have granted its required permissions. Archive-only is the default.
coldctl agent scheduler enqueue orders-archive --source-stability immutable-rows --confirm-original-source
coldctl agent scheduler run