PostgreSQL binding spec

Detailed documentation on the PostgreSQL binding component

Component format

To setup PostgreSQL binding create a component of type bindings.postgres. See this guide on how to create and apply a binding configuration.

  1. apiVersion: dapr.io/v1alpha1
  2. kind: Component
  3. metadata:
  4. name: <NAME>
  5. namespace: <NAMESPACE>
  6. spec:
  7. type: bindings.postgres
  8. version: v1
  9. metadata:
  10. - name: url # Required
  11. value: <CONNECTION_STRING>

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described here.

Spec metadata fields

FieldRequiredBinding supportDetailsExample
urlYOutputPostgres connection string See here for more details“user=dapr password=secret host=dapr.example.com port=5432 dbname=dapr sslmode=verify-ca”

URL format

The PostgreSQL binding uses pgx connection pool internally so the url parameter can be any valid connection string, either in a DSN or URL format:

Example DSN

  1. user=dapr password=secret host=dapr.example.com port=5432 dbname=dapr sslmode=verify-ca

Example URL

  1. 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

Binding support

This component supports output binding with the following 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

  1. {
  2. "operation": "exec",
  3. "metadata": {
  4. "sql": "INSERT INTO foo (id, c1, ts) VALUES (1, 'demo', '2020-09-24T11:45:05Z07:00')"
  5. }
  6. }

Response

  1. {
  2. "metadata": {
  3. "operation": "exec",
  4. "duration": "294µs",
  5. "start-time": "2020-09-24T11:13:46.405097Z",
  6. "end-time": "2020-09-24T11:13:46.414519Z",
  7. "rows-affected": "1",
  8. "sql": "INSERT INTO foo (id, c1, ts) VALUES (1, 'demo', '2020-09-24T11:45:05Z07:00')"
  9. }
  10. }

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

  1. {
  2. "operation": "query",
  3. "metadata": {
  4. "sql": "SELECT * FROM foo WHERE id < 3"
  5. }
  6. }

Response

  1. {
  2. "metadata": {
  3. "operation": "query",
  4. "duration": "432µs",
  5. "start-time": "2020-09-24T11:13:46.405097Z",
  6. "end-time": "2020-09-24T11:13:46.420566Z",
  7. "sql": "SELECT * FROM foo WHERE id < 3"
  8. },
  9. "data": "[
  10. [0,\"test-0\",\"2020-09-24T04:13:46Z\"],
  11. [1,\"test-1\",\"2020-09-24T04:13:46Z\"],
  12. [2,\"test-2\",\"2020-09-24T04:13:46Z\"]
  13. ]"
  14. }

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

  1. {
  2. "operation": "close"
  3. }

Note, the PostgreSql binding itself doesn’t prevent SQL injection, like with any database application, validate the input before executing query.

Last modified February 18, 2022: Update setup-jetstream.md (#2200) (428d8c2)