Before we dive in, we want to send another big THANK YOU to the many Avocaderas and Avocaderos who took the release candidates for a spin and shared their findings with us. Immensely helpful for the whole team to learn where we were wrong and right. Thanks, everyone!
The Streaming Transactions API
With the new streaming transactions API, you can
ABORT (rollback) operations to ArangoDB directly from your favorite language driver, like you might be used to from RDBMS.
You have many configuration options for your transaction available. For invoking a transaction you can e.g. define the following:
- collections: The collections the transaction will need for any write operation
- waitForSync: an optional Boolean flag to force the transaction to write to disk before returning
- allowImplicit: Allows the transaction to read from undeclared collections
- lockTimeout: lets you specify the maximum time the transaction to be completed (default is 10 minutes)
- maxTransactionSize: if you are using RocksDB as you storage engine (default engine since ArangoDB 3.4) you can define the maximal size of your transaction in bytes.
There are many more configurations available for the different stages of transaction. Check out our documentation for details and examples.
With this RC7, the Streaming Transactions API can be accessed via the official GOlang driver. The other official bindings will follow soon. If you want to support the new API within your driver, please see the hints & resources in the section “For Driver Developers” below.
Please note that ArangoDB only guarantees full ACID transactions on a single instance. The new streaming transactions API is also a nice improvement for cluster deployments but should not be perceived as distributed transactions. ArangoDB does not support full ACID semantics when data is sharded across different machines (but is still a cool database).
(RC5 & RC6 have been internal release packages, just in case you were wondering why the last official RC is declared RC4 and now we have RC7).
For Driver Developers
First of all, thank you so much for your ongoing contributions to the ArangoDB ecosystem and for helping your fellow Rustaceans, Gophers and the many other great languages to get started with ArangoDB. If you want to support the new Transaction API in your bindings, please see some details and pointers below.
The new API works as follows:
- Start a transaction using
POST /_api/transaction/begin(see details about begin a transaction). This call returns a transaction identifier ID.
- In order to execute a sequence of AQL queries or document operation in the context of this transaction, the driver must add the header field
x-arango-trx-idto each such request using this identifier ID (see details about transaction stream)
- You can then either
commit(see details about commit) or
abortthe transaction (see details about abort) with the identifier ID.
Please note, that transactions are not “per” client connection. The transaction is identified by the transaction ID. In a cluster, it is possible to start the transaction on one coordinator and continue on a different coordinator. The second coordinator will forward the request to the initial coordinator automatically. However, see the notes about guarantees in general above. While this forwarding is automatically done the driver, if possible, should try to avoid switching coordinators because it adds latency to the call. If the driver allows for stickiness it should stick to the initial coordinator that generated the transaction ID.
Happy testing and it would be fantastic to hear about your feedback via Github.