[v0.5.50] — Migration Safety & Correctness

[nagarjuna-tella]

Migrations are the one place where a framework bug doesn't just cause an error — it corrupts your data or leaves your schema in an unknown state. v0.5.50 is entirely focused on making that surface safe.

This is not a features release. It's a correctness release. If you're building on Aksara, this is the one you want in production before v0.6.0.

---

What Changed

Transactional execution
Python migrations now run inside a single transaction. The migration record is written inside the same transaction as the migration operations — so a failed migration doesn't leave a tracking row behind claiming it succeeded. SQL files are split and executed statement-by-statement inside a transaction.

Advisory locking
PostgreSQL advisory locking now prevents concurrent migration runners from applying the same migrations simultaneously. If you're running migrations in CI and a developer runs them locally at the same time, they won't step on each other.

Checksum verification
Aksara now records a checksum when a migration is applied and verifies it before running pending migrations. If you edit an already-applied migration file, the mismatch is caught before anything runs. Line endings are normalised before hashing so you don't get false mismatches across platforms. Legacy rows without stored checksums are still compatible — they warn instead of blocking.

Circular dependency detection
The migration graph now detects circular dependencies explicitly instead of silently producing an invalid execution order.

Safer SQL parsing
The SQL migration parser now handles multiple statements per line, semicolons inside strings, quoted identifiers, dollar-quoted blocks, and CRLF line endings correctly. Unterminated strings, blocks, and comments fail fast instead of producing invalid SQL silently.

SQL generation guardrails
Generated constraint names are quoted, length-bounded, and hash-suffixed when they would exceed PostgreSQL's identifier limits. Partial-index predicates, ArrayField types, NUMERIC/DECIMAL/VARCHAR precision forms are all validated more accurately.

Cleaner failure output
Failed migration runs now report which pending migrations were skipped. CLI errors for expected graph and load failures surface cleanly instead of leaking raw tracebacks. Advisory-lock contention guidance now correctly explains how to identify a stuck backend.

---

What This Doesn't Include

Deliberately deferred for a later design pass:

• Migration metadata schema versioning
• Checksum backfill for legacy rows
• app_label / name identity split
• Dedicated migration verification command

These are documented as deferred, not forgotten.

---

Validation

• Full DB-backed suite passing
• Migration suite passing
• Security suite passing
• Diagnostics suite passing
• MkDocs strict build passing
• pip-audit clean — no known vulnerabilities
• Release Gate passing on main

---

Install

pip install aksara-framework==0.5.50

Upgrading from an earlier version? Run in a development or CI database first:

aksara migrate --dry-run
aksara migrate

If you have existing migration history, review any checksum warnings carefully. Legacy rows without stored checksums are allowed — but if a stored checksum doesn't match, that means a migration file was edited after it was applied. That's worth knowing before you run anything.

---

No production-readiness claim is introduced by this release. Aksara remains pre-1.0.

---

This discussion was created from the release [v0.5.50] — Migration Safety & Correctness.