PostgreSQL

此组件允许使用 PostgreSQL (Postgres) 作为 Dapr 的状态存储，使用 “v2” 组件。请参阅此指南了解如何创建和应用状态存储配置。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: state.postgresql
  # 注意：设置 "version" 为 "v2" 是使用组件 v2 的必需项
  version: v2
  metadata:
    # 连接字符串
    - name: connectionString
      value: "<CONNECTION STRING>"
    # 单独的连接参数 - 可用于覆盖 connectionString 参数
    #- name: host
    #  value: "localhost"
    #- name: hostaddr
    #  value: "127.0.0.1"
    #- name: port
    #  value: "5432"
    #- name: database
    #  value: "my_db"
    #- name: user
    #  value: "postgres"
    #- name: password
    #  value: "example"
    #- name: sslRootCert
    #  value: "/path/to/ca.crt"
    # 数据库操作超时时间，作为 Go duration 或秒数（可选）
    #- name: timeout
    #  value: 20
    # 存储数据的表前缀（可选）
    #- name: tablePrefix
    #  value: ""
    # Dapr 用于存储元数据的表名称（可选）
    #- name: metadataTableName
    #  value: "dapr_metadata"
    # 清理过期行的时间间隔（秒）（可选）
    #- name: cleanupInterval
    #  value: "1h"
    # 此组件连接池的最大连接数（可选）
    #- name: maxConns
    #  value: 0
    # 连接的最大空闲时间，超过此时间后将关闭连接（可选）
    #- name: connectionMaxIdleTime
    #  value: 0
    # 控制执行查询的默认模式（可选）
    #- name: queryExecMode
    #  value: ""
    # 如果希望将 PostgreSQL 用作 actor 或工作流的状态存储，请取消注释（可选）
    #- name: actorStateStore
    #  value: "true"

规范元数据字段

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

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

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

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

使用 Microsoft Entra ID 进行身份验证

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

使用 AWS IAM 进行身份验证

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

其他元数据选项

设置 PostgreSQL

• Self-Hosted

高级

v1 和 v2 之间的差异

PostgreSQL 状态存储 v2 在 Dapr 1.13 中引入。现有的 v1 仍然可用，并未被弃用。

在 v2 组件中，表架构已进行了重大更改，旨在提高性能和可靠性。最值得注意的是，Dapr 存储的值现在为 BYTEA 类型，这允许更快的查询，并且在某些情况下比以前使用的 JSONB 列更节省空间。
然而，由于此更改，v2 组件不支持 Dapr 状态存储查询 API。

此外，在 v2 组件中，ETag 现在是随机 UUID，这确保了与其他 PostgreSQL 兼容数据库（如 CockroachDB）的更好兼容性。

由于这些更改，v1 和 v2 组件无法从同一个表读取或写入数据。在此阶段，也无法在两个版本的组件之间迁移数据。

以人类可读格式显示数据

PostgreSQL v2 组件将状态的值存储在 value 列中，该列的类型为 BYTEA。大多数 PostgreSQL 工具（包括 pgAdmin）将值视为二进制，默认情况下不会以人类可读的形式显示。

如果您想检查状态存储中的值，并且您知道它不是二进制数据（例如，JSON 数据），您可以使用如下查询以人类可读的形式显示值：

-- 将 "state" 替换为您环境中的状态表的名称
SELECT *, convert_from(value, 'utf-8') FROM state;

TTL 和清理

此状态存储支持使用 Dapr 存储的记录的生存时间（TTL）。使用 Dapr 存储数据时，您可以设置 ttlInSeconds 元数据属性来指示数据应在多少秒后被视为"过期"。

由于 PostgreSQL 没有内置的 TTL 支持，这是通过在状态表中添加一个列来实现的，该列指示数据何时应被视为"过期"。即使仍物理存储在数据库中，“过期"的记录也不会返回给调用方。后台"垃圾收集器"会定期扫描状态表中的过期行并删除它们。

您可以使用 cleanupInterval 元数据属性设置过期记录的删除时间间隔，默认为 3600 秒（即 1 小时）。

• 较长的间隔需要较少的过期行扫描频率，但可能需要存储过期记录更长时间，可能需要更多的存储空间。如果您计划在状态表中存储许多具有短 TTL 的记录，请考虑将 cleanupInterval 设置为较小的值；例如，5m（5 分钟）。
• 如果您不计划将 TTL 与 Dapr 和 PostgreSQL 状态存储一起使用，您应该考虑将 cleanupInterval 设置为 <= 0 的值（例如，0 或 -1）以禁用定期清理并减少数据库的负载。

相关链接

• Dapr 组件的基本架构
• 阅读此指南以获取有关配置状态存储组件的说明
• 状态管理构建块