PostgreSQL 绑定规范

PostgreSQL 绑定组件的详细文档

组件格式

要设置 PostgreSQL 绑定，需创建一个类型为 bindings.postgresql 的组件。请参阅此指南了解如何创建和应用绑定配置。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: bindings.postgresql
  version: v1
  metadata:
    # 连接字符串
    - name: connectionString
      value: "<CONNECTION STRING>"

规范元数据字段

使用连接字符串进行身份验证

使用 PostgreSQL 连接字符串进行身份验证时，以下元数据选项是必需的。

字段必需详情示例
connectionStringYPostgreSQL 数据库的连接字符串。有关如何定义连接字符串的信息，请参阅 PostgreSQL 关于数据库连接的文档。"host=localhost user=postgres password=example port=5432 connect_timeout=10 database=my_db"

使用单独的连接参数进行身份验证

除了使用连接字符串外，您还可以选择指定单独的连接参数。这些参数等同于标准的 PostgreSQL 连接参数。

字段必需详情示例
hostYPostgreSQL 服务器的主机名或 IP 地址"localhost"
hostaddrNPostgreSQL 服务器的 IP 地址（host 的替代选项）"127.0.0.1"
portYPostgreSQL 服务器的端口号"5432"
databaseY要连接的数据库名称"my_db"
userY用于连接的 PostgreSQL 用户"postgres"
passwordYPostgreSQL 用户的密码"example"
sslRootCertNSSL 根证书文件的路径"/path/to/ca.crt"

使用 Microsoft Entra ID 进行身份验证

支持使用 Microsoft Entra ID 对 Azure Database for PostgreSQL 进行身份验证。可以使用 Dapr 支持的所有身份验证方法，包括客户端凭据（“服务主体”）和托管标识。

字段必需详情示例
useAzureADY必须设置为 true 以使组件能够从 Microsoft Entra ID 获取访问令牌。"true"
connectionStringYPostgreSQL 数据库的连接字符串。
必须包含用户，该用户对应于在 PostgreSQL 内部创建的映射到 Microsoft Entra ID 标识的用户名称；这通常是相应主体的名称（例如 Microsoft Entra ID 应用程序的名称）。此连接字符串不应包含任何密码。		"host=mydb.postgres.database.azure.com user=myapplication port=5432 database=my_db sslmode=require"
azureTenantIdNMicrosoft Entra ID 租户的 ID"cd4b2887-304c-…"
azureClientIdN客户端 ID（应用程序 ID）"c7dd251f-811f-…"
azureClientSecretN客户端密钥（应用程序密码）"Ecy3X…"

使用 AWS IAM 进行身份验证

支持使用 AWS IAM 对所有版本的 PostgreSQL 类型组件进行身份验证。 连接字符串中指定的用户必须是数据库中已存在的用户，并且是已授予 rds_iam 数据库角色的 AWS IAM 启用用户。 身份验证基于 AWS 身份验证配置文件，或提供的 AccessKey/SecretKey。 AWS 身份验证令牌将在其过期时间之前动态轮换。

字段必需详情示例
useAWSIAMY必须设置为 true 以使组件能够从 AWS IAM 获取访问令牌。此身份验证方法仅适用于 AWS Relational Database Service for PostgreSQL 数据库。"true"
connectionStringYPostgreSQL 数据库的连接字符串。
必须包含已存在的用户，该用户对应于在 PostgreSQL 内部创建的映射到 AWS IAM 策略的用户名称。此连接字符串不应包含任何密码。请注意，对于 AWS，数据库名称字段由 dbname 表示。		"host=mydb.postgres.database.aws.com user=myapplication port=5432 dbname=my_db sslmode=require"
awsRegionN这保持与现有字段的向后兼容性。它将在 Dapr 1.17 中被弃用。请改用 ‘region’。部署 AWS Relational Database Service 的 AWS 区域。"us-east-1"
awsAccessKeyN这保持与现有字段的向后兼容性。它将在 Dapr 1.17 中被弃用。请改用 ‘accessKey’。与 IAM 账户关联的 AWS 访问密钥"AKIAIOSFODNN7EXAMPLE"
awsSecretKeyN这保持与现有字段的向后兼容性。它将在 Dapr 1.17 中被弃用。请改用 ‘secretKey’。与访问密钥关联的密钥"wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
awsSessionTokenN这保持与现有字段的向后兼容性。它将在 Dapr 1.17 中被弃用。请改用 ‘sessionToken’。要使用的 AWS 会话令牌。仅当您使用临时安全凭证时才需要会话令牌。"TOKEN"

其他元数据选项

字段必需绑定支持详情示例
timeoutN输出数据库操作的超时时间，格式为 Go duration。整数将被解释为秒数。默认为 20s"30s", 30
maxConnsN输出此组件池化的最大连接数。设置为 0 或更小以使用默认值，默认值为 4 或 CPU 数量中的较大者。"4"
connectionMaxIdleTimeN输出在连接池中自动关闭未使用连接之前的最大空闲时间。默认情况下，没有此值，由数据库驱动程序选择。"5m"
queryExecModeN输出控制执行查询的默认模式。默认情况下，Dapr 使用扩展协议并自动准备和缓存预处理语句。但是，这可能与 PGBouncer 等代理不兼容。在这种情况下，使用 exec 或 simple_protocol 可能更合适。"simple_protocol"

URL 格式

PostgreSQL 绑定内部使用 pgx connection pool，因此 connectionString 参数可以是任何有效的连接字符串，格式为 DSN 或 URL：

DSN 示例

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

URL 示例

postgres://dapr:secret@dapr.example.com:5432/my_dapr?sslmode=verify-ca

这两种方法也支持连接池配置变量：

  • pool_min_conns: 整数 0 或更大
  • pool_max_conns: 大于 0 的整数
  • pool_max_conn_lifetime: 持续时间字符串
  • pool_max_conn_idle_time: 持续时间字符串
  • pool_health_check_period: 持续时间字符串

绑定支持

此组件支持输出绑定，具有以下操作：

  • exec
  • query
  • close

参数化查询

此绑定支持参数化查询，允许将 SQL 查询本身与用户提供的值分开。出于安全原因，强烈建议使用参数化查询，因为它们可以防止 SQL 注入攻击。

例如：

-- ❌ 错误！在查询中包含值，并且容易受到 SQL 注入攻击。
SELECT * FROM mytable WHERE user_key = 'something';

-- ✅ 正确！使用参数化查询。
-- 这将使用参数 ["something"] 执行
SELECT * FROM mytable WHERE user_key = $1;

exec

exec 操作可用于 DDL 操作（如表创建），以及仅返回元数据（例如受影响的行数）的 INSERT、UPDATE、DELETE 操作。

params 属性是一个包含 JSON 编码参数数组的字符串。

请求

{
  "operation": "exec",
  "metadata": {
    "sql": "INSERT INTO foo (id, c1, ts) VALUES ($1, $2, $3)",
    "params": "[1, \"demo\", \"2020-09-24T11:45:05Z07:00\"]"
  }
}

响应

{
  "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, $2, $3)"
  }
}

query

query 操作用于 SELECT 语句，它以行值数组的形式返回数据以及元数据。

params 属性是一个包含 JSON 编码参数数组的字符串。

请求

{
  "operation": "query",
  "metadata": {
    "sql": "SELECT * FROM foo WHERE id < $1",
    "params": "[3]"
  }
}

响应

{
  "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 < $1"
  },
  "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

close 操作可用于显式关闭数据库连接并将其返回到池中。此操作没有任何响应。

请求

{
  "operation": "close"
}

相关链接