Transactions

Defines
#define	DB_SAVEPOINT_DEFAULT   _DB_SAVEPOINT_DEFAULT
#define	DB_SAVEPOINT_UNIQUE   _DB_SAVEPOINT_UNIQUE
#define	DB_SAVEPOINT_NESTED   _DB_SAVEPOINT_NESTED
#define	DB_SAVEPOINT_OVERRIDE   _DB_SAVEPOINT_OVERRIDE
Typedefs
typedef struct db_savepoint_t_s *	db_savepoint_t
Functions
db_result_t	db_begin_tx (db_t, db_flags_t)
db_result_t	db_commit_tx (db_t, db_flags_t)
db_result_t	db_abort_tx (db_t, db_flags_t)
db_result_t	db_flush_tx (db_t, db_flags_t)
int	db_is_active_tx (db_t)
db_result_t	db_set_tx_default (db_t, db_flags_t)
db_flags_t	db_get_tx_default (db_t)
db_savepoint_t	db_set_savepoint (db_t, const db_objname_t *, db_flags_t flags)
db_savepoint_t	db_find_savepoint (db_t, const db_objname_t *)
db_result_t	db_release_savepoint (db_t, db_savepoint_t)
db_result_t	db_rollback_savepoint (db_t, db_savepoint_t)
Transaction Isolation Levels
#define	DB_DEFAULT_ISOLATION   _DB_DEFAULT_ISOLATION
#define	DB_READ_COMMITTED   _DB_READ_COMMITTED
#define	DB_REPEATABLE_READ   _DB_REPEATABLE_READ
#define	DB_SERIALIZABLE   _DB_SERIALIZABLE
#define	DB_ISOLATION_MASK   _DB_ISOLATION_MASK
Transaction Completion Modes
#define	DB_DEFAULT_COMPLETION   _DB_DEFAULT_COMPLETION
#define	DB_LAZY_COMPLETION   _DB_LAZY_COMPLETION
#define	DB_FORCED_COMPLETION   _DB_FORCED_COMPLETION
#define	DB_GROUP_COMPLETION   _DB_GROUP_COMPLETION
#define	DB_COMPLETION_MASK   _DB_COMPLETION_MASK
Flush Mode
#define	DB_FLUSH_JOURNAL   _DB_FLUSH_JOURNAL
#define	DB_FLUSH_STORAGE   _DB_FLUSH_STORAGE
#define	DB_FLUSH_MASK   _DB_FLUSH_MASK

---

Detailed Description

All data access operations must occur inside a transaction.

A transaction is a logical group of operations that must all succeed or fail together. Changes made to the database do not become permanent until the transaction is committed. A transaction can also be aborted, which will undo any changes made since the transaction was started.

Transactions can be further divided into savepoints, allowing a transaction to be rolled back to the beginning of each savepoint. A savepoint should be used when a nested function is called during a transaction. The nested function can roll back its work if an error occurs, without affecting the enclosing scope.

---

Define Documentation

#define DB_SAVEPOINT_DEFAULT   _DB_SAVEPOINT_DEFAULT

Set savepoint with default behavior.

#define DB_SAVEPOINT_UNIQUE   _DB_SAVEPOINT_UNIQUE

Set savepoint only if no existing savepoint has the same name.

#define DB_SAVEPOINT_NESTED   _DB_SAVEPOINT_NESTED

Nest savepoints with the same name.

#define DB_SAVEPOINT_OVERRIDE   _DB_SAVEPOINT_OVERRIDE

Replace savepoints with the same name.

#define DB_DEFAULT_ISOLATION   _DB_DEFAULT_ISOLATION

Default isolation mode.

Examples:

phonebook_c.c.

#define DB_DEFAULT_COMPLETION   _DB_DEFAULT_COMPLETION

Default completion mode.

#define DB_FLUSH_JOURNAL   _DB_FLUSH_JOURNAL

Flush only the journal.

#define DB_READ_COMMITTED   _DB_READ_COMMITTED

Read committed isolation.

#define DB_REPEATABLE_READ   _DB_REPEATABLE_READ

Repeatable read isolation.

#define DB_SERIALIZABLE   _DB_SERIALIZABLE

Serializable isolation.

#define DB_LAZY_COMPLETION   _DB_LAZY_COMPLETION

Lazy completion.

#define DB_FORCED_COMPLETION   _DB_FORCED_COMPLETION

Immediate completion.

Examples:

phonebook_c.c.

#define DB_GROUP_COMPLETION   _DB_GROUP_COMPLETION

Group completion.

#define DB_FLUSH_STORAGE   _DB_FLUSH_STORAGE

Flush both the journal and storage.

---

Typedef Documentation

typedef struct db_savepoint_t_s* db_savepoint_t

Savepoint handle.

See also:

Transactions

---

Function Documentation

db_result_t db_begin_tx	(	db_t	hdb,
		db_flags_t	flags
	)

Begin a transaction.

Parameters:

hdb

Database handle

flags

Isolation mode: DB_DEFAULT_ISOLATIONDefault isolation mode. DB_READ_COMMITTEDRead committed isolation. DB_REPEATABLE_READRepeatable read isolation. DB_SERIALIZABLESerializable isolation. Lock mode: DB_LOCK_DEFAULT Equivalent to DB_LOCK_SHARED. DB_LOCK_SHARED Share access to the database with other transactions. This function will wait for transactions with an exclusive lock to finish. DB_LOCK_EXCLUSIVE Obtain exclusive access to the database for the duration of this transaction. This function will wait for all other transactions to finish.

Returns:

• DB_OK when successful.
• DB_FAIL on failure.

On failure, one of the following error codes is set:

• DB_EINVAL Could be caused by: invalid database handle, invalid flags parameter, invalid lock mode, invalid isolation mode.
• DB_ETXACTIVE A transaction is already running. Call db_commit_tx or

  db_abort_tx to finish the previous transaction before

starting a new transaction. To continue using the previous transaction, ignore this error.

• DB_ENOTX No such transcation found.

See also:

db_commit_tx, db_abort_tx, db_flush_tx,
get_db_error, clear_db_error, Error Handling

db_result_t db_commit_tx	(	db_t	hdb,
		db_flags_t	flags
	)

Commit a database's active transaction.

Parameters:

hdb	Database handle.
flags	DB_DEFAULT_COMPLETIONDefault completion mode. DB_LAZY_COMPLETIONLazy completion. DB_FORCED_COMPLETIONImmediate completion. DB_GROUP_COMPLETIONGroup completion.

Returns:

• DB_OK when successful.
• DB_FAIL on failure.

On failure, one of the following error codes is set:

• DB_EINVAL Could be caused by: invalid database handle, invalid flags parameter, invalid completion mode.
• DB_ENOTX No such transaction found.

See also:

db_begin_tx, db_abort_tx, db_flush_tx,
get_db_error, clear_db_error, Error Handling

db_result_t db_abort_tx	(	db_t	hdb,
		db_flags_t	flags
	)

Abort a database's active transaction.

Parameters:

hdb	Database handle.
flags	DB_DEFAULT_COMPLETIONDefault completion mode. DB_LAZY_COMPLETIONLazy completion. DB_FORCED_COMPLETIONImmediate completion. DB_GROUP_COMPLETIONGroup completion.

Returns:

• DB_OK when successful.
• DB_FAIL on failure.

On failure, one of the following error codes is set:

• DB_EINVAL Could be caused by: invalid database handle, invalid flags parameter, invalid completion mode.
• DB_ENOTX No such transaction found.
• DB_ESTATE Object state is not compatible with the method called or arguments. This could be caused by invalid transaction state.

See also:

db_begin_tx, db_commit_tx, db_flush_tx,
get_db_error, clear_db_error, Error Handling

db_result_t db_flush_tx	(	db_t	hdb,
		db_flags_t	flags
	)

Flush completed transactions to disk.

Parameters:

hdb	Database handle.
flags	DB_FLUSH_JOURNALFlush only the journal. DB_FLUSH_STORAGEFlush both the journal and storage.

Returns:

• DB_OK when successful.
• DB_FAIL on failure.

On failure, one of the following error codes is set:

• DB_EINVAL Could be caused by: invalid database handle, invalid flags parameter.

Call db_flush_tx with the DB_FLUSH_JOURNAL flag to flush transactions that were committed with the DB_LAZY_COMPLETION flag. You do not need to call db_flush_tx if transactions are committed with the

DB_FORCED_COMPLETION or DB_GROUP_COMPLETION flag. If automatic recovery is

necessary, transactions that have not been flushed may be aborted.

Call db_flush_tx with the DB_FLUSH_STORAGE flag to flush improve performance of automatic recovery and db_shutdown by flushing all dirty buffers to disk.

Note:

For best performance, use the minimum amount of flushing necessary for correct operation. For best reliability, always use forced completion.

See also:

db_begin_tx, db_commit_tx, db_flush_tx,
get_db_error, clear_db_error, Error Handling

int db_is_active_tx

(

db_t

hdb

)

Determine whether a transaction is active.

Parameters:

hdb	Database handle.

Returns:

• true if a transaction is active, false if no transaction is active.
• DB_LEN_FAIL on failure.

See also:

db_begin_tx, db_commit_tx, db_flush_tx,
get_db_error, clear_db_error, Error Handling

db_result_t db_set_tx_default	(	db_t	hdb,
		db_flags_t	flags
	)

Set default transaction mode.

Parameters:

hdb	Database handle.
flags	Isolation mode: DB_DEFAULT_ISOLATIONDefault isolation mode. DB_READ_COMMITTEDRead committed isolation. DB_REPEATABLE_READRepeatable read isolation. DB_SERIALIZABLESerializable isolation. Completion mode: DB_LAZY_COMPLETIONLazy completion. DB_GROUP_COMPLETIONGroup completion. DB_FORCED_COMPLETIONImmediate completion.

Returns:

• DB_OK when successful.
• DB_FAIL on failure.

On failure, one of the following error codes is set:

• DB_EINVAL Could be caused by: invalid database handle, invalid flags parameter or invalid isolation level.

This function can set the default mode for isolation, completion, or both. If a flag is not provided for either mode, the default for that mode will remain unchanged.

See also:

db_begin_tx, db_commit_tx, db_abort_tx, db_flush_tx,
get_db_error, clear_db_error, Error Handling

db_flags_t db_get_tx_default

(

db_t

hdb

)

Get default transaction mode.

Parameters:

hdb	Database handle.

Returns:

Current transaction mode flags.

On failure, one of the following error codes is set:

• DB_EINVAL Database handle is invalid.

See also:

db_begin_tx, db_commit_tx, db_abort_tx, db_flush_tx,
get_db_error, clear_db_error, Error Handling

db_savepoint_t db_set_savepoint	(	db_t	hdb,
		const db_objname_t *	name,
		db_flags_t	flags
	)

Create a save point and return a handle to identify it.

Parameters:

hdb	Database handle.
name	Name to assign the savepoint.
flags	Select behavior when name clashes with an existing savepoint: DB_SAVEPOINT_DEFAULTSet savepoint with default behavior. DB_SAVEPOINT_UNIQUESet savepoint only if no existing savepoint has the same name. DB_SAVEPOINT_NESTEDNest savepoints with the same name. DB_SAVEPOINT_OVERRIDEReplace savepoints with the same name.

Returns:

• Handle for the created savepoint.
• NULL on failure.

A transaction is started if not already active. Savepoints are automatically released when the transaction is committed or rolled back.

See also:

db_release_savepoint, db_rollback_savepoint, db_begin_tx
get_db_error, clear_db_error, Error Handling

db_savepoint_t db_find_savepoint	(	db_t	hdb,
		const db_objname_t *	name
	)

Identify the most recent savepoint with a given name.

Parameters:

hdb	Database handle.
name	Name of savepoint to find, or NULL to find the most recently created savepoint.

Returns:

• Handle for the identified savepoint.
• NULL on failure.

See also:

db_set_savepoint, db_release_savepoint, db_rollback_savepoint
get_db_error, clear_db_error, Error Handling

db_result_t db_release_savepoint	(	db_t	hdb,
		db_savepoint_t	sp
	)

Release a savepoint.

Parameters:

hdb	Database handle.
sp	Savepoint handle, or NULL to release the most recent savepoint.

When a savepoint is released, it can no longer be used to roll back to beginning of the savepoint. However, this does not garauntee that any work will be saved. If the enclosing transaction or an enclosing savepoint is rolled back, work performed in this savepoint will be lost.

Any savepoints that were subsequently set are automatically released.

Locks obtained during the savepoint are not released until the end of the enclosing transaction.

See also:

db_set_savepoint, db_find_savepoint, db_rollback_savepoint
get_db_error, clear_db_error, Error Handling

db_result_t db_rollback_savepoint	(	db_t	hdb,
		db_savepoint_t	sp
	)

Roll back a savepoint.

Parameters:

hdb	Database handle.
sp	Savepoint handle, or NULL to roll back the most recent savepoint.

When a savepoint is rolled back, the database is returned to the state it was in when the savepoint was set. Any savepoints that were subsequently set are automatically rolled back as well.

Locks obtained during the savepoint are not released until the end of the enclosing transaction.

See also:

db_set_savepoint, db_find_savepoint, db_release_savepoint
get_db_error, clear_db_error, Error Handling