diff --git a/content/en/docs/Developerguide/example-logic-replication-code.md b/content/en/docs/Developerguide/example-logic-replication-code.md new file mode 100644 index 0000000000000000000000000000000000000000..0f1710e62d72ec3f1239dcf17d42d0c05275009b --- /dev/null +++ b/content/en/docs/Developerguide/example-logic-replication-code.md @@ -0,0 +1,106 @@ +# Example: Logic Replication Code + +The following example demonstrates how to use the logical replication function through the JDBC interface. + +``` +//Logical replication function example: file name, LogicalReplicationDemo.java +//Prerequisite: Add the IP address of the JDBC user machine to the database whitelist. Add the following content to pg_hba.conf: +//Assume that the IP address of the JDBC user machine is 10.10.10.10. +//host all all 10.10.10.10/32 sha256 +//host replication all 10.10.10.10/32 sha256 + +import org.postgresql.PGProperty; +import org.postgresql.jdbc.PgConnection; +import org.postgresql.replication.LogSequenceNumber; +import org.postgresql.replication.PGReplicationStream; + +import java.nio.ByteBuffer; +import java.sql.DriverManager; +import java.util.Properties; +import java.util.concurrent.TimeUnit; + +public class LogicalReplicationDemo { + public static void main(String[] args) { + String driver = "org.postgresql.Driver"; + //Set the IP address and port number of the database. + String sourceURL = "jdbc:postgresql://$ip:$port/postgres"; + PgConnection conn = null; + //The default name of the logical replication slot is replication_slot. + //Test mode: Create a logical replication slot. + int TEST_MODE_CREATE_SLOT = 1; + //Test mode: Enable logical replication (The prerequisite is that the logical replication slot already exists). + int TEST_MODE_START_REPL = 2; + //Test mode: Delete a logical replication slot. + int TEST_MODE_DROP_SLOT = 3; + //Enable different test modes. + int testMode = TEST_MODE_START_REPL; + + try { + Class.forName(driver); + } catch (Exception e) { + e.printStackTrace(); + return; + } + + try { + Properties properties = new Properties(); + PGProperty.USER.set(properties, "user"); + PGProperty.PASSWORD.set(properties, "passwd"); + //For logical replication, the following three attributes are mandatory. + PGProperty.ASSUME_MIN_SERVER_VERSION.set(properties, "9.4"); + PGProperty.REPLICATION.set(properties, "database"); + PGProperty.PREFER_QUERY_MODE.set(properties, "simple"); + conn = (PgConnection) DriverManager.getConnection(sourceURL, properties); + System.out.println("connection success!"); + + if(testMode == TEST_MODE_CREATE_SLOT){ + conn.getReplicationAPI() + .createReplicationSlot() + .logical() + .withSlotName("replication_slot") + .withOutputPlugin("test_decoding") + .make(); + }else if(testMode == TEST_MODE_START_REPL) { + //Create a replication slot before enabling this mode. + LogSequenceNumber waitLSN = LogSequenceNumber.valueOf("6F/E3C53568"); + PGReplicationStream stream = conn + .getReplicationAPI() + .replicationStream() + .logical() + .withSlotName("replication_slot") + .withSlotOption("include-xids", false) + .withSlotOption("skip-empty-xacts", true) + .withStartPosition(waitLSN) + .start(); + while (true) { + ByteBuffer byteBuffer = stream.readPending(); + + if (byteBuffer == null) { + TimeUnit.MILLISECONDS.sleep(10L); + continue; + } + + int offset = byteBuffer.arrayOffset(); + byte[] source = byteBuffer.array(); + int length = source.length - offset; + System.out.println(new String(source, offset, length)); + + //If the LSN needs to be flushed, call the following APIs based on the service requirements: + //LogSequenceNumber lastRecv = stream.getLastReceiveLSN(); + //stream.setFlushedLSN(lastRecv); + //stream.forceUpdateStatus(); + + } + }else if(testMode == TEST_MODE_DROP_SLOT){ + conn.getReplicationAPI() + .dropReplicationSlot("replication_slot"); + } + } catch (Exception e) { + e.printStackTrace(); + return; + } + } +} + +``` + diff --git a/content/en/docs/Developerguide/figures/logical-replication.png b/content/en/docs/Developerguide/figures/logical-replication.png new file mode 100644 index 0000000000000000000000000000000000000000..3eb778cd95dc2eba667f144e891c02dfc3000f73 Binary files /dev/null and b/content/en/docs/Developerguide/figures/logical-replication.png differ diff --git a/content/en/docs/Developerguide/foregin-data-wrapper.md b/content/en/docs/Developerguide/foregin-data-wrapper.md new file mode 100644 index 0000000000000000000000000000000000000000..36e3f6371342e319b1155803758311a50be8130e --- /dev/null +++ b/content/en/docs/Developerguide/foregin-data-wrapper.md @@ -0,0 +1,11 @@ +# Foregin Data Wrapper + +The foreign data wrapper \(FDW\) of the openGauss can implement cross-database operations between openGauss databases and remote databases. Currently, the following remote databases are supported: Oracle, MySQL \(MariaDB\), and openGauss \(postgres\_fdw\). + +- **[oracle\_fdw](oracle_fdw.md)** + +- **[mysql\_fdw](mysql_fdw.md)** + +- **[postgres\_fdw](postgres_fdw.md)** + + diff --git a/content/en/docs/Developerguide/logical-decoding-by-sql-function-interfaces.md b/content/en/docs/Developerguide/logical-decoding-by-sql-function-interfaces.md new file mode 100644 index 0000000000000000000000000000000000000000..da397d2a02263a82b1e77e4a67518ffec57469d2 --- /dev/null +++ b/content/en/docs/Developerguide/logical-decoding-by-sql-function-interfaces.md @@ -0,0 +1,78 @@ +# Logical Decoding by SQL Function Interfaces + +In openGauss, you can call SQL functions to create, delete, and push logical replication slots, as well as obtain decoded transaction logs. + +## Prerequisites + +- Currently, logical logs are extracted from host nodes. Since SSL connections are disabled by default, to perform logical replication, set the GUC parameter **[ssl](en-us_topic_0242371486.md#en-us_topic_0237124696_en-us_topic_0059778664_s8c4647db116f44c4b9ce3dceee3d6ffa)** to **on** on host nodes. + + >![](public_sys-resources/icon-note.gif) **NOTE:** + >For security purposes, ensure that SSL connections are enabled. + + +- The GUC parameter **[wal\_level](en-us_topic_0242371497.md#en-us_topic_0237124707_en-us_topic_0059778393_s2c76f5957066407a959191148f2c780f)** is set to **logical**. +- The GUC parameter **[max\_replication\_slots](sending-server.md#section7322161612568)** is set to a value greater than the number of physical replication slots and logical replication slots required by each node. + + Physical replication slots provide an automatic method to ensure that Xlogs are not removed from a primary node before they are received by all the standby nodes and secondary nodes. That is, physical replication slots are used to support HA clusters. The number of physical replication slots required by a cluster is equal to the ratio of standby and secondary nodes to the primary node. For example, if an HA cluster has 1 primary node, 1 standby node, and 1 secondary node, the number of required physical replication slots will be 2. If an HA cluster has 1 primary node and 3 standby nodes, the number of required physical replication slots will be 3. + + Plan the number of logical replication slots as follows: + + - A logical replication slot can carry changes of only one database for decoding. If multiple databases are involved, create multiple logical replication slots. + - If logical replication is needed by multiple target databases, create multiple logical replication slots in the source database. Each logical replication slot corresponds to one logical replication link. + +- Only database administrators and users with the **REPLICATION** permission can perform operations in this scenario. + +## Procedure + +1. Log in to the primary node of the openGauss cluster as the cluster installation user. +2. Run the following command to connect to the default database **postgres**: + + ``` + gsql -d postgres -p 16000 -r + ``` + + In this command, **16000** is the database port number. It can be replaced by an actual port number. + +3. Create a logical replication slot named **slot1**. + + ``` + postgres=# SELECT * FROM pg_create_logical_replication_slot('slot1', 'mppdb_decoding'); + slotname | xlog_position + ----------+--------------- + slot1 | 0/601C150 + (1 row) + ``` + +4. Create a table **t** in the database and insert data into it. + + ``` + postgres=# CREATE TABLE t(a int PRIMARY KEY, b int); + postgres=# INSERT INTO t VALUES(3,3); + ``` + +5. Read the decoding result of **slot1**. The number of decoded records is 4096. + + ``` + postgres=# SELECT * FROM pg_logical_slot_peek_changes('slot1', NULL, 4096); + location | xid | data + -----------+-------+------------------------------------------------------------------------------------------------------------------------------------------------- + ------------------------------------------- + 0/601C188 | 1010023 | BEGIN 1010023 + 0/601ED60 | 1010023 | COMMIT 1010023 CSN 1010022 + 0/601ED60 | 1010024 | BEGIN 1010024 + 0/601ED60 | 1010024 | {"table_name":"public.t","op_type":"INSERT","columns_name":["a","b"],"columns_type":["integer","integer"],"columns_val":["3","3"],"old_keys_name":[],"old_keys_type":[],"old_keys_val":[]} + 0/601EED8 | 1010024 | COMMIT 1010024 CSN 1010023 + (5 rows) + ``` + +6. Delete the logical replication slot **slot1**. + + ``` + postgres=# SELECT * FROM pg_drop_replication_slot('slot1'); + pg_drop_replication_slot + -------------------------- + + (1 row) + ``` + + diff --git a/content/en/docs/Developerguide/logical-decoding.md b/content/en/docs/Developerguide/logical-decoding.md new file mode 100644 index 0000000000000000000000000000000000000000..061f37d4f43d4058bf3b37c2f3f9306673534551 --- /dev/null +++ b/content/en/docs/Developerguide/logical-decoding.md @@ -0,0 +1,7 @@ +# Logical Decoding + +- **[Overview](overview.md)** + +- **[Logical Decoding by SQL Function Interfaces](logical-decoding-by-sql-function-interfaces.md)** + + diff --git a/content/en/docs/Developerguide/logical-replication.md b/content/en/docs/Developerguide/logical-replication.md new file mode 100644 index 0000000000000000000000000000000000000000..68b13dd24e085b82f39d2097b95447f20c795bf7 --- /dev/null +++ b/content/en/docs/Developerguide/logical-replication.md @@ -0,0 +1,7 @@ +# Logical Replication + +- **[Logical Decoding](logical-decoding.md)** + +- **[Replicating Data Using the Logical Replication Tool](replicating-data-using-the-logical-replication-tool.md)** + + diff --git a/content/en/docs/Developerguide/mysql_fdw.md b/content/en/docs/Developerguide/mysql_fdw.md new file mode 100644 index 0000000000000000000000000000000000000000..3866d35e2b90182ffb23f063c3a49420285fe6aa --- /dev/null +++ b/content/en/docs/Developerguide/mysql_fdw.md @@ -0,0 +1,59 @@ +# mysql\_fdw + +mysql\_fdw is an [open-source plug-in](https://github.com/EnterpriseDB/mysql_fdw). openGauss is developed and adapted based on the open-source [mysql\_fdw Release 2.5.3](https://github.com/EnterpriseDB/mysql_fdw/archive/REL-2_5_3.tar.gz). + +To compile and use mysql\_fdw, the MariaDB development packages must be included in the environment. Therefore, openGauss does not compile mysql\_fdw by default. The following describes how to compile and use mysql\_fdw. + +## Compiling mysql\_fdw + +To compile mysql\_fdw, install the development library and header file of MariaDB. You are advised to use the official MariaDB repositories. For details about how to select a repository, visit [http://downloads.mariadb.org/mariadb/repositories/](http://downloads.mariadb.org/mariadb/repositories). + +After the repository is configured, run the **yum install MariaDB-devel MariaDB-shared** command to install the related development libraries. In addition, **MariaDB-client** is a client tool of the MariaDB. You can install it as required to connect to the MariaDB for testing. + +After installing the development packages, start mysql\_fdw compilation. Add the **--enable-mysql-fdw** option when running the **configure** command. Perform compilation using the common openGauss compilation method. \(For details about openGauss compilation reference, see _Software Compilation and Installation_.\) + +After the compilation is complete, the **mysql\_fdw.so** file is generated in **lib/postgresql/** in the installation directory. SQL files and control files related to mysql\_fdw are stored in **share/postgresql/extension/** in the installation directory. + +If the **--enable-mysql-fdw** option is not added during compilation and installation, compile mysql\_fdw again after openGauss is installed, and then manually place the **mysql\_fdw.so** file to **lib/postgresql/** in the installation directory, and place **mysql\_fdw--1.0--1.1.sql**, **mysql\_fdw--1.1.sql**, and **mysql\_fdw.control** to **share/postgresql/extension/** in the installation directory. + +## Using mysql\_fdw + +- To use mysql\_fdw, install and connect to MariaDB or MySQL server. + +- Load the mysql\_fdw extension using **CREATE EXTENSION mysql\_fdw;**. + +- Create a server object using **CREATE SERVER**. + +- Create a user mapping using **CREATE USER MAPPING**. + +- Create a foreign table using **CREATE FOREIGN TABLE**. The structure of the foreign table must be the same as that of the MySQL or MariaDB table. The first column in the table on the MySQL or MariaDB must be unique, for example, **PRIMARY KEY** and **UNIQUE**. + +- Perform normal operations on the foreign table, such as **INSERT**, **UPDATE**, **DELETE**, **SELECT**, **EXPLAIN**, **ANALYZE** and **COPY**. + +- Drop a foreign table using **DROP FOREIGN TABLE**. + +- Drop a user mapping using **DROP USER MAPPING**. + +- Drop a server object using **DROP SERVER**. + +- Drop an extension using **DROP EXTENSION mysql\_fdw;**. + + +## Common Issues + +- When a foreign table is created on the openGauss, the table is not created on the MariaDB or MySQL server. You need to use the MariaDB or MySQL server client to connect to the MariaDB or MySQL server to create a table. + +- The MariaDB or MySQL server user used for creating **USER MAPPING** must have the permission to remotely connect to the MariaDB or MySQL server and perform operations on tables. Before using a foreign table, you can use the MariaDB or MySQL server client on the machine where the openGauss server is located and use the corresponding user name and password to check whether the MariaDB or MySQL server can be successfully connected and operations can be performed. + +- The **Can't initialize character set SQL\_ASCII \(path: compiled\_in\)** error occurs when the DML operation is performed on a foreign table. MariaDB does not support the **SQL\_ASCII** encoding format. Currently, this problem can be resolved only by modifying the encoding format of the openGauss database. Change the database encoding format to **update pg\_database set encoding = pg\_char\_to\_encoding\('UTF-8'\) where datname = 'postgres';**. Set **datname** based on the actual requirements. After the encoding format is changed, start a gsql session again so that mysql\_fdw can use the updated parameters. You can also use **--locale=LOCALE** when running **gs\_initdb** to set the default encoding format to non-SQL\_ASCII. + + +## Precautions + +- **SELECT JOIN** between two MySQL foreign tables cannot be pushed down to the MariaDB or MySQL server for execution. Instead, **SELECT JOIN** is divided into two SQL statements and transferred to the MariaDB or MySQL server for execution. Then the processing result is summarized in the openGauss. + +- The **IMPORT FOREIGN SCHEMA** syntax is not supported. + +- **CREATE TRIGGER** cannot be executed for foreign tables. + + diff --git a/content/en/docs/Developerguide/oracle_fdw.md b/content/en/docs/Developerguide/oracle_fdw.md new file mode 100644 index 0000000000000000000000000000000000000000..f2318d1f612c7f064640adfb86a1d995d22f5154 --- /dev/null +++ b/content/en/docs/Developerguide/oracle_fdw.md @@ -0,0 +1,59 @@ +# oracle\_fdw + +oracle\_fdw is an [open-source plug-in](https://github.com/laurenz/oracle_fdw). openGauss is developed and adapted based on the open-source [oracle\_fdw Release 2.2.0](https://github.com/laurenz/oracle_fdw/archive/ORACLE_FDW_2_2_0.tar.gz). + +To compile and use oracle\_fdw, the Oracle development packages must be included in the environment. Therefore, openGauss does not compile oracle\_fdw by default. The following describes how to compile and use oracle\_fdw. + +## Compiling oracle\_fdw + +To compile oracle\_fdw, install the Oracle development library and header files from the [Oracle official website](https://www.oracle.com/database/technologies/instant-client/downloads.html). + +Select a proper running environment and version, download **Basic Package** and **SDK Package**, and install them. In addition, **SQLPlus Package** is a client tool of the Oracle server. You can install it as required to connect to the Oracle server for testing. + +After installing the development packages, start oracle\_fdw compilation. Add the **--enable-oracle-fdw** option when running the **configure** command. Perform compilation using the common openGauss compilation method. \(For details about openGauss compilation reference, see _Software Compilation and Installation_.\) + +After the compilation is complete, the **oracle\_fdw.so** file is generated in **lib/postgresql/** in the installation directory. SQL files and control files related to oracle\_fdw are stored in **share/postgresql/extension/** in the installation directory. + +If the **--enable-oracle-fdw** option is not added during compilation and installation, compile oracle\_fdw again after openGauss is installed, and then manually place the **oracle\_fdw.so** file to **lib/postgresql/** in the installation directory, and place **oracle\_fdw--1.0--1.1.sql**, **oracle\_fdw--1.1.sql**, and **oracle\_fdw.control** to **share/postgresql/extension/** in the installation directory. + +## Using oracle\_fdw + +- To use oracle\_fdw, install and connect to the Oracle server. + +- Load the oracle\_fdw extension using **CREATE EXTENSION oracle\_fdw;**. + +- Create a server object using **CREATE SERVER**. + +- Create a user mapping using **CREATE USER MAPPING**. + +- Create a foreign table using **CREATE FOREIGN TABLE**. The structure of the foreign table must be the same as that of the Oracle table. The first column in the table on the Oracle server must be unique, for example, **PRIMARY KEY** and **UNIQUE**. + +- Perform normal operations on the foreign table, such as **INSERT**, **UPDATE**, **DELETE**, **SELECT**, **EXPLAIN**, **ANALYZE** and **COPY**. + +- Drop a foreign table using **DROP FOREIGN TABLE**. + +- Drop a user mapping using **DROP USER MAPPING**. + +- Drop a server object using **DROP SERVER**. + +- Drop an extension using **DROP EXTENSION oracle\_fdw;**. + + +## Common Issues + +- When a foreign table is created on the openGauss, the table is not created on the Oracle server. You need to use the Oracle client to connect to the Oracle server to create a table. + +- The Oracle user used for executing **CREATE USER MAPPING** must have the permission to remotely connect to the Oracle server and perform operations on tables. Before using a foreign table, you can use the Oracle client on the machine where the openGauss server is located and use the corresponding user name and password to check whether the Oracle server can be successfully connected and operations can be performed. + +- When **CREATE EXTENSION oracle\_fdw;** is executed, the message **libclntsh.so: cannot open shared object file: No such file or directory** is displayed. The reason is that the Oracle development library **libclntsh.so** is not in the related path of the system. You can find the specific path of **libclntsh.so**, and then add the folder where the **libclntsh.so** file is located to **/etc/ld.so.conf**. For example, if the path of **libclntsh.so** is **/usr/lib/oracle/11.2/client64/lib/libclntsh.so.11.1**, add **/usr/lib/oracle/11.2/client64/lib/** to the end of **/etc/ld.so.conf**. Run the **ldconfig** command for the modification to take effect. Note that this operation requires the **root** permission. + + +## Precautions + +- **SELECT JOIN** between two Oracle foreign tables cannot be pushed down to the Oracle server for execution. Instead, **SELECT JOIN** is divided into two SQL statements and transferred to the Oracle server for execution. Then the processing result is summarized in the openGauss. + +- The **IMPORT FOREIGN SCHEMA** syntax is not supported. + +- **CREATE TRIGGER** cannot be executed for foreign tables. + + diff --git a/content/en/docs/Developerguide/overview.md b/content/en/docs/Developerguide/overview.md new file mode 100644 index 0000000000000000000000000000000000000000..f681e357531c9f47bb07b04e4b050036ad5f1b07 --- /dev/null +++ b/content/en/docs/Developerguide/overview.md @@ -0,0 +1,33 @@ +# Overview + +## Function + +The data replication capabilities supported by openGauss are as follows: + +Data is periodically synchronized to heterogeneous databases \(such as Oracle databases\) using a data migration tool. Real-time data replication is not supported. Therefore, the requirements for real-time data synchronization to heterogeneous databases are not satisfied. + +openGauss provides the logical decoding function to generate logical logs by decoding Xlogs. A target database parses logical logs to replicate data in real time. For details, see [Figure 1](#en-us_topic_0237121452_fig65787201989). Logical replication reduces the restrictions on target databases, allowing for data synchronization between heterogeneous databases and homogeneous databases with different forms. It allows data to be read and written during data synchronization on a target database, reducing the data synchronization latency. + +**Figure 1** Logical replication +![](figures/logical-replication.png "logical-replication") + +Logical replication consists of logical decoding and data replication. Logical decoding outputs logical logs by transaction. The database service or middleware parses the logical logs to implement data replication. Currently, openGauss supports only logical decoding. Therefore, this section involves only logical decoding. + +Logical decoding provides basic transaction decoding capabilities for logical replication. openGauss uses SQL functions for logical decoding. This method features easy function calling, requires no tools to obtain logical logs, and provides specific interfaces for interconnecting with external replay tools, saving the need of additional adaptation. + +Logical logs are output only after transactions are committed because they use transactions as the unit and logical decoding is driven by users. Therefore, to prevent Xlogs from being reclaimed by the system when transactions start and prevent required transaction information from being reclaimed by **VACUUM**, openGauss introduces logical replication slots to block Xlog reclaiming. + +A logical replication slot means a stream of changes that can be replayed in other clusters in the order they were generated in the original cluster. Each owner of logical logs maintains one logical replication slot. + +## Precautions + +- Decoding into DDL statements is not supported. +- Decoding for column-store data and data page replication is not supported. +- After a DDL statement \(for example, **ALTER TABLE**\) is executed, the physical logs that are not decoded before the DDL statement execution may be lost. +- Online cluster scale-out is not allowed during logical decoding. +- The size of a single tuple cannot exceed 1 GB, and decoding results may be larger than inserted data. Therefore, it is recommended that the size of a single tuple be less than or equal to 500 MB. +- Decoding compressed tables into DML statements is not supported. +- openGauss supports the following data types for decoding: **INTEGER**, **BIGINT**, **SMALLILNT**, **TINYINT**, **SERIAL**, **SMALLSERIAL**, **BIGSERIAL**, **FLOAT**, **DOUBLE PRECISION**, **DATE**, **TIME\[WITHOUT TIME ZONE\]**, **TIMESTAMP\[WITHOUT TIME ZONE\]**, **CHAR\(**_n_**\)**, **VARCHAR\(**_n_**\)**, and **TEXT**. +- Currently, SSL connections are not supported by default. If SSL connections are required, set the GUC parameter **ssl** to **on**. +- If JDBC is used to create a logical replication slot, the slot name must contain less than 64 characters, start with a letter or underscore \(\_\), and contain only one or more types of the following characters: letters \(a to z\), digits \(0-9\), and underscores \(\_\). + diff --git a/content/en/docs/Developerguide/postgres_fdw.md b/content/en/docs/Developerguide/postgres_fdw.md new file mode 100644 index 0000000000000000000000000000000000000000..095f8bd3d89fe7c77115b0a80b905d9411b1de39 --- /dev/null +++ b/content/en/docs/Developerguide/postgres_fdw.md @@ -0,0 +1,46 @@ +# postgres\_fdw + +postgres\_fdw is an open-source plug-in. Its code is released with the PostgreSQL source code. openGauss is developed and adapted based on the open-source postgres\_fdw source code \([https://ftp.postgresql.org/pub/source/v9.4.26/postgresql-9.4.26.tar.gz](https://ftp.postgresql.org/pub/source/v9.4.26/postgresql-9.4.26.tar.gz)\) in PostgreSQL 9.4.26. + +The postgres\_fdw plug-in is involved in compilation by default. After installing openGauss using the installation package, you can directly use postgres\_fdw without performing other operations. + +>![](public_sys-resources/icon-note.gif) **NOTE:** +>Currently, postgres\_fdw supports only connection between openGauss databases. + +## Using postgres\_fdw + +- Load the postgres\_fdw extension using **CREATE EXTENSION postgres\_fdw;**. + +- Create a server object using **CREATE SERVER**. + +- Create a user mapping using **CREATE USER MAPPING**. + +- Create a foreign table using **CREATE FOREIGN TABLE**. The structure of the foreign table must be the same as that of the remote openGauss table. + +- Perform normal operations on the foreign table, such as **INSERT**, **UPDATE**, **DELETE**, **SELECT**, **EXPLAIN**, **ANALYZE** and **COPY**. + +- Drop a foreign table using **DROP FOREIGN TABLE**. + +- Drop a user mapping using **DROP USER MAPPING**. + +- Drop a server object using **DROP SERVER**. + +- Drop an extension using **DROP EXTENSION postgres\_fdw;**. + + +## Common Issues + +- When a foreign table is created on the openGauss, the table is not created on the remote openGauss database. You need to use the Oracle client to connect to the remote openGauss database to create a table. + +- The openGauss user used for executing **CREATE USER MAPPING** must have the permission to remotely connect to the openGauss database and perform operations on tables. Before using a foreign table, you can use the gsql client on the local machine and use the corresponding user name and password to check whether the remote openGauss database can be successfully connected and operations can be performed. + + +## Precautions + +- **SELECT JOIN** between two postgres\_fdw foreign tables cannot be pushed down to the remote openGauss database for execution. Instead, **SELECT JOIN** is divided into two SQL statements and transferred to the remote openGauss database for execution. Then the processing result is summarized locally. + +- The **IMPORT FOREIGN SCHEMA** syntax is not supported. + +- **CREATE TRIGGER** cannot be executed for foreign tables. + + diff --git a/content/en/docs/Developerguide/replicating-data-using-the-logical-replication-tool.md b/content/en/docs/Developerguide/replicating-data-using-the-logical-replication-tool.md new file mode 100644 index 0000000000000000000000000000000000000000..203ca9813c799d27b1e8e36c345cc5c869cb1002 --- /dev/null +++ b/content/en/docs/Developerguide/replicating-data-using-the-logical-replication-tool.md @@ -0,0 +1,4 @@ +# Replicating Data Using the Logical Replication Tool + +Currently, the SDR and DRS tools support GaussDB logical replication. The replication tool extracts logical logs from GaussDB and plays them back to the peer database. + diff --git a/content/en/docs/Developerguide/sending-server.md b/content/en/docs/Developerguide/sending-server.md index 36bbf3a19c274c8a91a6402e40a3e0a245b1ed4c..76f0d9cd9d22ef4d193df23552000476ee4f2d8b 100644 --- a/content/en/docs/Developerguide/sending-server.md +++ b/content/en/docs/Developerguide/sending-server.md @@ -1,115 +1,168 @@ -# Sending Server - -## max\_wal\_senders - -**Parameter description**: Specifies the maximum number of simultaneously running WAL sender processes. The value cannot be greater than or equal to that of **[max\_connections](connection-settings.md#en-us_topic_0237124695_en-us_topic_0059777636_sa723b719fa70453bb7ec27f323d41c79)**. - -This parameter is a POSTMASTER parameter. Set it based on instructions provided in [Table 1](resetting-parameters.md#en-us_topic_0237121562_en-us_topic_0059777490_t91a6f212010f4503b24d7943aed6d846). - ->![](public_sys-resources/icon-notice.gif) **NOTICE:** ->**[wal\_level](settings.md#en-us_topic_0237124707_en-us_topic_0059778393_s2c76f5957066407a959191148f2c780f)** must be set to **archive** or **hot\_standby** to allow the connection from standby servers. - -**Value range**: an integer ranging from 0 to 262143 - -**Default value**: **4** for a single-server system and **8** for a primary/standby environment - -## wal\_keep\_segments - -**Parameter description**: Specifies the number of Xlog file segments. Specifies the minimum number of transaction log files stored in the **pg\_xlog** directory. The standby server obtains log files from the primary server for streaming replication. - -This parameter is a SIGHUP parameter. Set it based on instructions provided in [Table 1](resetting-parameters.md#en-us_topic_0237121562_en-us_topic_0059777490_t91a6f212010f4503b24d7943aed6d846). - -**Value range**: an integer ranging from 2 to _INT\_MAX_ - -**Default value**: **65** - -**Setting suggestions**: - -- During WAL archiving or recovery from a checkpoint on the server, the system may retain more log files than the number specified by **wal\_keep\_segments**. -- If this parameter is set to an excessively small value, a transaction log may have been overwritten by a new transaction before requested by the standby server. As a result, the request fails and the connection between the primary and standby servers is terminated. -- If the HA system uses asynchronous transmission, increase the value of **wal\_keep\_segments** when data greater than 4 GB is continuously imported in COPY mode. Take T6000 board as an example. If the data to be imported reaches 50 GB, you are advised to set this parameter to **1000**. You can dynamically restore the setting of this parameter after data import is complete and the WAL synchronization is proper. - -## wal\_sender\_timeout - -**Parameter description**: Specifies the maximum duration that the sending server waits for the WAL reception in the receiver. - -This parameter is a SIGHUP parameter. Set it based on instructions provided in [Table 1](resetting-parameters.md#en-us_topic_0237121562_en-us_topic_0059777490_t91a6f212010f4503b24d7943aed6d846). - ->![](public_sys-resources/icon-notice.gif) **NOTICE:** ->- If the data volume on the primary server is huge, the value of this parameter must be increased for the database rebuilding on a standby server. For example, if the data volume on the primary server reaches 500 GB, you are advised to set this parameter to 600 seconds. ->- This parameter cannot be set to a value larger than the value of **wal\_receiver\_timeout** or the timeout parameter for database rebuilding. - -**Value range**: an integer ranging from 0 to _INT\_MAX_. The unit is ms. - -**Default value**: **6s** - -## replconninfo1 - -**Parameter description**: Specifies the information about the first node to be listened to and authenticated by the current server. - -This parameter is a SIGHUP parameter. Set it based on instructions provided in [Table 1](resetting-parameters.md#en-us_topic_0237121562_en-us_topic_0059777490_t91a6f212010f4503b24d7943aed6d846). - -**Value range**: a string. An empty string indicates that no information about the first node is configured. - -**Default value**: empty - -## replconninfo2 - -**Parameter description**: Specifies the information about the second node to be listened to and authenticated by the current server. - -This parameter is a SIGHUP parameter. Set it based on instructions provided in [Table 1](resetting-parameters.md#en-us_topic_0237121562_en-us_topic_0059777490_t91a6f212010f4503b24d7943aed6d846). - -**Value range**: a string. An empty string indicates that no information about the second node is configured. - -**Default value**: empty - -## replconninfo3 - -**Parameter description**: Specifies the information about the third node to be listened to and authenticated by the current server. - -This parameter is a SIGHUP parameter. Set it based on instructions provided in [Table 1](resetting-parameters.md#en-us_topic_0237121562_en-us_topic_0059777490_t91a6f212010f4503b24d7943aed6d846). - -**Value range**: a string. An empty string indicates that no information about the third node is configured. - -**Default value**: empty - -## replconninfo4 - -**Parameter description**: Specifies the information about the fourth node to be listened to and authenticated by the current server. - -This parameter is a SIGHUP parameter. Set it based on instructions provided in [Table 1](resetting-parameters.md#en-us_topic_0237121562_en-us_topic_0059777490_t91a6f212010f4503b24d7943aed6d846). - -**Value range**: a string. An empty string indicates that no information about the fourth node is configured. - -**Default value**: empty - -## replconninfo5 - -**Parameter description**: Specifies the information about the fifth node to be listened to and authenticated by the current server. - -This parameter is a SIGHUP parameter. Set it based on instructions provided in [Table 1](resetting-parameters.md#en-us_topic_0237121562_en-us_topic_0059777490_t91a6f212010f4503b24d7943aed6d846). - -**Value range**: a string. An empty string indicates that no information about the fifth node is configured. - -**Default value**: empty - -## replconninfo6 - -**Parameter description**: Specifies the information about the sixth node to be listened to and authenticated by the current server. - -This parameter is a SIGHUP parameter. Set it based on instructions provided in [Table 1](resetting-parameters.md#en-us_topic_0237121562_en-us_topic_0059777490_t91a6f212010f4503b24d7943aed6d846). - -**Value range**: a string. An empty string indicates that no information about the sixth node is configured. - -**Default value**: empty - -## replconninfo7 - -**Parameter description**: Specifies the information about the seventh node to be listened to and authenticated by the current server. - -This parameter is a SIGHUP parameter. Set it based on instructions provided in [Table 1](resetting-parameters.md#en-us_topic_0237121562_en-us_topic_0059777490_t91a6f212010f4503b24d7943aed6d846). - -**Value range**: a string. An empty string indicates that no information about the seventh node is configured. - -**Default value**: empty - +# Sending Server + +## max\_wal\_senders + +**Parameter description**: Specifies the maximum number of simultaneously running WAL sender processes. The value cannot be greater than or equal to that of **[max\_connections](en-us_topic_0242371485.md#en-us_topic_0237124695_en-us_topic_0059777636_sa723b719fa70453bb7ec27f323d41c79)**. + +This parameter is a POSTMASTER parameter. Set it based on instructions provided in [Table 1](en-us_topic_0242370406.md#en-us_topic_0237121562_en-us_topic_0059777490_t91a6f212010f4503b24d7943aed6d846). + +>![](public_sys-resources/icon-notice.gif) **NOTICE:** +>**[wal\_level](en-us_topic_0242371497.md#en-us_topic_0237124707_en-us_topic_0059778393_s2c76f5957066407a959191148f2c780f)** must be set to **archive** or **hot\_standby** to allow the connection from standby servers. + +**Value range**: an integer ranging from 0 to 262143 + +**Default value**: **4** for a single-server system and **8** for a primary/standby environment + +## wal\_keep\_segments + +**Parameter description**: Specifies the number of Xlog file segments. Specifies the minimum number of transaction log files stored in the **pg\_xlog** directory. The standby server obtains log files from the primary server for streaming replication. + +This parameter is a SIGHUP parameter. Set it based on instructions provided in [Table 1](en-us_topic_0242370406.md#en-us_topic_0237121562_en-us_topic_0059777490_t91a6f212010f4503b24d7943aed6d846). + +**Value range**: an integer ranging from 2 to _INT\_MAX_ + +**Default value**: **65** + +**Setting suggestions**: + +- During WAL archiving or recovery from a checkpoint on the server, the system may retain more log files than the number specified by **wal\_keep\_segments**. +- If this parameter is set to an excessively small value, a transaction log may have been overwritten by a new transaction before requested by the standby server. As a result, the request fails and the connection between the primary and standby servers is terminated. +- If the HA system uses asynchronous transmission, increase the value of **wal\_keep\_segments** when data greater than 4 GB is continuously imported in COPY mode. Take T6000 board as an example. If the data to be imported reaches 50 GB, you are advised to set this parameter to **1000**. You can dynamically restore the setting of this parameter after data import is complete and the WAL synchronization is proper. + +## wal\_sender\_timeout + +**Parameter description**: Specifies the maximum duration that the sending server waits for the WAL reception in the receiver. + +This parameter is a SIGHUP parameter. Set it based on instructions provided in [Table 1](en-us_topic_0242370406.md#en-us_topic_0237121562_en-us_topic_0059777490_t91a6f212010f4503b24d7943aed6d846). + +>![](public_sys-resources/icon-notice.gif) **NOTICE:** +>- If the data volume on the primary server is huge, the value of this parameter must be increased for the database rebuilding on a standby server. For example, if the data volume on the primary server reaches 500 GB, you are advised to set this parameter to 600 seconds. +>- This parameter cannot be set to a value larger than the value of **wal\_receiver\_timeout** or the timeout parameter for database rebuilding. + +**Value range**: an integer ranging from 0 to _INT\_MAX_. The unit is ms. + +**Default value**: **6s** + +## max\_replication\_slots + +**Parameter description**: Specifies the number of log replication slots in the primary server. + +This parameter is a POSTMASTER parameter. Set it based on instructions provided in [Table 1](en-us_topic_0242370406.md#en-us_topic_0237121562_en-us_topic_0059777490_t91a6f212010f4503b24d7943aed6d846). + +**Value range**: an integer ranging from 8 to 100 + +**Default value**: **8** + +**Setting suggestions**: + +When using logical replication, you are advised to set this parameter to: Number of current physical replication slots + Number of required logical replication slots. + +- Physical replication slots provide an automatic method to ensure that Xlogs are not removed from a primary node before they are received by all the standby nodes and secondary nodes. That is, physical replication slots are used to support HA clusters. The number of physical replication slots required by a cluster is equal to the ratio of standby and secondary nodes to the primary node. For example, if an HA cluster has 1 primary node, 1 standby node, and 1 secondary node, the number of required physical replication slots will be 2. If an HA cluster has 1 primary node and 3 standby nodes, the number of required physical replication slots will be 3. +- Plan the number of logical replication slots as follows: + - A logical replication slot can carry changes of only one database for decoding. If multiple databases are involved, create multiple logical replication slots. + - If logical replication is needed by multiple target databases, create multiple logical replication slots in the source database. Each logical replication slot corresponds to one logical replication link. + + +## enable\_slot\_log + +**Parameter description**: Specifies whether to enable primary/standby synchronization for logical replication slots. + +This parameter is a USERSET parameter. Set it based on instructions provided in [Table 1](en-us_topic_0242370406.md#en-us_topic_0237121562_en-us_topic_0059777490_t91a6f212010f4503b24d7943aed6d846). + +**Value range**: Boolean + +- **on** indicates that primary/standby synchronization is enabled for logical replication slots. +- **off** indicates that primary/standby synchronization is disabled for logical replication slots. + +**Default value**: **off** + +## max\_changes\_in\_memory + +**Parameter description**: Specifies the maximum size \(bytes\) of a single transaction buffered in the memory during logical decoding. + +This parameter is a POSTMASTER parameter. Set it based on instructions provided in [Table 1](en-us_topic_0242370406.md#en-us_topic_0237121562_en-us_topic_0059777490_t91a6f212010f4503b24d7943aed6d846). + +**Value range**: an integer ranging from 1 to 2147483647 + +**Default value**: **4096** + +## max\_cached\_tuplebufs + +**Parameter description**: Specifies the maximum size \(bytes\) of the total tuple information buffered in the memory during logic decoding. You are advised to set this parameter to a value greater than or equal to twice of [max\_changes\_in\_memory](#section16366164213497). + +This parameter is a POSTMASTER parameter. Set it based on instructions provided in [Table 1](en-us_topic_0242370406.md#en-us_topic_0237121562_en-us_topic_0059777490_t91a6f212010f4503b24d7943aed6d846). + +**Value range**: an integer ranging from 1 to 2147483647 + +**Default value**: **8192** + +## replconninfo1 + +**Parameter description**: Specifies the information about the first node to be listened to and authenticated by the current server. + +This parameter is a SIGHUP parameter. Set it based on instructions provided in [Table 1](en-us_topic_0242370406.md#en-us_topic_0237121562_en-us_topic_0059777490_t91a6f212010f4503b24d7943aed6d846). + +**Value range**: a string. An empty string indicates that no information about the first node is configured. + +**Default value**: empty + +## replconninfo2 + +**Parameter description**: Specifies the information about the second node to be listened to and authenticated by the current server. + +This parameter is a SIGHUP parameter. Set it based on instructions provided in [Table 1](en-us_topic_0242370406.md#en-us_topic_0237121562_en-us_topic_0059777490_t91a6f212010f4503b24d7943aed6d846). + +**Value range**: a string. An empty string indicates that no information about the second node is configured. + +**Default value**: empty + +## replconninfo3 + +**Parameter description**: Specifies the information about the third node to be listened to and authenticated by the current server. + +This parameter is a SIGHUP parameter. Set it based on instructions provided in [Table 1](en-us_topic_0242370406.md#en-us_topic_0237121562_en-us_topic_0059777490_t91a6f212010f4503b24d7943aed6d846). + +**Value range**: a string. An empty string indicates that no information about the third node is configured. + +**Default value**: empty + +## replconninfo4 + +**Parameter description**: Specifies the information about the fourth node to be listened to and authenticated by the current server. + +This parameter is a SIGHUP parameter. Set it based on instructions provided in [Table 1](en-us_topic_0242370406.md#en-us_topic_0237121562_en-us_topic_0059777490_t91a6f212010f4503b24d7943aed6d846). + +**Value range**: a string. An empty string indicates that no information about the fourth node is configured. + +**Default value**: empty + +## replconninfo5 + +**Parameter description**: Specifies the information about the fifth node to be listened to and authenticated by the current server. + +This parameter is a SIGHUP parameter. Set it based on instructions provided in [Table 1](en-us_topic_0242370406.md#en-us_topic_0237121562_en-us_topic_0059777490_t91a6f212010f4503b24d7943aed6d846). + +**Value range**: a string. An empty string indicates that no information about the fifth node is configured. + +**Default value**: empty + +## replconninfo6 + +**Parameter description**: Specifies the information about the sixth node to be listened to and authenticated by the current server. + +This parameter is a SIGHUP parameter. Set it based on instructions provided in [Table 1](en-us_topic_0242370406.md#en-us_topic_0237121562_en-us_topic_0059777490_t91a6f212010f4503b24d7943aed6d846). + +**Value range**: a string. An empty string indicates that no information about the sixth node is configured. + +**Default value**: empty + +## replconninfo7 + +**Parameter description**: Specifies the information about the seventh node to be listened to and authenticated by the current server. + +This parameter is a SIGHUP parameter. Set it based on instructions provided in [Table 1](en-us_topic_0242370406.md#en-us_topic_0237121562_en-us_topic_0059777490_t91a6f212010f4503b24d7943aed6d846). + +**Value range**: a string. An empty string indicates that no information about the seventh node is configured. + +**Default value**: empty + diff --git a/content/en/docs/Developerguide/transaction-management.md b/content/en/docs/Developerguide/transaction-management.md new file mode 100644 index 0000000000000000000000000000000000000000..eba8e9a07b975eaa7bac317faa0bd8188c388e33 --- /dev/null +++ b/content/en/docs/Developerguide/transaction-management.md @@ -0,0 +1,74 @@ +# Transaction Management + +The **COMMIT** and **ROLLBACK** commands can be used to end a transaction when a stored procedure or anonymous block is called. After these commands are executed in a transaction, a new transaction is automatically started. You do not need to run the **START TRANSACTION** command separately. \(Note that BEGIN and END have different meanings in PL/SQL.\) In addition, stored procedures or anonymous blocks with transaction commands cannot be called in the transaction blocks that are explicitly started by users. + +**Example** + +``` +CREATE TABLE test1 (a int); +CREATE PROCEDURE transaction_test1() +AS +BEGIN + FOR i IN 0..9 LOOP + INSERT INTO test1 (a) VALUES (i); + IF i % 2 = 0 THEN + COMMIT; + ELSE + ROLLBACK; + END IF; + END LOOP; +END; +/ + +CALL transaction_test1(); +``` + +>![](public_sys-resources/icon-note.gif) **NOTE:** +>When a new transaction starts, it has the default transaction features, such as the transaction isolation level. +>The function call does not support transaction control. If you attempt to use transaction control in the function, an error is reported. In addition, for the nested use such as proc1\(\)-\>func2\(\)-\>proc3\(\), the last stored procedure cannot be used for transaction control because functions are called during the process. + +There are special considerations for cursor loops. The following is an example: + +``` +CREATE PROCEDURE transaction_test2() +AS +DECLARE + r RECORD; +BEGIN + FOR r IN SELECT * FROM test2 ORDER BY x LOOP + INSERT INTO test1 (a) VALUES (r.x); + COMMIT; + END LOOP; +END; +/ + +CALL transaction_test2(); +``` + +Typically, cursors are automatically closed when transactions are committed. However, a cursor that is created as part of a loop is automatically made a holdable cursor by the first COMMIT or ROLLBACK. This means that the cursor is fully computed at the first COMMIT or ROLLBACK, rather than being computed line by row. The cursor is still deleted automatically after the loop, so it is usually invisible to users. + +>![](public_sys-resources/icon-note.gif) **NOTE:** +>A cursor loop driven by non-read-only commands \(UPDATE... RETURNING\) is not allowed to have transaction commands. + +Transactional operations are also supported in a block with an exception handling section, as shown in the following example: + +``` +CREATE PROCEDURE transaction_test3() +AS +BEGIN + INSERT INTO test1 (a) VALUES (1); + COMMIT; + INSERT INTO test1 (a) VALUES (1/0); + COMMIT; +EXCEPTION + WHEN division_by_zero THEN + RAISE NOTICE 'caught division_by_zero'; +END; +/ + +CALL transaction_test3(); +``` + +>![](public_sys-resources/icon-note.gif) **NOTE:** +>After the preceding stored procedure is executed, an exception is captured, but the first insert operation is completed normally. + diff --git a/content/en/menu/index.md b/content/en/menu/index.md index 17973a26752634e16a39a25cbe403b2bc35ea514..dd95f7e3dd35abf25eac986bc08f03c1ce04cf21 100644 --- a/content/en/menu/index.md +++ b/content/en/menu/index.md @@ -199,6 +199,7 @@ headless: true - [Example: Retrying SQL Queries for Applications]({{< relref "./docs/Developerguide/example-retrying-sql-queries-for-applications.md" >}}) - [Example: Importing and Exporting Data Through Local Files]({{< relref "./docs/Developerguide/example-importing-and-exporting-data-through-local-files.md" >}}) - [Example 2: Migrating Data from a MY Database to openGauss]({{< relref "./docs/Developerguide/example-2-migrating-data-from-a-my-database-to-opengauss.md" >}}) + - [Example: Logic Replication Code]({{< relref "./docs/Developerguide/example-logic-replication-code.md" >}}) - [JDBC Interface Reference]({{< relref "./docs/Developerguide/jdbc-interface-reference.md" >}}) - [Development Based on ODBC]({{< relref "./docs/Developerguide/development-based-on-odbc.md" >}}) - [ODBC Packages, Dependent Libraries, and Header Files]({{< relref "./docs/Developerguide/odbc-packages-dependent-libraries-and-header-files.md" >}}) @@ -742,6 +743,7 @@ headless: true - [NULL Statements]({{< relref "./docs/Developerguide/null-statements.md" >}}) - [Error Trapping Statements]({{< relref "./docs/Developerguide/error-trapping-statements.md" >}}) - [GOTO Statements]({{< relref "./docs/Developerguide/goto-statements.md" >}}) + - [Transaction Management]({{< relref "./docs/Developerguide/transaction-management.md" >}}) - [Other Statements]({{< relref "./docs/Developerguide/other-statements.md" >}}) - [Lock Operations]({{< relref "./docs/Developerguide/lock-operations.md" >}}) - [Cursor Operations]({{< relref "./docs/Developerguide/cursor-operations.md" >}}) @@ -1096,6 +1098,15 @@ headless: true - [SNAPSHOT.SNAPSHOT]({{< relref "./docs/Developerguide/snapshot-snapshot.md" >}}) - [SNAPSHOT.TABLES\_SNAP\_TIMESTAMP]({{< relref "./docs/Developerguide/snapshot-tables_snap_timestamp.md" >}}) - [WDR Snapshot Data Table]({{< relref "./docs/Developerguide/wdr-snapshot-data-table.md" >}}) + - [Logical Replication]({{< relref "./docs/Developerguide/logical-replication.md" >}}) + - [Logical Decoding]({{< relref "./docs/Developerguide/logical-decoding.md" >}}) + - [Overview]({{< relref "./docs/Developerguide/overview.md) + - [Logical Decoding by SQL Function Interfaces]({{< relref "./docs/Developerguide/logical-decoding-by-sql-function-interfaces.md" >}}) + - [Replicating Data Using the Logical Replication Tool]({{< relref "./docs/Developerguide/replicating-data-using-the-logical-replication-tool.md" >}}) + - [Foregin Data Wrapper]({{< relref "./docs/Developerguide/foregin-data-wrapper.md" >}}) + - [oracle\_fdw]({{< relref "./docs/Developerguide/oracle_fdw.md" >}}) + - [mysql\_fdw]({{< relref "./docs/Developerguide/mysql_fdw.md" >}}) + - [postgres\_fdw]({{< relref "./docs/Developerguide/postgres_fdw.md" >}}) - [GUC Parameters]({{< relref "./docs/Developerguide/guc-parameters.md" >}}) - [GUC Parameter Usage]({{< relref "./docs/Developerguide/guc-parameter-usage.md" >}}) - [File Location]({{< relref "./docs/Developerguide/file-location.md" >}})