[JDBC] : Deprecate EclipseLink (#1515)

Author: singhpk234

helm/polaris/README.md

@@ -48,7 +48,7 @@ A Helm chart for Apache Polaris (incubating).
 
 ### Optional
 
-When using a custom `persistence.xml`, a Kubernetes Secret must be created for it. Below is a sample command:
+When using EclipseLink backed metastore a custom `persistence.xml` is required, a Kubernetes Secret must be created for it. Below is a sample command:
 ```bash
 kubectl create secret generic polaris-secret -n polaris --from-file=persistence.xml
 ```
@@ -67,7 +67,7 @@ helm unittest helm/polaris
 The below instructions assume Kind and Helm are installed.
 
 Simply run the `run.sh` script from the Polaris repo root, making sure to specify the
-`--eclipse-link-deps` option:
+`--eclipse-link-deps` if using EclipseLink backed metastore, option:
 
 ```bash
 ./run.sh
@@ -186,8 +186,8 @@ kubectl delete namespace polaris
 
 ## Values
 
-| Key | Type | Default | Description |
-|-----|------|---------|-------------|
+ Key | Type | Default | Description |
+|-----|------|-----|-------------|
 | advancedConfig | object | `{}` | Advanced configuration. You can pass here any valid Polaris or Quarkus configuration property. Any property that is defined here takes precedence over all the other configuration values generated by this chart. Properties can be passed "flattened" or as nested YAML objects (see examples below). Note: values should be strings; avoid using numbers, booleans, or other types. |
 | affinity | object | `{}` | Affinity and anti-affinity for polaris pods. See https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#affinity-and-anti-affinity. |
 | authentication | object | `{"authenticator":{"type":"default"},"tokenBroker":{"maxTokenGeneration":"PT1H","secret":{"name":null,"privateKey":"private.pem","publicKey":"public.pem","secretKey":"secret"},"type":"rsa-key-pair"},"tokenService":{"type":"default"}}` | Polaris authentication configuration. |
@@ -285,7 +285,7 @@ kubectl delete namespace polaris
 | persistence.eclipseLink.secret | object | `{"key":"persistence.xml","name":null}` | The secret name to pull persistence.xml from. |
 | persistence.eclipseLink.secret.key | string | `"persistence.xml"` | The key in the secret to pull persistence.xml from. |
 | persistence.eclipseLink.secret.name | string | `nil` | The name of the secret to pull persistence.xml from. If not provided, the default built-in persistence.xml will be used. This is probably not what you want. |
-| persistence.type | string | `"eclipse-link"` | The type of persistence to use. Two built-in types are supported: in-memory and eclipse-link. |
+| persistence.type | string | `"relational-jdbc"` | Three built-in types are available: "relational-jdbc", "in-memory", "eclipse-link". The in-memory type is not recommended for production use. The eclipse-link type is deprecated and will be unsupported in a future release. |
 | podAnnotations | object | `{}` | Annotations to apply to polaris pods. |
 | podLabels | object | `{}` | Additional Labels to apply to polaris pods. |
 | podSecurityContext | object | `{"fsGroup":10001,"seccompProfile":{"type":"RuntimeDefault"}}` | Security context for the polaris pod. See https://kubernetes.io/docs/tasks/configure-pod-container/security-context/. |
@@ -343,4 +343,4 @@ kubectl delete namespace polaris
 | tracing.attributes | object | `{}` | Resource attributes to identify the polaris service among other tracing sources. See https://opentelemetry.io/docs/reference/specification/resource/semantic_conventions/#service. If left empty, traces will be attached to a service named "Apache Polaris"; to change this, provide a service.name attribute here. |
 | tracing.enabled | bool | `false` | Specifies whether tracing for the polaris server should be enabled. |
 | tracing.endpoint | string | `"http://otlp-collector:4317"` | The collector endpoint URL to connect to (required). The endpoint URL must have either the http:// or the https:// scheme. The collector must talk the OpenTelemetry protocol (OTLP) and the port must be its gRPC port (by default 4317). See https://quarkus.io/guides/opentelemetry for more information. |
-| tracing.sample | string | `"1.0d"` | Which requests should be sampled. Valid values are: "all", "none", or a ratio between 0.0 and "1.0d" (inclusive). E.g. "0.5d" means that 50% of the requests will be sampled. Note: avoid entering numbers here, always prefer a string representation of the ratio. |
+| tracing.sample | string | `"1.0d"` | Which requests should be sampled. Valid values are: "all", "none", or a ratio between 0.0 and "1.0d" (inclusive). E.g. "0.5d" means that 50% of the requests will be sampled. Note: avoid entering numbers here, always prefer a string representation of the ratio. |

quarkus/admin/src/main/resources/application.properties

@@ -35,7 +35,7 @@ quarkus.container-image.additional-tags=latest
 # ---- Runtime Configuration ----
 # Below are default values for properties that can be changed in runtime.
 
-polaris.persistence.type=eclipse-link
+polaris.persistence.type=relational-jdbc
 
 quarkus.arc.ignored-split-packages=\
   org.apache.polaris.admintool.config,\

quarkus/admin/src/testFixtures/java/org/apache/polaris/admintool/PostgresTestResourceLifecycleManager.java

@@ -63,7 +63,10 @@ public Map<String, String> start() {
     context.containerNetworkId().ifPresent(postgres::withNetworkMode);
     postgres.start();
     return Map.of(
-        "polaris.persistence.eclipselink.configuration-file", createPersistenceXml().toString());
+        "polaris.persistence.type",
+        "eclipse-link",
+        "polaris.persistence.eclipselink.configuration-file",
+        createPersistenceXml().toString());
   }
 
   @Override

site/content/in-dev/unreleased/admin-tool.md

@@ -74,18 +74,13 @@ The Polaris Admin Tool must be executed with the same configuration as the Polar
 configuration can be done via environment variables or system properties.
 
 At a minimum, it is necessary to configure the Polaris Admin Tool to connect to the same database
-used by the Polaris server. This can be done by setting the following system properties:
-
-```shell
-java \
-    -Dpolaris.persistence.eclipselink.configuration-file=/path/to/persistence.xml \
-    -Dpolaris.persistence.eclipselink.persistence-unit=polaris \
-    -jar quarkus/admin/build/polaris-quarkus-admin-*-runner.jar
-```
+used by the Polaris server.
 
 See the [metastore documentation]({{% ref "metastores" %}}) for more information on configuring the
 database connection.
 
+Note: Polaris will always create schema 'polaris_schema' during bootstrap under the configured database.
+
 ## Bootstrapping Realms and Principal Credentials
 
 The `bootstrap` command is used to bootstrap realms and create the necessary principal credentials

site/content/in-dev/unreleased/configuring-polaris-for-production.md

@@ -135,34 +135,32 @@ default, Polaris uses an in-memory metastore.
 > The default in-memory metastore is not suitable for production use, as it will lose all data
 > when the server is restarted; it is also unusable when multiple Polaris replicas are used.
 
-To use a durable metastore, you need to switch to the EclipseLink metastore, and provide your own
-`persistence.xml` file. This file contains details of the database used for metastore management and
-the connection settings. For more information, refer to the [metastore documentation]({{% ref
-"metastores" %}}).
+To enable a durable metastore, configure your system to use the Relational JDBC-backed metastore.
+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](https://quarkus.io/guides/config-reference#env-file).
 
-Then, configure Polaris to use your metastore by setting the following properties:
+Configure the metastore by setting the following ENV variables:
 
-```properties
-polaris.persistence.type=eclipse-link
-polaris.persistence.eclipselink.configuration-file=/path/to/persistence.xml
-polaris.persistence.eclipselink.persistence-unit=polaris
 ```
+POLARIS_PERSISTENCE_TYPE=relational-jdbc
 
-Where:
+QUARKUS_DATASOURCE_DB_KIND=postgresql
+QUARKUS_DATASOURCE_USERNAME=<your-username>
+QUARKUS_DATASOURCE_PASSWORD=<your-password>
+QUARKUS_DATASOURCE_JDBC_URL=<jdbc-url-of-postgres>
+```
 
-- `polaris.persistence.type` indicates that we are using the EclipseLink metastore.
-- `polaris.persistence.eclipselink.configuration-file` is the path to the `persistence.xml` file.
-- `polaris.persistence.eclipselink.persistence-unit` is the name of the persistence unit to use (in
-  case the configuration file has many persistence units).
 
-Typically, in Kubernetes, you would define the `persistence.xml` file as a `ConfigMap` and set the
-`polaris.persistence.eclipselink.configuration-file` property to the path of the mounted file in
-the container.
+The relational JDBC metastore is a Quarkus-managed datasource and only supports Postgres and H2 as of now.
+Please refer to the documentation here:
+[Configure data sources in Quarkus](https://quarkus.io/guides/datasource)
 
 > [!IMPORTANT]
 > Be sure to secure your metastore backend since it will be storing sensitive data and catalog
 > metadata.
 
+Note: Polaris will always create schema 'polaris_schema' during bootstrap under the configured database.
+
 ### Bootstrapping
 
 Before using Polaris, you must **bootstrap** the metastore. This is a manual operation that must be

site/content/in-dev/unreleased/metastores.md

@@ -32,6 +32,27 @@ In order to add other JDBC drivers, you have to build Polaris using the `eclipse
 
 ## Polaris Server Configuration
 
+### 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](https://quarkus.io/guides/config-reference#env-file).
+
+
+```
+POLARIS_PERSISTENCE_TYPE=relational-jdbc
+
+QUARKUS_DATASOURCE_DB_KIND=postgresql
+QUARKUS_DATASOURCE_USERNAME=<your-username>
+QUARKUS_DATASOURCE_PASSWORD=<your-password>
+QUARKUS_DATASOURCE_JDBC_URL=<jdbc-url-of-postgres>
+```
+
+The Relational JDBC metastore currently relies on a Quarkus-managed datasource and supports only PostgreSQL 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](https://quarkus.io/guides/datasource)
+
+### EclipseLink
+> [!IMPORTANT] Eclipse link is deprecated, its recommend to use Relational JDBC as persistence instead.
+
 Configure the `polaris.persistence` section in your Polaris configuration file
 (`application.properties`) as follows:
 
@@ -58,7 +79,7 @@ Polaris creates and connects to a separate database for each realm. Specifically
 
 A single `persistence.xml` can describe multiple [persistence units](https://eclipse.dev/eclipselink/documentation/4.0/concepts/concepts.html#APPDEV001). 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.
 
-### Using H2
+#### Using H2
 
 > [!IMPORTANT] H2 is an in-memory database and is not suitable for production!
 
@@ -101,7 +122,7 @@ java -Dpolaris.persistence.type=eclipse-link \
      -jar quarkus/server/build/quarkus-app/quarkus-run.jar
 ```
 
-### Using Postgres
+#### Using Postgres
 
 PostgreSQL is included by default in the Polaris server distribution.
 
@@ -130,3 +151,4 @@ The following shows a sample configuration for integrating Polaris with Postgres
   </properties>
 </persistence-unit>
 ```
+