Relational JDBC

该实现基于 Quarkus 进行数据源管理，支持在启动时通过环境变量或 JVM -D 参数进行配置。更多信息请参阅 Quarkus 配置参考。

我们提供了 2 种配置持久化后端的方式：

1. 使用用户名和密码的 Relational JDBC 元数据存储

使用环境变量：

POLARIS_PERSISTENCE_TYPE=relational-jdbc

QUARKUS_DATASOURCE_USERNAME=<your-username>
QUARKUS_DATASOURCE_PASSWORD=<your-password>
QUARKUS_DATASOURCE_JDBC_URL=<jdbc-url-of-postgres>

使用属性文件：

polaris.persistence.type=relational-jdbc
quarkus.datasource.jdbc.username=<your-username>
quarkus.datasource.jdbc.password=<your-password>
quarkus.datasource.jdbc.jdbc-url=<jdbc-url-of-postgres>

2. 使用 IAM AWS 身份验证的 AWS Aurora PostgreSQL 元数据存储

polaris.persistence.type=relational-jdbc
quarkus.datasource.jdbc.url=jdbc:postgresql://polaris-cluster.cluster-xyz.us-east-1.rds.amazonaws.com:6160/polaris
quarkus.datasource.jdbc.additional-jdbc-properties.wrapperPlugins=iam
quarkus.datasource.username=dbusername
quarkus.datasource.db-kind=postgresql
quarkus.datasource.jdbc.additional-jdbc-properties.ssl=true
quarkus.datasource.jdbc.additional-jdbc-properties.sslmode=require
quarkus.datasource.credentials-provider=aws

quarkus.rds.credentials-provider.aws.use-quarkus-client=true
quarkus.rds.credentials-provider.aws.username=dbusername
quarkus.rds.credentials-provider.aws.hostname=polaris-cluster.cluster-xyz.us-east-1.rds.amazonaws.com
quarkus.rds.credentials-provider.aws.port=6160

这是基本配置。有关更多详细信息，请参阅 Quarkus 插件文档。

关系型 JDBC 元数据存储目前依赖于 Quarkus 管理的数据源，仅支持 PostgresSQL 和 H2 数据库。目前，官方文档仅针对 PostgreSQL 的使用场景提供。请参阅此处的文档：在 Quarkus 中配置数据源。

此外，重试可通过 polaris.persistence.relational.jdbc.* 属性进行配置；请参阅配置 Polaris 章节。

引导启动 Polaris

在使用配备关系型 JDBC 后端的 Polaris 之前，您必须先引导启动元数据存储，以创建必要的 schema 和初始 realm。此操作通过 Admin Tool 完成。

使用 Docker：

docker run --rm -it \
  --env="polaris.persistence.type=relational-jdbc" \
  --env="quarkus.datasource.username=<your-username>" \
  --env="quarkus.datasource.password=<your-password>" \
  --env="quarkus.datasource.jdbc.url=<jdbc-url-of-postgres>" \
  apache/polaris-admin-tool:latest bootstrap -r <realm-name> -c <realm-name>,<client-id>,<client-secret>

使用独立 JAR 包：

java \
  -Dpolaris.persistence.type=relational-jdbc \
  -Dquarkus.datasource.username=<your-username> \
  -Dquarkus.datasource.password=<your-password> \
  -Dquarkus.datasource.jdbc.url=<jdbc-url-of-postgres> \
  -jar polaris-admin-tool.jar bootstrap -r <realm-name> -c <realm-name>,<client-id>,<client-secret>

有关 bootstrap 命令及其他管理操作的更多详情，请参阅 Admin Tool 文档。

架构升级

Polaris 不会执行自动的架构迁移。引导过程（bootstrap）会应用完整的 schema-vN.sql 脚本，并将架构版本记录在 polaris_schema.version 表中；将现有数据库升级到更新的架构版本是一项需要运维人员手动执行的操作。

升级到架构 v5

架构 v5 使 events.catalog_id 列变为可空：不作用于某个 catalog 的事件（principal、策略、限流等）将存储 NULL，而不是 v5 之前的架构所要求的遗留占位字符串 __realm__（该占位符仅存在于 1.6.0 的候选发布版本中）。

在你完成升级之前，服务器仍能正常工作：它会在启动时从 polaris_schema.version 表中检测到低于 5 的架构版本，并继续为非 catalog 作用域的事件写入遗留占位符。要升级现有的 v3/v4 数据库，请执行以下一次性 SQL（如有需要，请调整 ALTER 语法以适配你的数据库——下面的语句适用于 PostgreSQL、CockroachDB 和 H2），然后重启 Polaris：

DROP TABLE IF EXISTS polaris_schema.idempotency_records;
ALTER TABLE polaris_schema.events ALTER COLUMN catalog_id DROP NOT NULL;
UPDATE polaris_schema.events SET catalog_id = NULL WHERE catalog_id = '__realm__';
UPDATE polaris_schema.version SET version_value = 5 WHERE version_key = 'version';

关系型 JDBC