This page explains how to configure and use Polaris metastores with either the recommended Relational JDBC or the deprecated EclipseLink persistence backends.
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:
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>
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
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. This limitation is similar to that of EclipseLink, primarily due to underlying schema differences. 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 ref [configuration]({{% ref “configuration” %}})
{{< alert important >}} EclipseLink persistence will be completely removed from Polaris in 1.3.0 or in 2.0.0 (whichever happens earlier). {{< /alert >}}
Polaris includes EclipseLink plugin by default with PostgresSQL driver.
Configure the polaris.persistence section in your Polaris configuration file (application.properties) as follows:
polaris.persistence.type=eclipse-link polaris.persistence.eclipselink.configuration-file=/path/to/persistence.xml polaris.persistence.eclipselink.persistence-unit=polaris
Alternatively, configuration can also be done with environment variables or system properties. Refer to the [Quarkus Configuration Reference] for more information.
The configuration-file option must point to an [EclipseLink configuration file]. This file, named persistence.xml, is used to set up the database connection properties, which can differ depending on the type of database and its configuration.
{{< alert note >}} You have to locate the persistence.xml at least two folders down to the root folder, e.g. /deployments/config/persistence.xml is OK, whereas /deployments/persistence.xml will cause an infinity loop. {{< /alert >}} [Quarkus Configuration Reference]: https://quarkus.io/guides/config-reference [EclipseLink configuration file]: https://eclipse.dev/eclipselink/documentation/4.0/solutions/solutions.html#TESTINGJPA002
Polaris creates and connects to a separate database for each realm. Specifically, the {realm} placeholder in jakarta.persistence.jdbc.url is substituted with the actual realm name, allowing the Polaris server to connect to different databases based on the realm.
{{< alert note >}} Some database systems such as Postgres don't create databases automatically. Database admins need to create them manually before running Polaris server. {{< /alert >}}
A single persistence.xml can describe multiple persistence units. For example, with both a polaris-dev and polaris persistence unit defined, you could use a single persistence.xml to easily switch between development and production databases. Use the persistence-unit option in the Polaris server configuration to easily switch between persistence units.
{{< alert important >}} H2 is an in-memory database and is not suitable for production! {{< /alert >}}
The default persistence.xml in Polaris is already configured for H2, but you can easily customize your H2 configuration using the persistence unit template below:
<persistence-unit name="polaris" transaction-type="RESOURCE_LOCAL"> <provider>org.eclipse.persistence.jpa.PersistenceProvider</provider> <class>org.apache.polaris.extension.persistence.impl.eclipselink.models.ModelEntity</class> <class>org.apache.polaris.extension.persistence.impl.eclipselink.models.ModelEntityActive</class> <class>org.apache.polaris.extension.persistence.impl.eclipselink.models.ModelEntityChangeTracking</class> <class>org.apache.polaris.extension.persistence.impl.eclipselink.models.ModelEntityDropped</class> <class>org.apache.polaris.extension.persistence.impl.eclipselink.models.ModelGrantRecord</class> <class>org.apache.polaris.extension.persistence.impl.eclipselink.models.ModelPrincipalSecrets</class> <class>org.apache.polaris.extension.persistence.impl.eclipselink.models.ModelSequenceId</class> <shared-cache-mode>NONE</shared-cache-mode> <properties> <property name="jakarta.persistence.jdbc.url" value="jdbc:h2:file:tmp/polaris_test/filedb_{realm}"/> <property name="jakarta.persistence.jdbc.user" value="sa"/> <property name="jakarta.persistence.jdbc.password" value=""/> <property name="jakarta.persistence.schema-generation.database.action" value="create"/> </properties> </persistence-unit>
To build Polaris with the necessary H2 dependency and start the Polaris service, run the following:
./gradlew \ :polaris-server:assemble \ :polaris-server:quarkusAppPartsBuild --rerun \ -PeclipseLinkDeps=com.h2database:h2:2.3.232 java -Dpolaris.persistence.type=eclipse-link \ -Dpolaris.persistence.eclipselink.configuration-file=/path/to/persistence.xml \ -Dpolaris.persistence.eclipselink.persistence-unit=polaris \ -jar runtime/server/build/quarkus-app/quarkus-run.jar
PostgreSQL is included by default in the Polaris server distribution.
The following shows a sample configuration for integrating Polaris with Postgres.
<persistence-unit name="polaris" transaction-type="RESOURCE_LOCAL"> <provider>org.eclipse.persistence.jpa.PersistenceProvider</provider> <class>org.apache.polaris.extension.persistence.impl.eclipselink.models.ModelEntity</class> <class>org.apache.polaris.extension.persistence.impl.eclipselink.models.ModelEntityActive</class> <class>org.apache.polaris.extension.persistence.impl.eclipselink.models.ModelEntityChangeTracking</class> <class>org.apache.polaris.extension.persistence.impl.eclipselink.models.ModelEntityDropped</class> <class>org.apache.polaris.extension.persistence.impl.eclipselink.models.ModelGrantRecord</class> <class>org.apache.polaris.extension.persistence.impl.eclipselink.models.ModelPrincipalSecrets</class> <class>org.apache.polaris.extension.persistence.impl.eclipselink.models.ModelSequenceId</class> <shared-cache-mode>NONE</shared-cache-mode> <properties> <property name="jakarta.persistence.jdbc.url" value="jdbc:postgresql://localhost:5432/{realm}"/> <property name="jakarta.persistence.jdbc.user" value="postgres"/> <property name="jakarta.persistence.jdbc.password" value="postgres"/> <property name="jakarta.persistence.schema-generation.database.action" value="create"/> <property name="eclipselink.persistence-context.flush-mode" value="auto"/> <property name="eclipselink.session.customizer" value="org.apache.polaris.extension.persistence.impl.eclipselink.PolarisEclipseLinkSessionCustomizer"/> <property name="eclipselink.transaction.join-existing" value="true"/> </properties> </persistence-unit>