Merge pull request #5789 from EnterpriseDB/dev/pgd/BDR-5141-extension…

…-usage

PGD: add documentation section considering extension usage

product_docs/docs/pgd/5/appusage/extensions.mdx

@@ -0,0 +1,77 @@
+---
+title: Using extensions with PGD
+navTitle: Extension usage
+deepToC: true
+---
+
+## PGD and other PostgreSQL extensions
+
+PGD is implemented as a PostgreSQL extension (see [Supported Postgres database servers](../overview/#supported-postgres-database-servers)), taking advantage of PostgreSQL's expandability and flexibility to modify low level system behavior to provide multi-master replication.
+
+In principle other extensions - both those provided by community PostgreSQL and EPAS, as well as third-party extensions, can be used together with PGD, however the distributed nature of PGD means selection and installation of extensions should be carefully considered and planned.
+
+### Extensions providing logical decoding
+
+Extensions providing logical decoding, such as [wal2json](https://github.com/eulerto/wal2json), may in theory work with PGD, but there is no support for failover, meaning any WAL stream being read from such an extension may be interrupted.
+
+### Extensions providing replication and/or HA functionality
+
+Any extension extending PostgreSQL with functionality related to replication and/or HA/failover is unlikely to work well with PGD, and may even be detrimental to the health of the PGD cluster, so should be avoided.
+
+## Supported extensions
+
+This section lists extensions which are explicitly supported by PGD.
+
+### EDB Advanced Server Table Access methods
+
+The [EDB Advanced Storage Pack](/pg_extensions/advanced_storage_pack/) provides a selection of table access methods (TAMs) implemented as extensions of which the following are certified for use with PGD:
+
+ - [Autocluster](/pg_extensions/advanced_storage_pack/#autocluster)
+ - [Refdata](/pg_extensions/advanced_storage_pack/#refdata)
+
+For more details, see [Table access methods](table-access-methods).
+
+### pgaudit
+
+PGD has been modified to ensure compatibility with the [pgaudit](https://www.pgaudit.org/) extension.
+See [Postgres settings](../postgres-configuration/#postgres-settings) for configuration information.
+
+
+## Installing extensions
+
+PostgreSQL extensions provide SQL objects such as functions and datatypes, and optionally also one or more shared libraries, which must be loaded into the PostgreSQL backend before the extension can be installed and used.
+
+!!! Warning
+
+    The relevant extension packages must be available on all nodes in the cluster, otherwise extension installation may fail and impact cluster stability.
+
+If PGD is deployed using [Trusted Postgres Architect](/tpa/latest/), extensions should be configured via that. 
+For more details see [Adding Postgres extensions](/tpa/latest/reference/postgres_extension_configuration).
+
+The following sections are relevant for manually configured PGD installations.
+
+### Configuring "shared_preload_libraries"
+
+If an extension provides a shared library, this library must be included in the [shared_preload_libraries](https://www.postgresql.org/docs/current/runtime-config-client.html#GUC-SHARED-PRELOAD-LIBRARIES) configuration parameter before the extension itself is installed.
+
+`shared_preload_libraries` consists of a comma-separated list of extension names. 
+It must include the `bdr` extension. 
+The order in which other extensions are specified is generally unimportant, however if using the `pgaudit` extension, `pgaudit` **must** appear in the list before `bdr`.
+
+`shared_preload_libraries` should be configured on all nodes in the cluster before installing the extension with `CREATE EXTENSION`. 
+Note that it requires a PostgreSQL restart to activate the new configuration.
+
+See also [Postgres settings](../postgres-configuration/#postgres-settings).
+
+
+### Installing the extension
+
+The extension itself is installed with the `CREATE EXTENSION` command. 
+This only needs to be carried out on one node in the cluster - PGD's DDL replication will ensure that it propagates to all other nodes.
+
+!!! Warning
+
+    Do not attempt to install extensions manually on each node by e.g. disabling DDL replication before executing `CREATE EXTENSION`.
+
+    Do not use a command such as `bdr.replicate_ddl_command()` to execute `CREATE EXTENSION`.
+

product_docs/docs/pgd/5/appusage/index.mdx

@@ -9,6 +9,7 @@ navigation:
 - nodes-with-differences
 - rules
 - timing
+- extensions
 - table-access-methods
 - feature-compatibility
 ---
@@ -32,6 +33,8 @@ Developing an application with PGD is mostly the same as working with any Postgr
 
 * [Timing considerations](timing) shows how the asynchronous/synchronous replication might affect an application's view of data and notes functions to mitigate stale reads.
 
+* [Extension usage](extensions) explains how to select and install extensions on PGD and configure them.
+
 * [Table access methods](table-access-methods) (TAMs) notes the TAMs available with PGD and how to enable them.
 
 * [Feature compatibility](feature-compatibility) shows which server features work with which commit scopes and which commit scopes can be daisy chained together.