 |
VOOZH | about |
|
VOOZH | about |
Transaction control messages enable explicit transaction management in the Bolt protocol. These messages (BEGIN, COMMIT, ROLLBACK) allow applications to group multiple queries into atomic units of work. Transaction control was introduced in Protocol V3 and is available in all subsequent versions.
Protocol V1 and V2 only support auto-commit transactions, where each RUN message executes in its own implicit transaction. For information on auto-commit vs explicit transactions, see the comparison later in this document.
The three transaction control messages are implemented as traits in the Bolt\protocol\v3 namespace and composed into protocol versions V3 through V6:
| Message | Signature | Trait | Purpose |
|---|---|---|---|
BEGIN | 0x11 | Bolt\protocol\v3\BeginMessage | Initialize explicit transaction |
COMMIT | 0x12 | Bolt\protocol\v3\CommitMessage | Persist transaction changes |
ROLLBACK | 0x13 | Bolt\protocol\v3\RollbackMessage | Discard transaction changes |
All three traits follow the same pattern: they pack a message signature, write it to the connection via $this->packer->pack() and $this->write(), and add the message to $this->pipelinedMessages array for ordered response processing.
Sources: src/protocol/v3/BeginMessage.php1-23 src/protocol/v3/CommitMessage.php1-36 src/protocol/v3/RollbackMessage.php1-36
When an explicit transaction is active, the server operates in specialized transaction states that mirror the non-transaction states:
| Non-Transaction State | Transaction State | Transition |
|---|---|---|
READY | TX_READY | begin() received |
STREAMING | TX_STREAMING | run() received within transaction |
Transaction State Transitions
The TX_READY state indicates a transaction is open but no queries are currently streaming results. The TX_STREAMING state indicates a transaction is open and at least one query has results waiting to be pulled or discarded.
Sources: src/protocol/v3/BeginMessage.php11-22 src/protocol/v3/CommitMessage.php30-35 src/protocol/v3/RollbackMessage.php29-35
The AProtocol::$openStreams property tracks the number of active result streams. Both COMMIT and ROLLBACK reset this counter to zero, ensuring proper cleanup of pending results.
When a RUN message succeeds and returns a query identifier (qid), the counter increments:
src/protocol/v3/RunMessage.php35-40
The _commit() response handler resets the counter before reading the server response:
src/protocol/v3/CommitMessage.php30-35
The _rollback() response handler similarly resets the counter:
src/protocol/v3/RollbackMessage.php29-35
openStreams Counter Lifecycle
This reset ensures that any unpulled or undiscarded results are implicitly cleaned up when the transaction ends, preventing resource leaks.
Sources: src/protocol/v3/RunMessage.php35-40 src/protocol/v3/CommitMessage.php30-35 src/protocol/v3/RollbackMessage.php29-35
The BEGIN message initiates an explicit transaction. All subsequent RUN messages execute within this transaction context until COMMIT or ROLLBACK is sent.
| Field | Type | Description |
|---|---|---|
| Signature | Byte | 0x11 |
| Extra | Dictionary | Optional transaction metadata |
The BeginMessage trait in the Bolt\protocol\v3 namespace implements the message at src/protocol/v3/BeginMessage.php9-22:
The method accepts an $extra array containing optional metadata. The array is cast to (object) for PackStream dictionary serialization. The packed binary data is written via $this->write() (defined in AProtocol), and the message type is appended to $this->pipelinedMessages for response processing.
| Parameter | Type | Version | Description |
|---|---|---|---|
bookmarks | array | V3+ | Transaction bookmarks for causal consistency |
tx_timeout | integer | V3+ | Transaction timeout in milliseconds |
tx_metadata | dictionary | V3+ | Application-level metadata |
mode | string | V4+ | Access mode: "r" (read) or "w" (write) |
db | string | V4+ | Target database name |
imp_user | string | V4.4+ | Execute as specified user |
The server responds with a SUCCESS message. The response does not include a qid field, so the openStreams counter is not incremented. The connection transitions from READY to TX_READY state.
Sources: src/protocol/v3/BeginMessage.php1-23 README.md117-123
The COMMIT message persists all changes made within the current explicit transaction. The server transitions from TX_READY or TX_STREAMING back to READY state.
| Field | Type | Description |
|---|---|---|
| Signature | Byte | 0x12 |
The message has no parameters. All transaction behavior is determined by the BEGIN extra parameters and the queries executed within the transaction.
The CommitMessage trait in the Bolt\protocol\v3 namespace implements the message at src/protocol/v3/CommitMessage.php9-23:
The response handler at src/protocol/v3/CommitMessage.php25-35 resets $this->openStreams to zero before reading the server response:
The _commit() method is invoked by AProtocol::getResponse() when processing the response queue.
A successful COMMIT returns a SUCCESS message with optional metadata:
bookmark - Transaction bookmark for causal chainingdb - Database name (V4+)If the commit fails, the server returns a FAILURE message. The transaction is implicitly rolled back and the connection enters the FAILED state, requiring a RESET message for recovery.
Sources: src/protocol/v3/CommitMessage.php1-36 README.md138-144
The ROLLBACK message discards all changes made within the current explicit transaction. The server transitions from TX_READY or TX_STREAMING back to READY state.
| Field | Type | Description |
|---|---|---|
| Signature | Byte | 0x13 |
The message has no parameters.
The RollbackMessage trait in the Bolt\protocol\v3 namespace implements the message at src/protocol/v3/RollbackMessage.php9-23:
The response handler at src/protocol/v3/RollbackMessage.php25-35 resets $this->openStreams to zero before reading the server response:
The _rollback() method is invoked by AProtocol::getResponse() when processing the response queue.
A successful ROLLBACK returns a SUCCESS message. Unlike COMMIT, rollback always succeeds even if the transaction is in a failed state, making it safe for error recovery.
Sources: src/protocol/v3/RollbackMessage.php1-36 README.md138-144
Transaction messages support pipelining, allowing multiple messages to be sent before reading responses. This optimizes network round-trips by batching operations.
Pipelined Transaction Message Flow
The $this->pipelinedMessages array (property of AProtocol) queues message types in send order. When getResponse() or getResponses() is called, the protocol reads responses in the same order and dispatches to the corresponding response handler method (e.g., _begin(), _commit(), _run()) based on the message type.
Sources: src/protocol/v3/BeginMessage.php20 src/protocol/v3/CommitMessage.php21 src/protocol/v3/RollbackMessage.php21 src/protocol/v3/RunMessage.php26 src/protocol/v3/CommitMessage.php32 src/protocol/v3/RollbackMessage.php31
The BEGIN message accepts various metadata parameters through its $extra array. These parameters control transaction behavior and are protocol-version dependent.
| Parameter | Type | Description |
|---|---|---|
bookmarks | array | Transaction bookmarks for causal consistency |
tx_timeout | integer | Transaction timeout in milliseconds |
tx_metadata | dictionary | Application-level metadata |
| Parameter | Type | Description |
|---|---|---|
mode | string | Access mode: "r" (read) or "w" (write) |
db | string | Target database name |
| Parameter | Type | Description |
|---|---|---|
imp_user | string | Execute transaction as specified user |
Sources: README.md117-123 src/protocol/v3/BeginMessage.php17-19
The Bolt protocol supports two transaction execution modes. Protocol V1 and V2 only support auto-commit, while V3+ support both modes.
When no explicit transaction is active, RUN messages execute in auto-commit mode. Each query is implicitly wrapped in its own transaction that commits immediately after the final result is consumed.
From README.md144:
runexecutes query in auto-commit transaction if explicit transaction was not open.
Auto-Commit Execution:
RUN messageREADY → STREAMINGPULL or DISCARD messageSTREAMING → READYWhen a BEGIN message is sent, all subsequent RUN messages execute within that transaction context. Changes are not persisted until COMMIT is explicitly sent.
Explicit Transaction Execution:
BEGIN messageREADY → TX_READYRUN + PULL/DISCARD sequencesTX_READY ↔ TX_STREAMING for each queryCOMMIT or ROLLBACKTX_READY/TX_STREAMING → READYTransaction Mode Comparison
The key distinction: auto-commit transactions commit after each query, while explicit transactions allow multiple queries to be grouped with atomic commit or rollback.
Sources: README.md138-144 src/protocol/v3/BeginMessage.php11-12 src/protocol/v3/RunMessage.php18-28
Transaction control messages are implemented as traits in the v3 namespace and composed unchanged into protocol versions V3 through V6. This demonstrates backward compatibility in transaction semantics.
Transaction Trait Files and Composition
The three traits are located at:
Each trait follows the same pattern: pack the signature byte via $this->packer->pack(), write to connection via $this->write(), add to $this->pipelinedMessages array. The response handler methods (prefixed with underscore: _begin(), _commit(), _rollback()) process server responses and manage the $this->openStreams counter.
Sources: src/protocol/v3/BeginMessage.php3 src/protocol/v3/CommitMessage.php3 src/protocol/v3/RollbackMessage.php3
Transaction failures can occur during any phase of the transaction lifecycle. The Bolt protocol provides mechanisms for detecting and recovering from transaction errors.
| Scenario | Server Response | Recovery Action |
|---|---|---|
| Constraint violation | FAILURE | ROLLBACK |
| Deadlock detected | FAILURE | ROLLBACK, retry |
| Query syntax error | FAILURE | ROLLBACK |
| Transaction timeout | FAILURE | ROLLBACK |
| Network interruption | Connection error | Reconnect |
When a query within a transaction fails, the server enters the FAILED state. In this state:
RESET message must be sent to return to READY stateError Recovery Sequence
For V1 and V2 protocols without explicit transactions, a RESET message is required after FAILURE:
Sources: README.md277-279 src/protocol/v1/ResetMessage.php12
The test suite demonstrates transaction rollback in BoltTest::testTransaction() at tests/BoltTest.php111-143:
The test verifies that rolling back a transaction discards all changes, including the created node.
The test suite demonstrates transactions with large data payloads in BoltTest::testChunking() at tests/BoltTest.php178-203 This verifies that PackStream message chunking works correctly within transactions:
This test validates that the PackStream chunking mechanism (with 0x0000 chunk terminators) functions correctly for large messages within transaction context.
Sources: tests/BoltTest.php178-203 README.md138-144
Transaction control messages availability across Bolt protocol versions:
| Message | V1 | V2 | V3 | V4 | V5 | V6 |
|---|---|---|---|---|---|---|
BEGIN | ❌ | ❌ | ✅ | ✅ | ✅ | ✅ |
COMMIT | ❌ | ❌ | ✅ | ✅ | ✅ | ✅ |
ROLLBACK | ❌ | ❌ | ✅ | ✅ | ✅ | ✅ |
Protocol V1 and V2 do not support explicit transactions. All queries in these versions execute in auto-commit mode. To use transaction control, Protocol V3 or higher must be negotiated.
Sources: README.md138-144 src/protocol/v3/BeginMessage.php13 src/protocol/v3/CommitMessage.php13 src/protocol/v3/RollbackMessage.php13
Refresh this wiki