Start here
0.15.9 Migration Guide
Review hook calls for rejected transactions, queued create errors, atomic bulk rollback, and two database migrations before you upgrade to Blnk v0.15.9.
This guide covers the changes you need to review when upgrading to Blnk v0.15.9.
Review this guide before you upgrade if your app uses POST_TRANSACTION hooks, creates queued or bulk transactions, matches bulk failure messages, or reads historical balances. Each section links to the Core 0.15.9 code or test that shows the behavior.
At a glance
| Change | Who is affected? | What changed |
|---|---|---|
| Database migrations | Everyone | Two migrations run with blnk migrate up. |
| Hooks for rejected transactions | Apps with POST_TRANSACTION hooks | Hooks now also run when a transaction is rejected. |
| Queued create errors | Apps that create queued transactions | A used reference or unknown balance now returns an error instead of 201. |
| Atomic bulk rollback | Apps that send atomic bulk requests | Queued atomic batches now roll back when a worker rejects an item. Handle the new batch failure event idempotently. |
| Monitor updates | Apps that update balance monitors | A PUT changes only the fields you send. |
| Negative split distributions | Apps that send split transactions | A negative distribution is rejected. |
| Balance history | Apps that read historical balances | Backdated transactions are now counted correctly. |
Database migrations
0.15.9 adds a column that balance history uses, and drops four database triggers that Blnk no longer uses.
What to do:
- Pause transaction submissions and let queued jobs finish.
- Stop the old API and every old worker. A 0.15.8 worker does not check whether a queued atomic batch has failed, so it can apply items that 0.15.9 would reject.
- Back up the database and run
blnk migrate up. The bundled Docker Compose file runs it on start. - Start the 0.15.9 API and workers.
The trigger migration sets a 3-second lock timeout so it fails instead of blocking writes. If it times out, wait for long-running queries to finish and run it again.
Both migrations have down steps. The trigger down step recreates the triggers. The snapshot down step drops last_tx_seq, so snapshots taken on 0.15.9 lose it. Test a rollback on a copy of your database first.
Hooks for rejected transactions
From 0.15.9, a rejected transaction calls your POST_TRANSACTION hooks. data.status is REJECTED, and data.meta_data.blnk_rejection_reason says why.
{
"transaction_id": "txn_aa13b549-c278-47ee-87d7-2e2cfcad99ce",
"hook_type": "POST_TRANSACTION",
"data": {
"status": "REJECTED",
"meta_data": {
"blnk_rejection_reason": "failed to apply transaction to balances: insufficient funds in source balance"
}
}
}
What to do: Check data.status before your hook acts on the call. See Transaction hooks.
Queued create errors
Blnk now saves a queued transaction before it answers. A used reference returns 409 TXN_DUPLICATE_REFERENCE, and an unknown balance returns 404 BAL_NOT_FOUND. Before, both returned 201 and the transaction was never recorded.
What is saved depends on the request:
| Request | What Blnk keeps after the error |
|---|---|
| Single transaction | Nothing. The new attempt has no transaction or REJECTED record. On 409, the original transaction with that reference is unchanged. |
| Bulk request | The items before the failing one. They were already queued and still process, even with atomic: true. Items after it are not saved. |
| Split transaction | The legs before the failing one, saved as QUEUED. Queue recovery picks up QUEUED rows after about 2 hours and can apply them. |
What to do: On 409, look up the original reference instead of retrying. On 404, fix the balance ID before retrying. After a failed bulk request or split, check each reference before you resend anything. See Reconcile a queued batch after a duplicate reference.
Atomic bulk rollback
From 0.15.9, when a worker rejects an item in a queued atomic: true batch, Blnk refunds applied items or voids inflight items and emits one bulk_transaction.failed event for the batch. Blnk records the items still waiting in the queue as REJECTED when it reaches them. Before, only skip_queue: true rolled back.
If Blnk finds a duplicate reference while adding items to the queue, items already queued may still process, even in an atomic batch. Reconcile by batch ID and reference before resubmitting any items. See Reconcile a queued batch after a duplicate reference.
The failure message now says how many items were refunded, instead of All transactions in this batch have been refunded.
What to do: Listen for bulk_transaction.failed and deduplicate it on data.batch_id. Blnk queues one event per batch, but webhook delivery can repeat. If your code matches the old message text, match the event instead. See Bulk transactions.
Monitor updates
From 0.15.9, PUT /balance-monitors/{monitor_id} changes only the fields you send. A partial body used to fail with 500.
What to do: If your app sends precision without value, include value in the same request to change the scale. If your app does not send precision alone, no change is required. See Update balance monitor.
Negative split distributions
A negative distribution used to be accepted, and the "left" leg received the difference. From 0.15.9, negative distribution and precise_distribution values return 400 TXN_VALIDATION_ERROR; no balance moves.
What to do: Send 0 or a positive value for each leg. See Split transactions.
Balance history
Balance history could miss a backdated transaction or count a future-dated one twice. From 0.15.9, each transaction is counted once, at its effective_date.
Snapshots taken before the upgrade are skipped until new ones replace them. from_source=true results do not change.
What to do: Expect some past balances to change. If you store history results, read them again, and take a snapshot after you upgrade. See Historical balances.
Core release references
- Queued atomic rollback and final item states, worker rollback event timing, and the enqueue loop that stops at the first failure.
- Queued create status and record tests, split legs saved one by one, and queue recovery of stuck
QUEUEDrows. - Rejected transaction hook test.
- Precision-only monitor update test and negative split validation test.
- Historical balances with legacy snapshots, backdated transactions, and future-dated transactions.
- Snapshot migration SQL and trigger migration SQL. The release CI test run applied the migrations and passed these Core tests.