Storage Adapters
Vorliq production storage is currently hardened JSON. This page describes the adapter boundary being prepared for a future SQLite or PostgreSQL migration. It does not mean production has migrated.
Current Adapter
The active adapter is JSON persistence under blockchain/data and backend/data. The chain uses atomic writes, backup-before-write behavior, storage health checks, audit exports, and derived read indexes. Readiness must report active_storage_adapter: json.
Interface Layer
The adapter interface lives at blockchain/storage_adapters/base.py. json_adapter.py wraps the existing hardened storage class without changing production behavior. postgres_adapter.py is available for shadow reads and tests only, and factory.py defaults to JSON.
Future Adapters
Future adapters may target SQLite for single-node deployments or PostgreSQL for managed multi-process production deployments. PostgreSQL is the preferred future production option because it provides transactional imports, JSONB compatibility, mature managed backups, replicas, and strong relational indexing. The PostgreSQL adapter is currently disabled in production and write-blocked by default. Any future adapter must preserve public API behavior, chain validation behavior, and audit export parity before it can become active.
Immutable Chain Rule
Historical chain blocks are immutable. A database adapter must store the original block fields without rewriting transactions, recalculating historical hashes, or changing proof data. Block hashes remain the compatibility contract.
Derived Data
indexes.json is a derived cache. It speeds up reads but is not source of truth. A database migration should rebuild index-style tables from confirmed chain data after import rather than treating cache data as authoritative.
Pending Transactions
Pending transactions remain separate from confirmed chain transactions. Confirmed transactions come from blocks in chain.json; pending transactions come from pending.json until mined.
Dry Run First
Operators must run python tools/migration_dry_run.py --output migration-dry-run-report.json before any future adapter cutover. The dry run reads JSON, validates chain history, counts records, and produces a table-style report without creating a database or modifying production files.
Rollback
A future migration must be reversible. Keep JSON backups and audit exports until the new adapter has passed parity checks, readiness checks, and production smoke tests. Rollback means returning to the JSON adapter with chain history intact.
Wallet Keys
Private wallet keys are never stored server-side by Vorliq. Browser and mobile wallets remain client-controlled. Storage adapters must not introduce server-side private key tables, logs, or exports.