Safety and records
How Neo stores information
Where Neo keeps its records and how developers change that structure safely.
Runtime contract
PostgreSQL is required for local development, every automated test, and production. AppDatabase exposes async query, queryOne, execute, transaction, withAdvisoryLock, and close. Tests use disposable PostgreSQL schemas and application SQL uses PostgreSQL-numbered parameters.
SQLite is not an application or test database. It remains available only to the historical one-way migration-source reader.
Schema domains
| Domain | Representative tables |
|---|---|
| Identity and audit | users, addresses, merchants, stores, audit_logs |
| Commerce | products, product_variants, inventory_ledger, carts, cart_items, orders, order_items |
| Conversation | chat_sessions, message_events, conversation_decisions, conversation_goals, pending_actions |
| Durability | inbox_events, outbox_commands, sequence and rate-limit tables |
| Trust | Reviews, return cases, private uploads, privacy requests, and support cases/events |
| Finance | Accounts, journals, payouts, recipients, attempts, evidence, reserves, negative balances, and reconciliation periods/cases |
| Provider safety | Certification runs, checks, revocations, catalogue mappings, and callback evidence |
Important invariants
- Unique provider event and business idempotency keys.
- One active cart per buyer/merchant/channel.
- One open pending action by type and conversation.
- One open support case per conversation and one open privacy deletion request per phone.
- One active payout recipient/account where required.
- Append-only inventory, audit, certification, reconciliation evidence, and financial journals.
- Partial indexes express active/open uniqueness without deleting history.
- Advisory locks serialize conversations, inventory-sensitive workflows, recipients, payouts, certification, and reconciliation.
Migration guide
npm run db:start
npm run db:migrate
npm test
POSTGRES_DATABASE_URL=postgresql://... npm run db:migrate:postgresMigrations are ordered SQL files in db/migrations. New migrations target PostgreSQL, preserve existing data, and add deterministic tests. Never rewrite a migration that has shipped; add a later migration.
The SQLite-to-PostgreSQL copy command is a historical controlled cutover tool with dry-run and apply modes. It validates counts, checksums, foreign keys, money, inventory, and queue sequencing. It is not a runtime or synchronization service.
Evidence and tests
src/db.tssrc/migrate.tssrc/postgres-migrations.tssrc/database-copy.tsdb/migrations/test/migration-sql.test.tstest/phase2-postgres-runtime.test.ts