Migrations

Every alembic migration lives under apps/ledger/alembic/versions/. This page tracks the concepts, not specific revision IDs.

The chain (grouped by concern)

Group	What	Both books?
Core schema	transactions, journal_lines, accounts, customers and standard indexes	✓
UAE evolution	Cash-request tables, snapshot tables, reconciliation-variance tables, misc. extensions	✓
Source widening	Widen source CHECK (add VIEWTRADE, GLOMOPAY); add customers.viewtrade_account_refs, pan, partner_id	✓ (India-relevant, safe on UAE)
lrs_remittances	Create the LRS snapshot table	✓ (stays empty on UAE)
LRS refs	Add remittance_information, reference_number	✓
LRS payment / settlement	Add payment_id, funds_available, settlement_id, settlement_utr, settled_on	✓
LRS credited signal	Add credited_to_beneficiary	✓
LRS actual TCS	Add tcs_amount_inr, purpose_code	✓
dividend_events	Dividend sub-ledger	✓ (stays empty on UAE)

Bold rows are India-relevant. Every one is safe on UAE — either shared, or the added tables / columns stay empty there.

Adding a new migration

1. Create apps/ledger/alembic/versions/NNNN_<slug>.py.
2. Write upgrade() and downgrade() — always include the downgrade, always idempotent (IF EXISTS / IF NOT EXISTS).
3. If the migration adds a table both books will use, no per-book difference needed. India-only tables still create on UAE (empty is fine).
4. Apply locally:

   docker compose --env-file .env.compose -f docker-compose.dev.yml \
     up migrate-ind migrate-uae --no-deps

5. Add tests. If the migration affects a query, add a test that runs against a fresh DB.
6. On staging / prod, migrations run on boot.

Rolling back

docker exec valura-ledger-ind alembic downgrade -1
docker exec valura-ledger-uae alembic downgrade -1

Both books must be on the same head at all times.

Data migrations

op.execute("UPDATE ...") supports it. Use sparingly; big backfills should be a separate script (scripts/backfill_*.py) so they can be chunked and monitored.

Checking current head

docker exec valura-ledger-ind alembic current