From 84402ba8f18828f10bb9f12f5aa99ff5610b65bf Mon Sep 17 00:00:00 2001 From: AkhilaC <3939554+akhilac1@users.noreply.github.com> Date: Wed, 28 Sep 2022 04:02:24 +0530 Subject: [PATCH] postgres configuration store (#2800) * postgres configuration store Signed-off-by: akhilac1 * Added example for subscribe request Signed-off-by: akhilac1 * added pool_max_conns to example connection string Signed-off-by: akhilac1 * added recommendation to use single subscription with multiple keys Signed-off-by: akhilac1 * fixed review comments Signed-off-by: akhilac1 Signed-off-by: akhilac1 Signed-off-by: Mark Fussell Co-authored-by: Mark Fussell --- .../postgres-configuration-store.md | 116 ++++++++++++++++++ .../configuration_stores/generic.yaml | 6 + 2 files changed, 122 insertions(+) create mode 100644 daprdocs/content/en/reference/components-reference/supported-configuration-stores/postgres-configuration-store.md diff --git a/daprdocs/content/en/reference/components-reference/supported-configuration-stores/postgres-configuration-store.md b/daprdocs/content/en/reference/components-reference/supported-configuration-stores/postgres-configuration-store.md new file mode 100644 index 000000000..35c74f030 --- /dev/null +++ b/daprdocs/content/en/reference/components-reference/supported-configuration-stores/postgres-configuration-store.md @@ -0,0 +1,116 @@ +--- +type: docs +title: "Postgres" +linkTitle: "Postgres" +description: Detailed information on the Postgres configuration store component +aliases: + - "/operations/components/setup-configuration-store/supported-configuration-stores/setup-postgres/" +--- + +## Component format + +To set up an Postgres configuration store, create a component of type `configuration.postgres` + +```yaml +apiVersion: dapr.io/v1alpha1 +kind: Component +metadata: + name: +spec: + type: configuration.postgres + version: v1 + metadata: + - name: connectionString + value: "host=localhost user=postgres password=example port=5432 connect_timeout=10 database=config" + - name: table # name of the table which holds configuration information + value: "[your_configuration_table_name]" + - name: connMaxIdleTime # max timeout for connection + value : "15s" + +``` + +{{% alert title="Warning" color="warning" %}} +The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described [here]({{< ref component-secrets.md >}}). +{{% /alert %}} + +## Spec metadata fields + +| Field | Required | Details | Example | +|--------------------|:--------:|---------|---------| +| connectionString | Y | The connection string for PostgreSQL. Default pool_max_conns = 5 | `"host=localhost user=postgres password=example port=5432 connect_timeout=10 database=dapr_test pool_max_conns=10"` +| table | Y | table name for configuration information. | `configTable` + +## Set up Postgres as Configuration Store + +1. Start Postgres Database +1. Connect to the Postgres database and setup a configuration table with following schema - + +| Field | Datatype | Nullable |Details | +|--------------------|:--------:|---------|---------| +| KEY | VARCHAR | N |Holds `"Key"` of the configuration attribute | +| VALUE | VARCHAR | N |Holds Value of the configuration attribute | +| VERSION | VARCHAR | N | Holds version of the configuration attribute +| METADATA | JSON | Y | Holds Metadata as JSON + +```console +CREATE TABLE IF NOT EXISTS table_name ( + KEY VARCHAR NOT NULL, + VALUE VARCHAR NOT NULL, + VERSION VARCHAR NOT NULL, + METADATA JSON ); +``` +3. Create a TRIGGER on configuration table. An example function to create a TRIGGER is as follows - +```console +CREATE OR REPLACE FUNCTION configuration_event() RETURNS TRIGGER AS $$ + DECLARE + data json; + notification json; + + BEGIN + + IF (TG_OP = 'DELETE') THEN + data = row_to_json(OLD); + ELSE + data = row_to_json(NEW); + END IF; + + notification = json_build_object( + 'table',TG_TABLE_NAME, + 'action', TG_OP, + 'data', data); + + PERFORM pg_notify('config',notification::text); + RETURN NULL; + END; +$$ LANGUAGE plpgsql; +``` +4. Create the trigger with data encapsulated in the field labelled as `data` +```ps +notification = json_build_object( + 'table',TG_TABLE_NAME, + 'action', TG_OP, + 'data', data); +``` +5. The channel mentioned as attribute to `pg_notify` should be used when subscribing for configuration notifications +6. Since this is a generic created trigger, map this trigger to `configuration table` +```console +CREATE TRIGGER config +AFTER INSERT OR UPDATE OR DELETE ON configTable + FOR EACH ROW EXECUTE PROCEDURE notify_event(); +``` +7. In the subscribe request add an additional metadata field with key as `pgNotifyChannel` and value should be set to same `channel name` mentioned in `pg_notify`. From the above example, it should be set to `config` + +{{% alert title="Note" color="primary" %}} +When calling `subscribe` API, `metadata.pgNotifyChannel` should be used to specify the name of the channel to listen for notifications from Postgres configuration store. + +Any number of keys can be added to a subscription request. Each subscription uses an exclusive database connection. It is strongly recommended to subscribe to multiple keys within a single subscription. This helps optimize the number of connections to the database. + +Example of subscribe HTTP API - +```ps +curl --location --request GET 'http://:/configuration/postgres/subscribe?key=&key=&metadata.pgNotifyChannel=' +``` +{{% /alert %}} + +## Related links +- [Basic schema for a Dapr component]({{< ref component-schema >}}) +- [Configuration building block]({{< ref configuration-api-overview >}}) diff --git a/daprdocs/data/components/configuration_stores/generic.yaml b/daprdocs/data/components/configuration_stores/generic.yaml index 19ff8f017..c6d180327 100644 --- a/daprdocs/data/components/configuration_stores/generic.yaml +++ b/daprdocs/data/components/configuration_stores/generic.yaml @@ -3,8 +3,14 @@ state: Alpha version: v1 since: "1.5" +- component: Postgres + link: postgres-configuration-store + state: Alpha + version: v1 + since: "1.9" - component: Azure App Configuration link: azure-appconfig-configuration-store state: Alpha version: v1 since: "1.9" +