Doc: add extension modules reference

docs/modules/auto-explain.md

@@ -0,0 +1,55 @@
+---
+title: auto_explain
+---
+
+# auto_explain
+
+The `auto_explain` module logs the execution plans of slow statements automatically, without having to run `EXPLAIN` by hand.
+
+In Apache Cloudberry, `auto_explain` takes effect only in regular sessions on the coordinator. When the library is loaded in a segment process or in a utility-mode connection, it does nothing and does not define its configuration parameters. Otherwise, it works like the PostgreSQL `auto_explain` module. With `auto_explain.log_analyze` enabled, the logged plan also includes the per-slice execution statistics collected from the segments.
+
+## Load the module
+
+`auto_explain` is built and installed by a default Apache Cloudberry build. It is a library, not an extension: it provides no SQL objects, and you do not run `CREATE EXTENSION` for it.
+
+To load the module into a single session, run the following command as a superuser:
+
+```sql
+LOAD 'auto_explain';
+```
+
+To load it into all sessions, add `auto_explain` to `session_preload_libraries` or `shared_preload_libraries`. A change to `shared_preload_libraries` requires a restart of the cluster. Preloading lets you track slow queries whenever they happen, at the cost of some overhead for all queries.
+
+## Configuration parameters
+
+The module does nothing until `auto_explain.log_min_duration` is set to a value other than `-1`. Only superusers can change these parameters.
+
+| Parameter | Description |
+|-----------|-------------|
+| `auto_explain.log_min_duration` | Minimum statement execution time, in milliseconds, above which the plan is logged. `0` logs all plans. `-1` (the default) turns logging off. |
+| `auto_explain.log_analyze` | Logs `EXPLAIN ANALYZE` output instead of `EXPLAIN` output. |
+| `auto_explain.log_buffers` | Logs buffer usage. Takes effect only when `log_analyze` is on. |
+| `auto_explain.log_wal` | Logs WAL usage. Takes effect only when `log_analyze` is on. |
+| `auto_explain.log_timing` | Collects per-node timing. Takes effect only when `log_analyze` is on. |
+| `auto_explain.log_triggers` | Includes trigger statistics. Takes effect only when `log_analyze` is on. |
+| `auto_explain.log_verbose` | Logs `EXPLAIN VERBOSE` output. |
+| `auto_explain.log_settings` | Logs the modified configuration parameters that affect query planning. |
+| `auto_explain.log_format` | Output format: `text`, `xml`, `json`, or `yaml`. |
+| `auto_explain.log_level` | Log level for the plan. |
+| `auto_explain.log_nested_statements` | Logs statements that are run inside functions. |
+| `auto_explain.sample_rate` | Fraction of statements to process in each session. |
+
+## Example
+
+```sql
+LOAD 'auto_explain';
+SET auto_explain.log_min_duration = 0;
+SET auto_explain.log_analyze = true;
+SELECT count(*) FROM pg_class;
+```
+
+The plan of the `SELECT` statement is written to the coordinator log.
+
+## Module documentation
+
+See [auto_explain](https://www.postgresql.org/docs/14/auto-explain.html) in the PostgreSQL documentation for details about each configuration parameter.

docs/modules/btree-gin.md

@@ -0,0 +1,21 @@
+---
+title: btree_gin
+---
+
+# btree_gin
+
+The `btree_gin` module provides sample generalized inverted index (GIN) operator classes that implement B-tree equivalent behavior for a number of data types.
+
+The Apache Cloudberry `btree_gin` module is equivalent to the PostgreSQL `btree_gin` module. There are no MPP-specific considerations for the module.
+
+## Install and register the module
+
+`btree_gin` is built and installed by a default Apache Cloudberry build. Register the extension in each database in which you want to use it:
+
+```sql
+CREATE EXTENSION btree_gin;
+```
+
+## Module documentation
+
+See [btree_gin](https://www.postgresql.org/docs/14/btree-gin.html) in the PostgreSQL documentation for the list of supported data types and usage examples.

docs/modules/citext.md

@@ -0,0 +1,21 @@
+---
+title: citext
+---
+
+# citext
+
+The `citext` module provides a case-insensitive character string data type, `citext`. Essentially, it internally calls the `lower()` function when comparing values. Otherwise, it behaves almost exactly like the `text` data type.
+
+The Apache Cloudberry `citext` module is equivalent to the PostgreSQL `citext` module. There are no MPP-specific considerations for the module.
+
+## Install and register the module
+
+`citext` is built and installed by a default Apache Cloudberry build. Register the extension in each database in which you want to use it:
+
+```sql
+CREATE EXTENSION citext;
+```
+
+## Module documentation
+
+See [citext](https://www.postgresql.org/docs/14/citext.html) in the PostgreSQL documentation for details about the data type, operators, and functions that this module defines.

docs/modules/dblink.md

@@ -0,0 +1,135 @@
+---
+title: dblink
+---
+
+# dblink
+
+The `dblink` module supports connections to other databases from within a database session. The other database can be in the same Apache Cloudberry cluster, in another Apache Cloudberry cluster, or in a PostgreSQL server.
+
+:::note
+`dblink` is intended for short ad hoc queries in other databases. It is not a replacement for external tables, foreign tables, or data migration tools.
+:::
+
+The Apache Cloudberry `dblink` module is a modified version of the PostgreSQL `dblink` module. See [MPP considerations](#mpp-considerations) for the restrictions that apply.
+
+## Install and register the module
+
+`dblink` is built and installed by a default Apache Cloudberry build. Register the extension in each database in which you want to use it:
+
+```sql
+CREATE EXTENSION dblink;
+```
+
+## MPP considerations
+
+- A named or implicit (unnamed) `dblink` connection exists only in the coordinator process that serves your session. A statement that modifies table data, such as `INSERT INTO ... SELECT ... FROM dblink(...)`, runs the `dblink()` call in a different process, which cannot see that connection. In such statements, pass the connection string directly to `dblink()`:
+
+    ```sql
+    CREATE TABLE testdbllocal (a int, b text) DISTRIBUTED BY (a);
+    INSERT INTO testdbllocal
+      SELECT * FROM dblink('dbname=postgres', 'SELECT * FROM testdblink') AS dbltab(id int, product text);
+    ```
+
+    If you use a connection name instead, the statement fails with the error `could not establish connection`, and the detail `missing "=" after "<connection name>" in connection info string`.
+
+- Asynchronous queries are not supported. The extension does not create the `dblink_send_query()`, `dblink_is_busy()`, and `dblink_get_result()` functions.
+
+- A non-superuser must specify both `host` and `password` in the connection string of `dblink_connect()` and `dblink()`, even to connect to a local database. Otherwise, the call fails with `host is required` or `password is required`. If a non-superuser does not specify `user`, the name of the current database user is used.
+
+## Use dblink
+
+The following steps show the basic use of `dblink`. The examples use `dblink_connect()` to create a connection to a database and `dblink()` to run an SQL query.
+
+1. Create a sample table in the `postgres` database:
+
+    ```sql
+    CREATE TABLE testdblink (a int, b text) DISTRIBUTED BY (a);
+    INSERT INTO testdblink VALUES (1, 'Cheese'), (2, 'Fish');
+    ```
+
+2. Log in to a different database, for example `testdb`, as a superuser, and register the extension if you have not done so:
+
+    ```sql
+    CREATE EXTENSION dblink;
+    ```
+
+3. Use `dblink_connect()` to create either an implicit or a named connection to another database. The connection string is a `libpq`-style keyword/value string. This example creates a connection named `mylocalconn` to the `postgres` database on the local cluster:
+
+    ```sql
+    SELECT dblink_connect('mylocalconn', 'dbname=postgres user=gpadmin');
+    ```
+
+    ```text
+     dblink_connect
+    ----------------
+     OK
+    (1 row)
+    ```
+
+4. Use `dblink()` to run a query over the connection. The function returns `record`, so you must specify the names and types of the returned columns:
+
+    ```sql
+    SELECT * FROM dblink('mylocalconn', 'SELECT * FROM testdblink') AS dbltab(id int, product text);
+    ```
+
+    ```text
+     id | product
+    ----+---------
+      1 | Cheese
+      2 | Fish
+    (2 rows)
+    ```
+
+5. Close the connection when you no longer need it:
+
+    ```sql
+    SELECT dblink_disconnect('mylocalconn');
+    ```
+
+To connect to a remote system, include the host and password information in the connection string. For example, to create an implicit connection:
+
+```sql
+SELECT dblink_connect('host=remotehost port=5432 dbname=postgres user=gpadmin password=secret');
+```
+
+### Use dblink as a non-superuser
+
+A non-superuser must include the host and the password in the connection string of `dblink_connect()`. For example, the user `test_user` can create a connection to the local coordinator host `cdw` with this command:
+
+```sql
+SELECT dblink_connect('host=cdw port=5432 dbname=postgres user=test_user password=secret');
+```
+
+In addition, the remote server must actually request a password for the connection. If it does not (for example, with `trust` authentication), the call fails with `password is required`.
+
+To let non-superusers create connections that do not require a password, use the `dblink_connect_u()` function. It is identical to `dblink_connect()`, except that it skips these checks. `dblink_connect_u()` is installed with all privileges revoked from `PUBLIC`, so only superusers can call it until you grant the `EXECUTE` privilege on it.
+
+:::caution
+Grant `EXECUTE` on `dblink_connect_u()` only to users that you trust. If the target system has users with an authentication method that does not involve a password, a non-superuser who can call `dblink_connect_u()` can impersonate such a user and escalate privileges. Also, a password can be supplied from the server environment, such as a `~/.pgpass` file that belongs to the operating system user that runs the server.
+:::
+
+1. As a superuser, grant the `EXECUTE` privilege on the `dblink_connect_u()` functions:
+
+    ```sql
+    GRANT EXECUTE ON FUNCTION dblink_connect_u(text) TO test_user;
+    GRANT EXECUTE ON FUNCTION dblink_connect_u(text, text) TO test_user;
+    ```
+
+2. As `test_user`, create a connection without a password, and use it:
+
+    ```sql
+    SELECT dblink_connect_u('testconn', 'dbname=postgres user=test_user');
+    SELECT * FROM dblink('testconn', 'SELECT * FROM testdblink') AS dbltab(id int, product text);
+    ```
+
+### Use dblink with SSL-encrypted connections
+
+To connect over an encrypted connection, specify the `sslmode` keyword in the connection string. Set `sslmode` to at least `require` to disallow unencrypted connections. For example:
+
+```sql
+SELECT dblink_connect('con_sales', 'dbname=sales host=cdw user=gpadmin sslmode=require');
+```
+
+## Module documentation
+
+See [dblink](https://www.postgresql.org/docs/14/dblink.html) in the PostgreSQL documentation for details about the individual functions in this module.