Skip to content

docs: adapt metastores.md to Quarkus #831

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
flyrain merged 2 commits into from
Jan 23, 2025
Merged

docs: adapt metastores.md to Quarkus #831

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4b1fa04
docs: adapt metastores.md to Quarkus
adutra Jan 20, 2025
880a0ee
review
adutra Jan 23, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
74 changes: 49 additions & 25 deletions site/content/in-dev/unreleased/metastores.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Copy link
Contributor

@flyrain flyrain Jan 23, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It'd be nice to give an example of a single file with multiple units. But it isn't a blocker to me. We can improve on it later.


### 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>
Expand All @@ -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.

Expand All @@ -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
```
Loading