Refresh the local database seed

A staging refresh replaces the primary local seed. It is different from creating or restarting a worktree. Do not overwrite an active worktree database or refresh while its source database is being used for seeding.

Manual procedure with a known restore inconsistency. The current sync script can exclude parent image data while retaining dependent rows, and ordinary exit success is not sufficient evidence of a complete restore. Unattended refresh is deferred until this is fixed.

Connect read-only to staging

From the Mac:

ssh -t shipyard 'spot db proxy --instance api-db-staging --port 54322'

Keep the proxy session open while needed. The listener is Shipyard loopback 54322. Database spotai, IAM username akshat-shipyard@test-ai-243511.iam, no database password. The key is local to Shipyard; do not copy the Mac’s broad credentials.

Prepare before a refresh

1. Stop or coordinate local consumers of the primary seed; preserve a restorable local backup if it contains work worth retaining.
2. Inspect the current repository’s scripts/sync-database.sh and private source/target .db.env files locally. Confirm the target is local and the source is staging. Never print the complete environment files into chat or commit them.
3. Confirm how the script handles exclusions and failures. Use PostgreSQL ON_ERROR_STOP and shell pipefail where the invocation supports them; inspect the script before choosing the exact invocation.
4. Resolve the excluded agentTrainingImages / dependent-image-row inconsistency before declaring a refresh routine. Do not blindly replay the original one-off deletion counts.

Completion checks

Validate schema/constraint states, indexes and migration ledgers against the intended source. The original source itself contained NOT VALID constraints, so compare states instead of assuming all must be valid. Check restore logs privately for failures. Reconcile local SpiceDB relationships and overwrite copied revision tokens through the reviewed lifecycle. Historical ClickHouse/analytics data requires separate backfills.

Stop the proxy when finished. Dumps contain staging data and stay private. The original local seed was validated; this document deliberately does not turn a partially repaired one-off procedure into an unattended recipe. Database recovery.