Transactions

A transaction comprises a unit of work performed within a database management system (or similar system) against a database, and treated in a coherent and reliable way independent of other transactions. Transactions in a database environment have two main purposes:

to provide reliable units of work that allow correct recovery from failures and keep a database consistent even in cases of system failure, when execution stops (completely or partially) and many operations upon a database remain uncompleted, with unclear status
to provide isolation between programs accessing a database concurrently. If this isolation is not provided, the program’s outcome are possibly erroneous.

A database transaction, by definition, must be atomic, consistent, isolated and durable. Database practitioners often refer to these properties of database transactions using the acronym ACID). - Wikipedia

ArcadeDB is an ACID compliant DBMS.

ArcadeDB keeps the transaction in the host’s RAM, so the transaction size is affected by the available RAM (Heap memory) on JVM. For transactions involving many records, consider to split it in multiple transactions.

ACID Properties

Atomicity

"Atomicity requires that each transaction is 'all or nothing': if one part of the transaction fails, the entire transaction fails, and the database state is left unchanged. An atomic system must guarantee atomicity in each and every situation, including power failures, errors, and crashes. To the outside world, a committed transaction appears (by its effects on the database) to be indivisible ("atomic"), and an aborted transaction does not happen." - Wikipedia

Consistency

"The consistency property ensures that any transaction will bring the database from one valid state to another. Any data written to the database must be valid according to all defined rules, including but not limited to constraints, cascades, triggers, and any combination thereof. This does not guarantee correctness of the transaction in all ways the application programmer might have wanted (that is the responsibility of application-level code) but merely that any programming errors do not violate any defined rules." - Wikipedia

ArcadeDB uses the MVCC to assure consistency by versioning the page where the record are stored.

Look at this example:

Sequence	Client/Thread 1	Client/Thread 2	Version of page containing record X
1	Begin of Transaction
2	read(x)		10
3		Begin of Transaction
4		read(x)	10
5		write(x)	10
6		commit	10 → 11
7	write(x)		10
8	commit		10 → 11 = Error, in database x already is at 11

Isolation

"The isolation property ensures that the concurrent execution of transactions results in a system state that would be obtained if transactions were executed serially, i.e. one after the other. Providing isolation is the main goal of concurrency control. Depending on concurrency control method, the effects of an incomplete transaction might not even be visible to another transaction." - Wikipedia

The SQL standard defines the following phenomena which are prohibited at various levels are:

Dirty Read: a transaction reads data written by a concurrent uncommitted transaction. This is never possible with ArcadeDB.
Non Repeatable Read: a transaction re-reads data it has previously read and finds that data has been modified by another transaction (that committed since the initial read).
Phantom Read: a transaction re-executes a query returning a set of rows that satisfy a search condition and finds that the set of rows satisfying the condition has changed due to another recently-committed transaction. This happens also when records are deleted or inserted during the transaction and they could become visible during the transaction.

The SQL standard transaction isolation levels are described in the table below:

Isolation Level Dirty Read Non repeatable Read Phantom Read

Isolation Level	Dirty Read	Non repeatable Read	Phantom Read
`READ_COMMITTED` (default)	Not possible	Possible	Possible
`REPEATABLE_READ`	Not possible	Not possible	Possible

READ_COMMITTED (default)

Not possible

Possible

REPEATABLE_READ

Not possible

Possible

The SQL SERIALIZABLE level is not supported by ArcadeDB.

Using remote access all the commands are executed on the server, so out of transaction scope. Look below for more information.

Look at these examples:

Sequence	Client/Thread 1	Client/Thread 2
1	Begin of Transaction
2	read(x)
3		Begin of Transaction
4		read(x)
5		write(x)
6		commit
7	read(x)
8	commit

At operation 7 the client 1 continues to read the same version of x read in operation 2.

Sequence	Client/Thread 1	Client/Thread 2
1	Begin of Transaction
2	read(x)
3		Begin of Transaction
4		read(y)
5		write(y)
6		commit
7	read(y)
8	commit

At operation 7 the client 1 reads the version of y which was written at operation 6 by client 2. This is because it never reads y before.

Durability

"Durability means that once a transaction has been committed, it will remain so, even in the event of power loss, crashes, or errors. In a relational database, for instance, once a group of SQL statements execute, the results need to be stored permanently (even if the database crashes immediately thereafter). To defend against power loss, transactions (or their effects) must be recorded in a non-volatile memory." - Wikipedia

Fail-over

An ArcadeDB instance can fail for several reasons:

Hardware problems, such as loss of power or disk error
Software problems, such as a operating system crash
Application problems, such as a bug that crashes your application that is connected to the ArcadeDB engine.

You can use the ArcadeDB engine directly in the same process of your application. This gives superior performance due to the lack of inter-process communication. In this case, should your application crash (for any reason), the ArcadeDB engine also crashes.

If you’re connected to an ArcadeDB server remotely, and if your application crashes but the engine continues to work, any pending transaction owned by the client will be rolled back.

Auto-recovery

At start-up the ArcadeDB engine checks to if it is restarting from a crash. In this case, the auto-recovery phase starts which rolls back all pending transactions.

ArcadeDB has different levels of durability based on storage type, configuration and settings.

WAL Flush and Durability

ArcadeDB uses a Write-Ahead Log (WAL) to guarantee transaction durability. The arcadedb.txWalFlush setting controls whether the WAL is flushed (fsynced) to disk at commit time:

Value Behavior Durability guarantee

Value	Behavior	Durability guarantee
`0` (default)	No flush. WAL is written to the OS page cache but not fsynced.	Safe against process crashes (OS page cache survives). Not safe against power loss or OS crash - committed transactions may be lost.
`1`	Flush without metadata (`fdatasync`). WAL content is fsynced to the storage device.	Safe against power loss. Recommended for production.
`2`	Full flush (`fsync`). WAL content and filesystem metadata (timestamps, file size) are fsynced.	Maximum durability guarantee. Slightly slower than `1`, but ensures all metadata is consistent.

0 (default)

No flush. WAL is written to the OS page cache but not fsynced.

Safe against process crashes (OS page cache survives). Not safe against power loss or OS crash - committed transactions may be lost.

1

Flush without metadata (fdatasync). WAL content is fsynced to the storage device.

Safe against power loss. Recommended for production.

2

Full flush (fsync). WAL content and filesystem metadata (timestamps, file size) are fsynced.

Maximum durability guarantee. Slightly slower than 1, but ensures all metadata is consistent.

In production server mode (arcadedb.server.mode=production), ArcadeDB automatically sets txWalFlush=1 if you have not explicitly configured it. This ensures that production deployments are durable by default. If you explicitly set txWalFlush=0 in production mode, a warning is logged at startup.

The WAL flush setting can also be changed per-database or per-transaction via the Java API:

// Per-database
database.setWALFlush(WALFile.FlushType.YES_NOMETADATA);

// Per-transaction
database.getTransaction().setWALFlush(WALFile.FlushType.YES_FULL);

// Per async executor
database.async().setTransactionSync(WALFile.FlushType.YES_NOMETADATA);

If your storage hardware has battery-backed write cache (BBU/BBWC) or power-loss protection (common in enterprise SSDs and cloud block storage like AWS EBS), txWalFlush=0 is safe even in production because the hardware guarantees that buffered writes reach persistent storage on power loss.

Optimistic Transaction

This mode uses the well known Multi Version Control System MVCC by allowing multiple reads and writes on the same records. The integrity check is made on commit. If the record has been saved by another transaction in the interim, then an ConcurrentModificationException will be thrown. The application can choose either to repeat the transaction or abort it.

ArcadeDB keeps the whole transaction in the host’s RAM, so the transaction size is affected by the available RAM (Heap) memory on JVM. For transactions involving many records, consider to split it in multiple transactions.

Nested transactions and propagation

ArcadeDB does support nested transaction. If a begin() is called after a transaction is already begun, then the new transaction is the current one until commit or rollback. When this nested transaction is completed, the previous transaction becomes the current transaction again.