Database Migration Plan

This is a future planning document. Vorliq has not migrated to PostgreSQL and production still uses hardened JSON as the source of truth.

Pre-Migration Rehearsal

1. Verify the latest JSON backup and storage health.
2. Run python tools/postgres_schema_check.py.
3. Run python tools/migration_dry_run.py --output migration-dry-run-report.json.
4. Run python tools/simulate_postgres_import.py --input migration-dry-run-report.json --output import-simulation.json.
5. Run python tools/run_shadow_migration_rehearsal.py --data-dir tests/fixtures/migration/sample_data --database-url "$SHADOW_DATABASE_URL" --check-adapter --output temp-shadow-report.json against a local or CI-only shadow database.
6. Compare counts, latest block hash, and public API behavior in a staging environment.

Future Migration Window

A future migration window should pause writes, snapshot JSON, run a final dry run, import into a managed PostgreSQL instance, run parity checks, switch a staged adapter, smoke test public routes, then cut traffic only after readiness passes. This release does not perform that cutover.

Adapter Gates

Until a future approved cutover, production must keep VORLIQ_STORAGE_BACKEND=json. The PostgreSQL adapter may be exercised only in non-production shadow tests with VORLIQ_ALLOW_EXPERIMENTAL_POSTGRES=true and VORLIQ_POSTGRES_SHADOW_ONLY=true, and readiness must show postgres_adapter_enabled: false and postgres_write_mode: disabled.

Block Hash Preservation

The import must store original raw block JSON and raw transaction JSON. It must not normalize historical blocks in a way that changes block hash inputs or transaction ordering.

Managed Database Recommendation

Use a managed PostgreSQL provider with point-in-time recovery, encrypted backups, monitoring, read replicas if needed, and a tested restore workflow. Do not store server-side private wallet keys.

Exit Criteria

• Dry run status is ok or warnings are explicitly accepted.
• Import simulation passes ordering checks.
• Shadow migration rehearsal passes count, block hash, transaction ID, balance, and secret-scan parity checks.
• PostgreSQL adapter read parity passes against the shadow database while default writes remain blocked.
• Chain height and latest block hash match JSON.
• Explorer, account, transaction, leaderboard, readiness, health, audit, and SDK smoke tests pass.
• Rollback plan has been rehearsed.