IMPORTANT: Developer documentation for the current main branch. This content is unreleased and may change before the next Polaris release. For stable user documentation, see the latest release docs.

Relational JDBC

This implementation leverages Quarkus for datasource management and supports configuration through environment variables or JVM -D flags at startup. For more information, refer to the Quarkus configuration reference.

We have 2 options for configuring the persistence backend:

1. Relational JDBC metastore with username and password🔗

Using environment variables:

1POLARIS_PERSISTENCE_TYPE=relational-jdbc
2
3QUARKUS_DATASOURCE_USERNAME=<your-username>
4QUARKUS_DATASOURCE_PASSWORD=<your-password>
5QUARKUS_DATASOURCE_JDBC_URL=<jdbc-url-of-postgres>

Using properties file:

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

2. AWS Aurora PostgreSQL metastore using IAM AWS authentication🔗

 1polaris.persistence.type=relational-jdbc
 2quarkus.datasource.jdbc.url=jdbc:postgresql://polaris-cluster.cluster-xyz.us-east-1.rds.amazonaws.com:6160/polaris
 3quarkus.datasource.jdbc.additional-jdbc-properties.wrapperPlugins=iam
 4quarkus.datasource.username=dbusername
 5quarkus.datasource.db-kind=postgresql
 6quarkus.datasource.jdbc.additional-jdbc-properties.ssl=true
 7quarkus.datasource.jdbc.additional-jdbc-properties.sslmode=require
 8quarkus.datasource.credentials-provider=aws
 9
10quarkus.rds.credentials-provider.aws.use-quarkus-client=true
11quarkus.rds.credentials-provider.aws.username=dbusername
12quarkus.rds.credentials-provider.aws.hostname=polaris-cluster.cluster-xyz.us-east-1.rds.amazonaws.com
13quarkus.rds.credentials-provider.aws.port=6160

This is the basic configuration. For more details, please refer to the Quarkus plugin documentation.

The Relational JDBC metastore currently relies on a Quarkus-managed datasource and supports only PostgresSQL and H2 databases. At this time, official documentation is provided exclusively for usage with PostgreSQL. Please refer to the documentation here: Configure data sources in Quarkus.

Additionally, the retries can be configured via polaris.persistence.relational.jdbc.* properties; please refer to the Configuring Polaris section.

Bootstrapping Polaris🔗

Before using Polaris with the Relational JDBC backend, you must bootstrap the metastore to create the necessary schema and initial realm. This is done using the Admin Tool.

Using Docker:

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

Using the standalone JAR:

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

For more details on the bootstrap command and other administrative operations, see the Admin Tool documentation.