Relational JDBC

The Relational JDBC metastore relies on a Quarkus-managed datasource. For more information, refer to the Quarkus datasource documentation and Quarkus configuration reference.

Configuration🔗

Check below two configuration examples:

1. Regular JDBC connection with username and password.
2. AWS Aurora PostgreSQL metastore using IAM AWS authentication.

The examples show the basic configuration, but many other options are available. For more details, please refer to the Quarkus configuration reference.

1. Relational JDBC metastore with username and password🔗

Using environment variables:

POLARIS_PERSISTENCE_TYPE=relational-jdbc

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

Using properties file:

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. AWS Aurora PostgreSQL metastore using IAM AWS authentication🔗

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

For more details about how to configure the AWS Aurora PostgreSQL metastore using IAM AWS authentication, please refer to the Quarkus Amazon RDS Client docs.

Additional configuration🔗

The following polaris.persistence.relational.jdbc.* properties tune retry behavior and database type detection:

# Maximum number of attempts for retryable operations (default: 1, i.e. no retries)
polaris.persistence.relational.jdbc.max-retries=3

# Maximum total time to spend on retries in milliseconds (default: 5000)
polaris.persistence.relational.jdbc.max-duration-in-ms=10000

# Initial delay between retries in milliseconds, doubled on each attempt (default: 100)
polaris.persistence.relational.jdbc.initial-delay-in-ms=200

# Explicitly set the database type instead of inferring it from JDBC metadata.
# Supported values: postgresql, cockroachdb, h2
polaris.persistence.relational.jdbc.database-type=postgresql

For the full list of available properties with their types and defaults, please refer to the Configuring Polaris section.

SQL Schema🔗

Schema Name🔗

By default, Polaris stores its tables in a schema named POLARIS_SCHEMA. The schema is selected entirely through the datasource configuration — the persistence code itself is agnostic of the schema name. Polaris ships the following default in application.properties:

quarkus.datasource.jdbc.additional-jdbc-properties.currentSchema=POLARIS_SCHEMA

This sets the PostgreSQL (and CockroachDB) driver’s currentSchema connection property on every connection. To use a different schema — for example, to run multiple Polaris deployments in the same database or to comply with a schema-naming policy — override this property:

quarkus.datasource.jdbc.additional-jdbc-properties.currentSchema=<your-schema-name>

Alternatively, set currentSchema directly in the JDBC URL; the URL takes precedence over the property. The name is passed to the driver unquoted, so the database applies its usual identifier case folding (for example, PostgreSQL folds it to lowercase).

Schema Structure🔗

Starting with Polaris 1.8.0, each Polaris binary ships a single schema.sql script for each supported database type.

For this release ([unreleased]), the corresponding SQL files are:

• PostgreSQL: schema.sql
• CockroachDB: schema.sql

The schema.sql file is versioned, and contains the SQL statements to create the Polaris schema and tables, as well as the initial data for the version table that tracks the schema version.

Polaris checks the version table on the first request to each realm, and fails fast with an actionable error message if the recorded version does not match what the binary expects.

Setting Up a Fresh Deployment🔗

Setting up a fresh deployment is a two-step procedure:

1. A database administrator creates the schema. Polaris does not issue CREATE SCHEMA, since that is a privileged operation best performed by a DBA. For example:

   CREATE SCHEMA polaris_schema;
   

   The database user that Polaris runs with needs USAGE (and, for bootstrap, CREATE) privileges on that schema only.

2. The Admin Tool bootstraps the realm. The bootstrap command creates the necessary SQL tables (using the schema.sql shipped with the binary) and the initial realm. The datasource must be configured with the same schema as the one created in step 1.

Using 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>" \
  --env="quarkus.datasource.jdbc.additional-jdbc-properties.currentSchema=POLARIS_SCHEMA" \
  apache/polaris-admin-tool:latest bootstrap -r <realm-name> -c <realm-name>,<client-id>,<client-secret>

Using the standalone 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> \
  "-Dquarkus.datasource.jdbc.additional-jdbc-properties.currentSchema=POLARIS_SCHEMA" \
  -jar polaris-admin-tool.jar bootstrap -r <realm-name> -c <realm-name>,<client-id>,<client-secret>

Replace POLARIS_SCHEMA with the schema name created in step 1 if you chose a different name. See the Schema name section for details. Alternatively, set currentSchema directly in the JDBC URL; the URL takes precedence over the property.

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

Upgrading Polaris🔗

Upgrading Polaris on an existing installation requires two steps, in this order:

1. Apply schema migrations for each schema version between your current version and the target version (see below). Schema migrations must be applied before starting the new Polaris binary. The first request to any realm whose recorded schema version does not match what the binary expects will fail fast with an actionable error message.

2. Bootstrap new realms if needed. Re-bootstrapping an existing installation is not required unless you want to add new realms. The bootstrap command is idempotent — already-bootstrapped realms are simply ignored — so it can be safely run again if needed.

Schema Upgrades🔗

Starting with schema version v6 (Polaris 1.9.0), schema changes are versioned in git, and you can use regular diff tools to compare the two files and see the differences between two release tags. Polaris release git tags are of the form: apache-polaris-<version>, e.g. apache-polaris-1.9.0.

For example, to get the diff between the PostgreSQL schema SQL file between Polaris 1.9.0 and 1.10.0, you can run the following command:

git diff apache-polaris-1.9.0 apache-polaris-1.10.0 -- persistence/relational-jdbc/src/main/resources/postgres/schema.sql

Refer to the Schema Version Reference table for links to the full schema SQL file for each database type.

Older schema versions had each their own versioned schema file. Refer to the Schema Version Reference table for links to the specific SQL file for each database type at the desired version.

Schema Version Reference🔗

The table below maps each released Polaris version to the JDBC schema version it ships with: