mirror of https://github.com/dapr/docs.git
126 lines
2.8 KiB
Markdown
126 lines
2.8 KiB
Markdown
# PostgrSQL Binding Spec
|
|
|
|
```yaml
|
|
apiVersion: dapr.io/v1alpha1
|
|
kind: Component
|
|
metadata:
|
|
name: <NAME>
|
|
namespace: <NAMESPACE>
|
|
spec:
|
|
type: bindings.postgres
|
|
metadata:
|
|
- name: url # Required
|
|
value: <CONNECTION_STRING>
|
|
```
|
|
|
|
> **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.
|
|
|
|
|