flyrain commented on code in PR #831: URL: https://github.com/apache/polaris/pull/831#discussion_r1926261557
########## 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 distributions currently do not ship with any JDBC driver included. To build Polaris with +EclipseLink, you must specify the JDBC driver when building Polaris from sources. This is done 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. Review Comment: 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. ########## 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 distributions currently do not ship with any JDBC driver included. To build Polaris with +EclipseLink, you must specify the JDBC driver when building Polaris from sources. This is done using +Gradle's project property: `-PeclipseLinkDeps=<jdbc-driver-artifact1>,<jdbc-driver-artifact2>,...`. Review Comment: I think Polaris may never ship with JDBC drivers, due to the license issues. And we could change the doc in case of any change. ```suggestion 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>,...`. ``` -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
