Transaction retry in Ballerina 2201.x: work that falls outside the transaction manager

Direct Answer

In Ballerina Swan Lake 2201.x, only database clients explicitly documented as transaction-aware (e.g., mysql:Client, postgresql:Client) enroll in the transaction manager. HTTP calls, file I/O, and message publishes (Kafka, RabbitMQ, NATS) execute immediately and are never rolled back. A retry clause re-runs the entire transaction block, so any non-participating side effect inside the block runs again — at-least-once semantics with no automatic compensation.

Confirmed Participation Rules

• Participates: JDBC-based clients (mysql:Client, postgresql:Client) when invoked inside a transaction block; transactional named workers extend this across strands.
• Does not participate: http:Client calls, file:* writes, outbound messaging producers, any connector without explicit transaction enrollment in its 2201.x documentation.

Assume non-participation unless the connector's release notes for your exact 2201.x patch version state otherwise.

Retry Guarantees for Non-Participating Effects

When retry triggers (e.g., on a transient DB deadlock), the whole block re-executes. Effects from non-participating clients are not undone by the prior rollback and are re-issued on retry. This yields at-least-once delivery. The language provides no built-in deduplication or compensation.

Mitigation Patterns (Application-Level)

1. Transactional outbox: Write the intended side effect (e.g., message payload) as a row inside the transaction; publish asynchronously after commit via an on-commit handler or separate worker.
2. Idempotent receivers: Design consumers to deduplicate using a business key carried in the payload.
3. Move effects after commit: Place HTTP calls or file writes in an on-commit clause (runs after successful commit) or after the transaction block — but note on-commit is not itself transactional; a crash between commit and handler loses the effect.

Verifying Post-Rollback State

To confirm a rollback left no committed rows, you must read outside the transaction:

// Inside transaction - rolled back
transaction {
    dbClient->execute("INSERT INTO t VALUES (1)");
    // force rollback
    rollback;
}

// Verification: NEW client, NO transaction block
mysql:Client verifyClient = check new (url);
stream<record {}> rows = verifyClient->query("SELECT * FROM t WHERE id = 1");
check rows.hasNext() == false; // Confirms no committed row
verifyClient.close();

Use the database's default isolation (typically READ COMMITTED). Reading inside the same transaction sees its own uncommitted/rolled-back view and proves nothing.

One Diagnostic Detail

Which exact 2201.x patch version (e.g., 2201.4.1, 2201.6.0) and which connector versions are in your distribution? Enrollment behavior can differ across patch releases; confirm against the connector docs for that version before assuming uniform participation.