This is an automated email from the ASF dual-hosted git repository.
yufei pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/polaris.git
The following commit(s) were added to refs/heads/main by this push:
new 353269aa Docs: adapt metastores.md to Quarkus (#831)
353269aa is described below
commit 353269aa7162f4043ec3d9f66b80e648c552a197
Author: Alexandre Dutra <[email protected]>
AuthorDate: Thu Jan 23 17:52:20 2025 +0100
Docs: adapt metastores.md to Quarkus (#831)
---
site/content/in-dev/unreleased/metastores.md | 74 ++++++++++++++++++----------
1 file changed, 49 insertions(+), 25 deletions(-)
diff --git a/site/content/in-dev/unreleased/metastores.md
b/site/content/in-dev/unreleased/metastores.md
index 8b287ffb..eb61f371 100644
--- a/site/content/in-dev/unreleased/metastores.md
+++ b/site/content/in-dev/unreleased/metastores.md
@@ -23,33 +23,51 @@ type: docs
weight: 700
---
-This page documents important configurations for connecting to production
database through [EclipseLink](https://eclipse.dev/eclipselink/).
+This page documents important configurations for connecting to a production
database through [EclipseLink](https://eclipse.dev/eclipselink/).
+
+## Building Polaris with EclipseLink
+
+Polaris doesn't ship with any JDBC driver. You must specify them when building
Polaris with
+EclipseLink by using Gradle's project property:
+`-PeclipseLinkDeps=<jdbc-driver-artifact1>,<jdbc-driver-artifact2>,...`. See
below examples for H2
+and Postgres.
## Polaris Server Configuration
-Configure the `metaStoreManager` section in the Polaris configuration
(`polaris-server.yml` by default) as follows:
-```
-metaStoreManager:
- type: eclipse-link
- conf-file: META-INF/persistence.xml
- persistence-unit: polaris
-```
-`conf-file` must point to an [EclipseLink configuration
file](https://eclipse.dev/eclipselink/documentation/2.5/solutions/testingjpa002.htm)
+Configure the `polaris.persistence` section in your Polaris configuration file
+(`application.properties`) as follows:
-By default, `conf-file` points to the embedded resource file
`META-INF/persistence.xml` in the `polaris-eclipselink` module.
+```
+polaris.persistence.type=eclipse-link
+polaris.persistence.eclipselink.configuration-file=/path/to/persistence.xml
+polaris.persistence.eclipselink.persistence-unit=polaris
+```
-In order to specify a configuration file outside the classpath, follow these
steps.
-1) Place `persistence.xml` into a jar file: `jar cvf /tmp/conf.jar
persistence.xml`
-2) Use `conf-file: /tmp/conf.jar!/persistence.xml`
+Alternatively, configuration can also be done with environment variables or
system properties. Refer
+to the [Quarkus Configuration Reference] for more information.
-## EclipseLink Configuration - persistence.xml
-The configuration file `persistence.xml` is used to set up the database
connection properties, which can differ depending on the type of database and
its configuration.
+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.
-Check out the default
[persistence.xml](https://github.com/apache/polaris/blob/main/extension/persistence/eclipselink/src/main/resources/META-INF/persistence.xml)
for a complete sample for connecting to the file-based H2 database.
+[Quarkus Configuration Reference]: https://quarkus.io/guides/config-reference
+[EclipseLink configuration file]:
https://eclipse.dev/eclipselink/documentation/2.5/solutions/testingjpa002.htm
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.
> Note: some database systems such as Postgres don't create databases
> automatically. Database admins need to create them manually before running
> Polaris server.
+
+A single `persistence.xml` can describe multiple [persistence
units](https://eclipse.dev/eclipselink/documentation/2.6/concepts/app_dev001.htm).
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
+
+> [!IMPORTANT] H2 is an in-memory database and is not suitable for production!
+
+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.xml]:
https://github.com/apache/polaris/blob/main/extension/persistence/eclipselink/src/main/resources/META-INF/persistence.xml
+
```xml
<persistence-unit name="polaris" transaction-type="RESOURCE_LOCAL">
<provider>org.eclipse.persistence.jpa.PersistenceProvider</provider>
@@ -71,15 +89,17 @@ Polaris creates and connects to a separate database for
each realm. Specifically
</persistence-unit>
```
-A single `persistence.xml` can describe multiple [persistence
units](https://eclipse.dev/eclipselink/documentation/2.6/concepts/app_dev001.htm).
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 `persistence-unit` in the Polaris server
configuration to easily switch between persistence units.
-
To build Polaris with the necessary H2 dependency and start the Polaris
service, run the following:
-```bash
-polaris> ./gradlew --no-daemon --info -PeclipseLink=true
-PeclipseLinkDeps=com.h2database:h2:2.3.232 clean shadowJar
-polaris> java -jar quarkus/service/build/quarkus-app/quarkus-run.jar
+
+```shell
+./gradlew clean :polaris-quarkus-server:assemble
-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 quarkus/server/build/quarkus-app/quarkus-run.jar
```
-### Postgres
+### Using Postgres
The following shows a sample configuration for integrating Polaris with
Postgres.
@@ -106,7 +126,11 @@ The following shows a sample configuration for integrating
Polaris with Postgres
```
To build Polaris with the necessary Postgres dependency and start the Polaris
service, run the following:
-```bash
-polaris> ./gradlew --no-daemon --info -PeclipseLink=true
-PeclipseLinkDeps=org.postgresql:postgresql:42.7.4 clean shadowJar
-polaris> java -jar quarkus/service/build/quarkus-app/quarkus-run.jar
+
+```shell
+./gradlew clean :polaris-quarkus-server:assemble
-PeclipseLinkDeps=org.postgresql:postgresql:42.7.4
+java -Dpolaris.persistence.type=eclipse-link \
+
-Dpolaris.persistence.eclipselink.configuration-file=/path/to/persistence.xml \
+ -Dpolaris.persistence.eclipselink.persistence-unit=polaris \
+ -jar quarkus/server/build/quarkus-app/quarkus-run.jar
```
\ No newline at end of file
