diff --git a/concepts/bindings/README.md b/concepts/bindings/README.md index 2daea43a8..ec7648b72 100644 --- a/concepts/bindings/README.md +++ b/concepts/bindings/README.md @@ -23,15 +23,17 @@ Every binding has its own unique set of properties. Click the name link to see t |------|:----------------:|:-----------------:|--------| | [Cron (Scheduler)](../../reference/specs/bindings/cron.md) | ✅ | ✅ | Experimental | | [HTTP](../../reference/specs/bindings/http.md) | | ✅ | Experimental | +| [InfluxDB](../../reference/specs/bindings/influxdb.md) | | ✅ | Experimental | | [Kafka](../../reference/specs/bindings/kafka.md) | ✅ | ✅ | Experimental | | [Kubernetes Events](../../reference/specs/bindings/kubernetes.md) | ✅ | | Experimental | | [MQTT](../../reference/specs/bindings/mqtt.md) | ✅ | ✅ | Experimental | +| [PostgreSql](../../reference/specs/bindings/postgres.md) | | ✅ | Experimental | | [RabbitMQ](../../reference/specs/bindings/rabbitmq.md) | ✅ | ✅ | Experimental | | [Redis](../../reference/specs/bindings/redis.md) | | ✅ | Experimental | | [Twilio](../../reference/specs/bindings/twilio.md) | | ✅ | Experimental | | [Twitter](../../reference/specs/bindings/twitter.md) | ✅ | ✅ | Experimental | | [SendGrid](../../reference/specs/bindings/sendgrid.md) | | ✅ | Experimental | -| [InfluxDB](../../reference/specs/bindings/influxdb.md) | | ✅ | Experimental | + ### Amazon Web Service (AWS) diff --git a/reference/specs/bindings/postgres.md b/reference/specs/bindings/postgres.md new file mode 100644 index 000000000..19151b335 --- /dev/null +++ b/reference/specs/bindings/postgres.md @@ -0,0 +1,125 @@ +# PostgrSQL Binding Spec + +```yaml +apiVersion: dapr.io/v1alpha1 +kind: Component +metadata: + name: + namespace: +spec: + type: bindings.postgres + metadata: + - name: url # Required + value: +``` + +> **Note:** In production never place passwords or secrets within Dapr components. For information on securely storing and retrieving secrets refer to [Setup Secret Store](../../../howto/setup-secret-store) + +The PostgrSQL binding uses [pgx connection pool](https://github.com/jackc/pgx) internally so the `url` parameter can be any valid connection string, either in a `DSN` or `URL` format: + +**Example DSN** + +```shell +user=dapr password=secret host=dapr.example.com port=5432 dbname=dapr sslmode=verify-ca +``` + +**Example URL** + +```shell +postgres://dapr:secret@dapr.example.com:5432/dapr?sslmode=verify-ca +``` + +Both methods also support connection pool configuration variables: + +* `pool_min_conns`: integer 0 or greater +* `pool_max_conns`: integer greater than 0 +* `pool_max_conn_lifetime`: duration string +* `pool_max_conn_idle_time`: duration string +* `pool_health_check_period`: duration string + +## Output Binding Supported Operations + +* `exec` +* `query` +* `close` + +### exec + +The `exec` operation can be used for DDL operations (like table creation), as well as `INSERT`, `UPDATE`, `DELETE` operations which return only metadata (e.g. number of affected rows). + +**Request** + +```json +{ + "operation": "exec", + "metadata": { + "sql": "INSERT INTO foo (id, c1, ts) VALUES (1, 'demo', '2020-09-24T11:45:05Z07:00')" + } +} +``` + +**Response** + +```json +{ + "metadata": { + "operation": "exec", + "duration": "294µs", + "start-time": "2020-09-24T11:13:46.405097Z", + "end-time": "2020-09-24T11:13:46.414519Z", + "rows-affected": "1", + "sql": "INSERT INTO foo (id, c1, ts) VALUES (1, 'demo', '2020-09-24T11:45:05Z07:00')" + } +} +``` + +### query + +The `query` operation is used for `SELECT` statements, which returns the metadata along with data in a form of an array of row values. + +**Request** + +```json +{ + "operation": "query", + "metadata": { + "sql": "SELECT * FROM foo WHERE id < 3" + } +} +``` + +**Response** + +```json +{ + "metadata": { + "operation": "query", + "duration": "432µs", + "start-time": "2020-09-24T11:13:46.405097Z", + "end-time": "2020-09-24T11:13:46.420566Z", + "sql": "SELECT * FROM foo WHERE id < 3" + }, + "data": "[ + [0,\"test-0\",\"2020-09-24T04:13:46Z\"], + [1,\"test-1\",\"2020-09-24T04:13:46Z\"], + [2,\"test-2\",\"2020-09-24T04:13:46Z\"] + ]" +} +``` + +### close + +Finally, the `close` operation can be used to explicitly close the DB connection and return it to the pool. This operation doesn't have any response. + +**Request** + +```json +{ + "operation": "close" +} +``` + + +> Note, the PostgreSql binding itself doesn't prevent SQL injection, like with any database application, validate the input before executing query. + +