Distributed Transactions

Data Structures
struct	db_xid_t
	Persistent transaction identifier. More...
struct	db_dtm_info_t
	Distributed transaction information. More...
Resource Management
db_result_t	db_rm_prepare (db_t, const db_xid_t *xid, db_wtime_t, db_flags_t)
db_result_t	db_rm_recover (db_t, db_xid_t *, db_len_t, db_len_t *, db_flags_t)
db_result_t	db_rm_commit (db_t, const db_xid_t *, db_flags_t)
db_result_t	db_rm_rollback (db_t, const db_xid_t *, db_flags_t)
#define	DB_RM_DETACH   1
#define	DB_RECOVER_RESTART   1
Distributed Transaction Management
db_result_t	db_dtm_commit (db_t, const db_ansi_t *tx_info, db_t *, int slave_count, db_xid_t *xid, int *unresolved)
db_result_t	db_dtm_info (db_t, const db_xid_t *, db_dtm_info_t *)
db_result_t	db_dtm_resolve (db_t, const db_xid_t *, db_t *, int slave_count, int *unresolved)
db_result_t	db_dtm_recover (db_t, db_xid_t *, db_len_t, db_len_t *, db_flags_t)
db_result_t	db_set_commit_timeout (db_t, db_wtime_t)
db_result_t	db_get_commit_timeout (db_t, db_wtime_t *)
#define	DB_DTM_NONE   0
#define	DB_DTM_PREPARED   1
#define	DB_DTM_COMMIT   2
#define	DB_DTM_ROLLBACK   3

---

Detailed Description

Distributed transactions are used to commit changes to multiple database atomically.

When a distributed transaction is committed with db_dtm_commit, ITTIA DB uses two-phase commit: no storage can commit its transaction until all storages are prepared to commit.

If a distributed commit is interrupted before it can finish, it and the transactions in each individual storage must be resolved. Until then, any rows or tables locked by these transactions will remain locked, even when the storages are closed.

Use db_dtm_resolve to resolve the distributed transaction. When it is not possible to reestablish connections to all the storages, it is also necessary to resolve each prepared transaction manually with db_rm_commit or

db_rm_rollback.

---

Define Documentation

#define DB_RM_DETACH   1

Detach prepared transaction from the connection.

#define DB_RECOVER_RESTART   1

Recover the first of a list of transactions.

#define DB_DTM_NONE   0

No distributed transaction.

#define DB_DTM_PREPARED   1

All slaves in a distributed transaction are prepared.

#define DB_DTM_COMMIT   2

Distributed transaction is committed.

#define DB_DTM_ROLLBACK   3

Distributed transaction is rolled back.

---

Function Documentation

db_result_t db_rm_prepare	(	db_t	hdb,
		const db_xid_t *	xid,
		db_wtime_t	commit_timeout,
		db_flags_t	flags
	)

Prepare the current transaction for a two-phase commit.

Parameters:

hdb	Database handle.
xid	A unique identifier for the transaction.
commit_timeout	Length of time expected to elapse between prepare and commit in the worst case.
flags	Commit options. A bitwise combination of: DB_RM_DETACHDetach prepared transaction from the connection. and one of the following completion modes: 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.

Make the current transaction global amd mark it as prepared to commit.

Warning:

Rows and tables locked by the transaction will remain locked until the transaction is resolved, even if the storage is closed.

If DB_RM_DETACH is not set in flags, use db_commit_tx or db_abort_tx to resolve the transaction state before starting another transaction. The database cannot be accessed through the same connection until the transaction is resolved.

If DB_RM_DETACH is set in flags, prepare detaches from the current transaction, so hdb can be used to carry out other transactions. Use db_rm_commit or db_rm_rollback to resolve the transaction.

db_result_t db_rm_recover	(	db_t	hdb,
		db_xid_t *	xid_list,
		db_len_t	max_count,
		db_len_t *	res_count,
		db_flags_t	flags
	)

Recover the list of unresolved prepared transactions.

Parameters:

	hdb	Database handle.
[out]	xid_list	Transaction identifier list.
	max_count	Maximum number of items that can be stored in xid_list.
[out]	res_count	Actual number of items stored in @ xid_list.
	flags	Options for recovering information. Any bitwise combination of: DB_RECOVER_RESTART: Start from the beginning of the list.

Returns:

• DB_OK when successful.
• DB_FAIL on failure.

If flags does not contain DB_RECOVER_RESTART, this function will only return transaction identifiers that have not been return by any previous call on the same connection.

A prepared transaction may belong to a distributed transaction in this or another database storage. Use db_dtm_recover to list unresolved distributed transactions.

db_result_t db_rm_commit	(	db_t	hdb,
		const db_xid_t *	xid,
		db_flags_t	flags
	)

Commit a prepared transaction that is unresolved.

Parameters:

hdb	Database handle.
xid	Idenifier for the prepared transaction.
flags	Commit flags. One of the following completion modes: 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.

db_result_t db_rm_rollback	(	db_t	hdb,
		const db_xid_t *	xid,
		db_flags_t	flags
	)

Roll back a prepared transaction that is unresolved.

Parameters:

hdb	Database handle.
xid	Idenifier for the prepared transaction.
flags	Commit flags. One of the following completion modes: 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.

db_result_t db_dtm_commit	(	db_t	hdb,
		const char *	tx_info,
		db_t *	slave_list,
		int	slave_count,
		db_xid_t *	res_xid,
		int *	x_unresolved
	)

Commit a distributed transaction.

Parameters:

	hdb	Master database handle.
	tx_info	Freeform description of the transaction to store in the log.
[in,out]	slave_list	List of slave database handles.
	slave_count	Number of slave database handles in slave_list.
[out]	res_xid	Identifier for the distributed transaction.
[out]	x_unresolved	Number of slave transactions that could not be resolved.

Returns:

• DB_OK when successful.
• DB_FAIL on failure.

Active transactions for all the listed slaves are prepared and committed as part of a distributed transaction. No transactions are committed until all transactions are prepared.

Warning:

The distributed transaction is logged to the database storage opened by the master database handle, hdb. The master database handle must not have an active transaction when db_dtm_commit is called and must not appear in the slave list. However, another connection to the same storage may appear in the slave list.

If a distributed commit is interrupted before it can finish, it and the transactions in each individual storage must be resolved. Until then, any rows or tables locked by these transactions will remain locked, even when the storages are closed.

Unlike a normal transaction, a distributed transaction is not automatically recovered when the storage is opened, because the state of the slave databases is unknown at that time. Use db_dtm_resolve to resolve the distributed transaction. When it is not possible to reestablish connections to all the storages, it is also necessary to resolve each prepared transaction manually with db_rm_commit or db_rm_rollback.

The slave_list argument is modified to contain only those slaves which could not be resolved, unless x_unresolved is NULL.

db_result_t db_dtm_info	(	db_t	hdb,
		const db_xid_t *	xid,
		db_dtm_info_t *	info
	)

Obtain information about an unresolved distributed transaction.

Parameters:

	hdb	Master database handle.
	xid	Identifier for the distributed transaction.
[out]	info	Transaction information data structure.

Returns:

• DB_OK when successful.
• DB_FAIL on failure.

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

• DB_EINVAL Caused by: invalid database handle.
• DB_ENOTX Distributed transaction does not exist or has already been resolved.

Information about the transaction identified by xid is written to info.

This function can only be used with the master storage that was used to commit the distributed transaction. However, hdb can be a different connection to that storage.

db_result_t db_dtm_resolve	(	db_t	hdb,
		const db_xid_t *	xid,
		db_t *	slave_list,
		int	slave_count,
		int *	x_unresolved
	)

Resolve an unresolved distributed transaction.

Parameters:

	hdb	Master database handle.
	xid	Distributed transaction identifier.
[in,out]	slave_list	List of slave database handles.
	slave_count	Number of slave databases in slave_list.
[out]	x_unresolved	Number of slave transactions that could not be resolved.

Returns:

• DB_OK when successful.
• DB_FAIL on failure.

When db_dtm_commit fails or is interrupted by a system failure, the distributed transaction is left in an unresolved state. Use db_dtm_resolve to resolve the distributed transaction and any prepared transactions that remain in the slave databases.

The slave_list should contain connections to as many of the original slave storages as possible. New connections can be used if the original connections are no longer available. It is also safe to include storages that were not involved in the distributed transaction in slave_list.

If it is not possible to connect to all the slaves, use db_rm_commit or

db_rm_rollback to manually resolve each slave's prepared transaction.

These functions can be used even if it is not possible to connect to the master database in order to make the slave databases useable.

None of the database handles passed to this function should have an active transaction (prepared transactions, however, are not active.)

Note:

An unresolved distributed transaction can also occur when synchronous replication is enabled if a failure occurs during a normal transaction commit. In this case, the database which originated the transaction will have an unresolved distributed transaction and the replication peers may each have an unresolved prepared transaction.

The slave_list argument is modified to contain only those slaves which could not be resolved, unless x_unresolved is NULL.

db_result_t db_dtm_recover	(	db_t	hdb,
		db_xid_t *	xid_list,
		db_len_t	max_count,
		db_len_t *	res_count,
		db_flags_t	flags
	)

Recover the list of unresolved distributed transactions.

Parameters:

	hdb	Master database handle.
[out]	xid_list	Transaction identifier list.
	max_count	Maximum number of items that can be stored in xid_list.
[out]	res_count	Actual number of items stored in @ xid_list.
	flags	Options for recovering information. Any bitwise combination of: DB_RECOVER_RESTART: Start from the beginning of the list.

Returns:

• DB_OK when successful.
• DB_FAIL on failure.

If flags does not contain DB_RECOVER_RESTART, this function will only return transaction identifiers that have not been return by any previous call on the same connection.

A distributed transaction may have one or more associated prepared transactions in this or other database storages. Use db_rm_recover to list unresolved prepared transactions.

db_result_t db_set_commit_timeout	(	db_t	hdb,
		db_wtime_t	msec
	)

Set the timeout for distributed transaction and synchronous replication commit operations.

Parameters:

hdb	Master database handle.
msec	Timeout duration.

Returns:

• DB_OK when successful.
• DB_FAIL on failure.

The commit timeout is the length of time that a slave or peer database will wait after it has been instructed to prepare its transaction. If it is not instructed to commit before the timeout elapses, it will roll back instead so that other connections can continue using the database.

This timeout affects transactions committed with db_dtm_commit and, when synchronous replication is configured, db_commit_tx.

db_result_t db_get_commit_timeout	(	db_t	hdb,
		db_wtime_t *	result
	)

Get the timeout for distributed transaction and synchronous replication commit operations.

Parameters:

	hdb	Master database handle.
[out]	result	Timeout duration.

Returns:

• DB_OK when successful.
• DB_FAIL on failure.

The commit timeout is the length of time that a slave or peer database will wait after it has been instructed to prepare its transaction. If it is not instructed to commit before the timeout elapses, it will roll back instead so that other connections can continue using the database.

This timeout affects transactions committed with db_dtm_commit and, when synchronous replication is configured, db_commit_tx.