From d2156de537f7b2cb1d01a6a1f5a58c73017b00d0 Mon Sep 17 00:00:00 2001 From: Masahiko Sawada Date: Tue, 19 May 2020 15:06:38 +0900 Subject: [PATCH v22 3/6] Documentation update. --- doc/src/sgml/catalogs.sgml | 136 +++++++++++++ doc/src/sgml/config.sgml | 144 +++++++++++++ doc/src/sgml/distributed-transaction.sgml | 143 +++++++++++++ doc/src/sgml/fdwhandler.sgml | 236 ++++++++++++++++++++++ doc/src/sgml/filelist.sgml | 1 + doc/src/sgml/func.sgml | 89 ++++++++ doc/src/sgml/monitoring.sgml | 42 ++++ doc/src/sgml/postgres.sgml | 1 + doc/src/sgml/storage.sgml | 6 + 9 files changed, 798 insertions(+) create mode 100644 doc/src/sgml/distributed-transaction.sgml diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml index 700271fd40..2af2eda512 100644 --- a/doc/src/sgml/catalogs.sgml +++ b/doc/src/sgml/catalogs.sgml @@ -9223,6 +9223,11 @@ SCRAM-SHA-256$<iteration count>:&l summary of configuration file contents + + pg_foreign_xacts + foreign transactions + + pg_group groups of database users @@ -10934,6 +10939,137 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx + + <structname>pg_foreign_xacts</structname> + + + pg_foreign_xacts + + + + The view pg_foreign_xacts displays + information about foreign transactions that are opened on + foreign servers for atomic distributed transaction commit (see + for details). + + + + pg_foreign_xacts contains one row per foreign + transaction. An entry is removed when the foreign transaction is + committed or rolled back. + + + + <structname>pg_foreign_xacts</structname> Columns + + + + + Name + Type + References + Description + + + + + dbid + oid + pg_database.oid + + OID of the database which the foreign transaction resides in + + + + xid + xid + + + Numeric transaction identifier with which this foreign transaction + associates + + + + serverid + oid + pg_foreign_server.oid + + The OID of the foreign server on which the foreign transaction is prepared + + + + userid + oid + pg_user.oid + + The OID of the user that prepared this foreign transaction. + + + + status + text + + + Status of foreign transaction. Possible values are: + + + + preparing : This foreign transaction is being prepared. + + + + + prepared : This foreign transaction has been prepared. + + + + + committing : This foreign transcation is being committed. + + + + + aborting : This foreign transaction is being aborted. + + + + + + + in_doubt + boolean + + + If true this foreign transaction is in-doubt status. + A foreign transaction becomes in-doubt status when user canceled the + query during transaction commit or the server crashed during transaction + commit. + + + + identifier + text + + + The identifier of the prepared foreign transaction. + + + + +
+ + + When the pg_foreign_xacts view is accessed, the + internal transaction manager data structures are momentarily locked, and + a copy is made for the view to display. This ensures that the + view produces a consistent set of results, while not blocking + normal operations longer than necessary. Nonetheless + there could be some impact on database performance if this view is + frequently accessed. + + + + <structname>pg_publication_tables</structname> diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml index 31b4660160..918fac967c 100644 --- a/doc/src/sgml/config.sgml +++ b/doc/src/sgml/config.sgml @@ -9085,6 +9085,150 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' + + Distributed Transaction Management + + + Setting + + + + foreign_twophase_commit (enum) + + foreign_twophase_commit configuration parameter + + + + + Specifies whether distributed transaction commits ensures that all + involved changes on foreign servers are committed or not. Valid + values are required and disabled. + The default setting is disabled. Setting to + disabled don't use two-phase commit protocol to + commit or rollback distributed transactions. When set to + required distributed transactions strictly requires + that all written servers can use two-phase commit protocol. That is, + the distributed transaction cannot commit if even one server does not + support the prepare callback routine + (described in ). + In required case, distributed transaction commit will + wait for all involving foreign transaction to be committed before the + command return a "success" indication to the client. + + + + This parameter can be changed at any time; the behavior for any one + transaction is determined by the setting in effect when it commits. + + + + + When disabled there can be risk of database + consistency among all servers that involved in the distributed + transaction when some foreign server crashes during committing the + distributed transaction. + + + + + + + max_prepared_foreign_transactions (integer) + + max_prepared_foreign_transactions configuration parameter + + + + + Sets the maximum number of foreign transactions that can be prepared + simultaneously. A single local transaction can give rise to multiple + foreign transaction. If a user expects N local + transactions and each of those involves K foreign + servers, this value need to be set N * K, not + just N. This parameter can only be set at server + start. + + + When running a standby server, you must set this parameter to the + same or higher value than on the master server. Otherwise, queries + will not be allowed in the standby server. + + + + + + + + + Foreign Transaction Resolvers + + + These settings control the behavior of a foreign transaction resolver. + + + + + max_foreign_transaction_resolvers (int) + + max_foreign_transaction_resolvers configuration parameter + + + + + Specifies maximum number of foreign transaction resolution workers. A foreign transaction + resolver is responsible for foreign transaction resolution on one database. + + + Foreign transaction resolution workers are taken from the pool defined by + max_worker_processes. + + + The default value is 0. + + + + + + foreign_transaction_resolution_retry_interval (integer) + + foreign_transaction_resolution_interval configuration parameter + + + + + Specify how long the foreign transaction resolver should wait when the last resolution + fails before retrying to resolve foreign transaction. This parameter can only be set in the + postgresql.conf file or on the server command line. + + + The default value is 10 seconds. + + + + + + foreign_transaction_resolver_timeout (integer) + + foreign_transaction_resolver_timeout configuration parameter + + + + + Terminate foreign transaction resolver processes that don't have any foreign + transactions to resolve longer than the specified number of milliseconds. + A value of zero disables the timeout mechanism, meaning it connects to one + database until stopping manually. This parameter can only be set in the + postgresql.conf file or on the server command line. + + + The default value is 60 seconds. + + + + + + + Version and Platform Compatibility diff --git a/doc/src/sgml/distributed-transaction.sgml b/doc/src/sgml/distributed-transaction.sgml new file mode 100644 index 0000000000..139dd7f918 --- /dev/null +++ b/doc/src/sgml/distributed-transaction.sgml @@ -0,0 +1,143 @@ + + + + Distributed Transaction + + + A distributed transaction is a transaction in which two or more network hosts + are involved. PostgreSQL's global Transaction + manager supports distributed transactions that access foreign servers using + Foreign Data Wrappers. The global transaction manager is responsible for + managing transactions on foreign servers. + + + + Atomic Commit + + + Formerly, transactions on foreign server were simply committed or rolled + back one by one. Therefore, when one foreign server had a problem during + commit, it was possible that transactions on only part of foreign servers + are committed while other transactions are rolled back. This used to leave + database data in an inconsistent state in term of federated database. + Atomic commit of distributed transaction is an operation that applies a set + of changes as a single operation globally. This guarantees all-or-nothing + results for the changes on all remote hosts involved in. + PostgreSQL provides a way to perform read-write + transactions with foreign resources using foreign data wrappers. + Using the PostgreSQL's atomic commit ensures that + all changes on foreign servers end in either commit or rollback using the + transaction callback routines + (see ). + + + + Atomic Commit Using Two-phase Commit Protocol + + + To achieve commit among all foreign servers automatically, + PostgreSQL employs two-phase commit protocol, + which is a type of atomic commitment protocol (ACP). Using two-phase + commit protocol, the commit sequence of distributed transaction performs + with the following steps: + + + + Prepare all transactions on foreign servers. + PostgreSQL distributed transaction manager + prepares all transaction on the foreign servers if two-phase commit is + required. Two-phase commit is required when the transaction modifies + data on two or more servers including the local server itself and + is + required. If all preparations on foreign servers got + successful go to the next step. Any failure happens in this step, + the server changes to rollback, then rollback all transactions on both + local and foreign servers. + + + + + Commit locally. The server commits transaction locally. Any failure happens + in this step the server changes to rollback, then rollback all transactions + on both local and foreign servers. + + + + + Resolve all prepared transaction on foreign servers. Pprepared transactions + are committed or rolled back according to the result of the local transaction. + This step is normally performed by a foreign transaction resolver process. + + + + + + + Each commit of a distributed transaction will wait until confirmation is + received that all prepared transactions are committed or rolled back. + + + + + In-Doubt Transactions + + + The atomic commit mechanism ensures that all foreign servers either commit + or rollback using two-phase commit protocol. However, foreign transactions + become in-doubt in three cases: where the foreign + server crashed or lost the connectibility to it during preparing foreign + transaction, where the local node crashed during either preparing or + resolving foreign transaction and where user canceled the query. You can + check in-doubt transaction in + view. These foreign transactions are resolved by foreign transaction resolver + process or executing pg_resolve_foriegn_xact function + manually. + + + + + Foreign Transaction Resolver Processes + + + Foreign transaction resolver processes are auxiliary processes that are + responsible for resolving both foreign transactions that are prepared by + online transactions and in-doubt transactions. They commit or rollback + prepared transactions on all foreign servers involved with the distributed + transaction if the local node received agreement messages from all + foreign servers during the first step of two-phase commit protocol. + + + + One foreign transaction resolver is responsible for transaction resolutions + on which one database connecting. On failure during resolution, they retry to + resolve at an interval of foreign_transaction_resolution_interval + time. + + + + + During a foreign transaction resolver process connecting to the database, + database cannot be dropped without immediate shutdown. You can call + pg_stop_foreign_xact_resovler function to stop the + particular resolver process before dropping the database. + + + + + + Configuration Settings + + + Atomic commit requires several configuration options to be set. + On the local node, and + must be non-zero value. + Additionally the max_worker_processes may need to be adjusted to + accommodate for foreign transaction resolver workers, at least + (max_foreign_transaction_resolvers + 1). + Note that other PostgreSQL feature such as parallel + queries, logical replication, etc., also take worker slots from + max_worker_processes. + + + + diff --git a/doc/src/sgml/fdwhandler.sgml b/doc/src/sgml/fdwhandler.sgml index 6587678af2..dd0358ef22 100644 --- a/doc/src/sgml/fdwhandler.sgml +++ b/doc/src/sgml/fdwhandler.sgml @@ -1415,6 +1415,127 @@ ReparameterizeForeignPathByChild(PlannerInfo *root, List *fdw_private, + + FDW Routines For Transaction Managements + + + Transaction management callbacks are used for doing commit, rollback and + prepare the foreign transaction. If an FDW wishes that its foreign + transaction is managed by PostgreSQL's global + transaction manager it must provide both + CommitForeignTransaction and + RollbackForeignTransaction. In addition, if an FDW + wishes to support atomic commit (as described in + ), it must provide + PrepareForeignTransaction as well and can provide + GetPrepareId callback optionally. + + + + +void +PrepareForeignTransaction(FdwXactRslvState *frstate); + + Prepare the transaction on the foreign server. This function is called at the + pre-commit phase of the local transactions if foreign twophase commit is + required. This function is used only for distribute transaction management + (see ). + + + + Note that this callback function is always executed by backend processes. + + + +bool +CommitForeignTransaction(FdwXactRslvState *frstate); + + Commit the foreign transaction. This function is called either at + the pre-commit phase of the local transaction if the transaction + can be committed in one-phase or at the post-commit phase if + two-phase commit is required. If frstate->flag has + the flag FDW_XACT_FLAG_ONEPHASE the transaction + can be committed in one-phase, this function must commit the prepared + transaction identified by frstate->fdwxact_id. + + + + The foreign transaction identified by frstate->fdwxact_id + might not exist on the foreign servers. This can happen when, for instance, + PostgreSQL server crashed during preparing or + committing the foreign tranasction. Therefore, this function needs to + tolerate the undefined object error + (ERRCODE_UNDEFINED_OBJECT) rather than raising an error. + + + + Note that all cases except for calling pg_resolve_fdwxact + SQL function, this callback function is executed by foreign transaction + resolver processes. + + + +bool +RollbackForeignTransaction(FdwXactRslvState *frstate); + + Rollback the foreign transaction. This function is called either at + the end of the local transaction after rolled back locally. The foreign + transactions are rolled back when user requested rollbacking or when + any error occurs during the transaction. This function must be tolerate to + being called recursively if any error occurs during rollback the foreign + transaction. So you would need to track recursion and prevent being called + infinitely. If frstate->flag has the flag + FDW_XACT_FLAG_ONEPHASE the transaction can be rolled + back in one-phase, otherwise this function must rollback the prepared + transaction identified by frstate->fdwxact_id. + + + + The foreign transaction identified by frstate->fdwxact_id + might not exist on the foreign servers. This can happen when, for instance, + PostgreSQL server crashed during preparing or + committing the foreign tranasction. Therefore, this function needs to + tolerate the undefined object error + (ERRCODE_UNDEFINED_OBJECT) rather than raising an error. + + + + Note that all cases except for calling pg_resolve_fdwxact + SQL function, this callback function is executed by foreign transaction + resolver processes. + + + +char * +GetPrepareId(TransactionId xid, Oid serverid, Oid userid, int *prep_id_len); + + Return null terminated string that represents prepared transaction identifier + with its length *prep_id_len. + This optional function is called during executor startup for once per the + foreign server. Note that the transaction identifier must be string literal, + less than NAMEDATALEN bytes long and should not be same + as any other concurrent prepared transaction id. If this callback routine + is not supported, PostgreSQL's distributed + transaction manager generates an unique identifier with in the form of + fx_<random value up to 231>_<server oid>_<user oid>. + + + + Note that this callback function is always executed by backend processes. + + + + + Functions PrepareForeignTransaction, + CommitForeignTransaction and + RolblackForeignTransaction are called + at outside of a valid transaction state. So please note that + you cannot use functions that use the system catalog cache + such as Foreign Data Wrapper helper functions described in + . + + + @@ -1894,4 +2015,119 @@ GetForeignServerByName(const char *name, bool missing_ok); + + Transaction managements for Foreign Data Wrappers + + If a FDW's server supports transaction, it is usually worthwhile for the + FDW to manage transaction opened on the foreign server. The FDW callback + function CommitForeignTransaction, + RollbackForeignTransaction and + PrepareForeignTransaction are used to manage Transaction + management and must fit into the working of the + PostgreSQL transaction processing. + + + + The information in FdwXactRslvState can be used to get + information of foreign server being processed such as server name, OID of + server, user and user mapping. The flags has contains flag + bit describing the foreign transaction state for transaction management. + + + + Commit And Rollback Single Foreign Transaction + + The FDW callback function CommitForeignTransaction + and RollbackForeignTransaction can be used to commit + and rollback the foreign transaction. During transaction commit, the core + transaction manager calls CommitForeignTransaction function + in the pre-commit phase and calls + RollbackForeignTransaction function in the post-rollback + phase. + + + + + Atomic Commit And Rollback Distributed Transaction + + In addition to simply commit and rollback foreign transactions described at + , + PostgreSQL global transaction manager enables + distributed transactions to atomically commit and rollback among all foreign + servers, which is as known as atomic commit in literature. To achieve atomic + commit, PostgreSQL employs two-phase commit + protocol, which is a type of atomic commitment protocol. Every FDWs that wish + to support two-phase commit protocol are required to have the FDW callback + function PrepareForeignTransaction and optionally + GetPrepareId, in addition to + CommitForeignTransaction and + RollbackForeignTransaction + (see for details). + + + + An example of distributed transaction is as follows + +BEGIN; +UPDATE ft1 SET col = 'a'; +UPDATE ft2 SET col = 'b'; +COMMIT; + + ft1 and ft2 are foreign tables on different foreign servers may be using different + Foreign Data Wrappers. + + + + When the core executor access the foreign servers, foreign servers whose FDW + supports transaction management callback routines is registered as a participant. + During registration, GetPrepareId is called if provided to + generate an unique transaction identifer. + + + + During pre-commit phase of local transaction, the foreign transaction manager + persists the foreign transaction information to the disk and WAL, and then + prepare all foreign transaction by calling + PrepareForeignTransaction if two-phase commit protocol + is required. Two-phase commit is required when the transaction modified data + on more than one servers including the local server itself and user requests + foreign twophase commit (see ). + + + + PostgreSQL can commit locally and go to the next + step if and only if all foreign transactions are prepared successfully. + If any failure happens or user requests to cancel during preparation, + the distributed transaction manager changes over rollback and calls + RollbackForeignTransaction. + + + + Note that when (frstate->flags & FDWXACT_FLAG_ONEPHASE) + is true, both CommitForeignTransaction function and + RollbackForeignTransaction function should commit and + rollback directly, rather than processing prepared transactions. This can + happen when two-phase commit is not required or foreign server is not + modified with in the transaction. + + + + Once all foreign transaction is prepared, the core transaction manager commits + locally. After that the transaction commit waits for all prepared foreign + transaction to be committed before completetion. After all prepared foreign + transactions are resolved the transaction commit completes. + + + + One foreign transaction resolver process is responsible for foreign + transaction resolution on a database. Foreign transaction resolver process + calls either CommitForeignTransaction or + RollbackForeignTransaction to resolve foreign + transaction identified by frstate->fdwxact_id. If failed + to resolve, resolver process will exit with an error message. The foreign + transaction launcher will launch the resolver process again at + interval. + + + diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml index 68179f71cd..1ab8e80fdc 100644 --- a/doc/src/sgml/filelist.sgml +++ b/doc/src/sgml/filelist.sgml @@ -48,6 +48,7 @@ + diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml index 7c06afd3ea..e281bd33d8 100644 --- a/doc/src/sgml/func.sgml +++ b/doc/src/sgml/func.sgml @@ -26126,6 +26126,95 @@ SELECT convert_from(pg_read_binary_file('file_in_utf8.txt'), 'UTF8'); + + Foreign Transaction Management Functions + + + pg_resolve_foreign_xact + + + pg_remove_foreign_xact + + + + shows the functions + available for foreign transaction management. + These functions cannot be executed during recovery. Use of these function + is restricted to superusers. + + + + Foreign Transaction Management Functions + + + Name Return Type Description + + + + + + pg_resolve_foreign_xact(transaction xid, userid oid, userid oid) + + bool + + Resolve a foreign transaction. This function searches for foreign + transaction matching the arguments and resolves it. Once the foreign + transaction is resolved successfully, this function removes the + corresponding entry from . + This function won't resolve a foreign transaction which is being + processed. + + + + + pg_remove_foreign_xact(transaction xid, serverid oid, userid oid) + + void + + This function works the same as pg_resolve_foreign_xact + except that this removes the foreign transcation entry without resolution. + + + + +
+ + + The function shown in + control the foreign transaction resolvers. + + + + Foreign Transaction Resolver Control Functions + + + + Name Return Type Description + + + + + + + pg_stop_fdwxact_resolver(dbid oid) + + bool + + Stop the foreign transaction resolver running on the given database. + This function is useful for stopping a resolver process on the database + that you want to drop. + + + + +
+ + + pg_stop_fdwxact_resolver is useful to be used before + dropping the database to that the foreign transaction resolver is connecting. + + + diff --git a/doc/src/sgml/monitoring.sgml b/doc/src/sgml/monitoring.sgml index 89662cc0a3..82c94d5e5d 100644 --- a/doc/src/sgml/monitoring.sgml +++ b/doc/src/sgml/monitoring.sgml @@ -1052,6 +1052,18 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser CheckpointerMain Waiting in main loop of checkpointer process. + + FdwXactLauncherMain + Waiting in main loop of foreign transaction resolution launcher process. + + + FdwXactResolverMain + Waiting in main loop of foreign transaction resolution worker process. + + + LogicalLauncherMain + Waiting in main loop of logical launcher process. + LogicalApplyMain Waiting in main loop of logical replication apply process. @@ -1273,6 +1285,18 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser DataFileWrite Waiting for a write to a relation data file. + + FdwXactFileRead + Waiting for a read of a foreign transaction state file. + + + FdwXactFileSync + Waiting for a foreign transaction state file to reach stable storage. + + + FdwXactFileWrite + Waiting for a write of a foreign transaction state file. + LockFileAddToDataDirRead Waiting for a read while adding a line to the data directory lock @@ -1550,6 +1574,11 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser Waiting for activity from a child process while executing a Gather plan node. + + FdwXactResolution + Waiting for all foreign transaction participants to be resolved during + atomic commit among foreign servers. + HashBatchAllocate Waiting for an elected Parallel Hash participant to allocate a hash @@ -1861,6 +1890,19 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser Waiting to read or update dynamic shared memory allocation information. + + FdwXactLock + Waiting to read or update the state of foreign transactions. + + + FdwXactResolutionLock + Waiting to read or update information of foreign trasnaction + resolution. + + + LogicalRepWorkerLock + Waiting for action on logical replication worker to finish. + LockFastPath Waiting to read or update a process' fast-path lock diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml index c41ce9499b..5ef1f4a329 100644 --- a/doc/src/sgml/postgres.sgml +++ b/doc/src/sgml/postgres.sgml @@ -170,6 +170,7 @@ break is not needed in a wider output rendering. &wal; &logical-replication; &jit; + &distributed-transaction; ®ress; diff --git a/doc/src/sgml/storage.sgml b/doc/src/sgml/storage.sgml index ea08d0b614..58f1e4fd15 100644 --- a/doc/src/sgml/storage.sgml +++ b/doc/src/sgml/storage.sgml @@ -83,6 +83,12 @@ Item subsystem + + pg_fdwxact + Subdirectory containing files used by the distributed transaction + manager subsystem + + pg_logical Subdirectory containing status data for logical decoding -- 2.23.0