This is an automated email from the ASF dual-hosted git repository.
emaynard 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 bead4293 style-and-copy (#340)
bead4293 is described below
commit bead429338bd031a42207feca3e1cf9a606ad50f
Author: Eric Maynard <[email protected]>
AuthorDate: Wed Oct 2 16:11:30 2024 -0400
style-and-copy (#340)
---
site/content/in-dev/unreleased/_index.md | 2 +-
.../configuring-polaris-for-production.md | 4 +--
site/content/in-dev/unreleased/metastores.md | 29 +++++++++++++---------
3 files changed, 20 insertions(+), 15 deletions(-)
diff --git a/site/content/in-dev/unreleased/_index.md
b/site/content/in-dev/unreleased/_index.md
index 8f233f2e..19100e71 100644
--- a/site/content/in-dev/unreleased/_index.md
+++ b/site/content/in-dev/unreleased/_index.md
@@ -37,7 +37,7 @@ These pages refer to the current state of the main branch,
which is still under
Functionalities can be changed, removed or added without prior notice.
{{< /alert >}}
-Checkout the [Quick Start]({{% ref "quickstart" %}}) page.
+Check out the [Quick Start]({{% ref "quickstart" %}}) page to get started.
<!--
Testing the `releaseVersion` shortcode here: version is: {{< releaseVersion >}}
diff --git
a/site/content/in-dev/unreleased/configuring-polaris-for-production.md
b/site/content/in-dev/unreleased/configuring-polaris-for-production.md
index 819d5ee8..86ccd195 100644
--- a/site/content/in-dev/unreleased/configuring-polaris-for-production.md
+++ b/site/content/in-dev/unreleased/configuring-polaris-for-production.md
@@ -59,7 +59,7 @@ Be sure to secure your metastore backend since it will be
storing credentials an
### Configuring EclipseLink
-To use EclipseLink for metastore management, specify the configuration
`metaStoreManager.conf-file` to point to an EclipseLink `persistence.xml` file.
This file, local to the Polaris service, contains details of the database used
for metastore management and the connection settings. For more information,
refer to [metastore documentation]({{% ref "metastores" %}}) for details.
+To use EclipseLink for metastore management, specify the configuration
`metaStoreManager.conf-file` to point to an EclipseLink `persistence.xml` file.
This file, local to the Polaris service, contains details of the database used
for metastore management and the connection settings. For more information,
refer to the [metastore documentation]({{% ref "metastores" %}}).
### Bootstrapping
@@ -71,7 +71,7 @@ To bootstrap Polaris, run:
java -jar /path/to/jar/polaris-service-all.jar bootstrap polaris-server.yml
```
-Afterwards, Polaris can be launched normally:
+Afterward, Polaris can be launched normally:
```bash
java -jar /path/to/jar/polaris-service-all.jar server polaris-server.yml
diff --git a/site/content/in-dev/unreleased/metastores.md
b/site/content/in-dev/unreleased/metastores.md
index 72d97a38..220c1b72 100644
--- a/site/content/in-dev/unreleased/metastores.md
+++ b/site/content/in-dev/unreleased/metastores.md
@@ -23,29 +23,31 @@ type: docs
weight: 700
---
-This page documents the general configurations to connect to production
database through [EclipseLink](https://eclipse.dev/eclipselink/).
+This page documents important configurations for connecting to production
database through [EclipseLink](https://eclipse.dev/eclipselink/).
## Polaris Server Configuration
-Configure the `metaStoreManager` section in server configuration
`polaris-server.yml` as follows:
+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` points to the EclipseLink configuration file and
`persistence-unit` tells which unit from the configuration file to use for
database connection.
-E.g., `polaris-dev` and `polaris` persistence units are configured in
`persistence.xml` to connect to development database and production database
respectively. Updating `persistence-unit` from `polaris-dev` to `polaris`
switch from the development to the production.
+`conf-file` must point to an [EclipseLink configuration
file](https://eclipse.dev/eclipselink/documentation/2.5/solutions/testingjpa002.htm)
-`conf-file` by default points to the embedded resource file
`META-INF/persistence.xml` in `polaris-eclipselink` module.
-To specify an external configuration file,
-1) Place `persistence.xml` into a jar file: `jar cvf /tmp/conf.jar
persistence.xml`.
-2) Use `conf-file: /tmp/conf.jar!/persistence.xml`.
+By default, `conf-file` points to the embedded resource file
`META-INF/persistence.xml` in the `polaris-eclipselink` module.
+
+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`
## 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.
-Check out [default
persistence.xml](https://github.com/apache/polaris/blob/main/extension/persistence/eclipselink/src/main/resources/META-INF/persistence.xml)
for the complete sample and the following shows the database connection
properties against file-based H2 database. Polaris creates and connects to a
separate database for each realm. Specifically, `{realm}` placeholder in
`jakarta.persistence.jdbc.url` is substituted with the actual realm name,
allowing the Polaris server to connec [...]
+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.
+
+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.
```xml
@@ -69,7 +71,9 @@ Check out [default
persistence.xml](https://github.com/apache/polaris/blob/main/
</persistence-unit>
```
-Build with H2 dependency and run Polaris service:
+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 polaris-service/build/libs/polaris-service-*.jar server
./polaris-server.yml
@@ -77,7 +81,7 @@ polaris> java -jar
polaris-service/build/libs/polaris-service-*.jar server ./po
### Postgres
-The following shows a sample configuration for Postgres database.
+The following shows a sample configuration for integrating Polaris with
Postgres.
```xml
<persistence-unit name="polaris" transaction-type="RESOURCE_LOCAL">
@@ -100,7 +104,8 @@ The following shows a sample configuration for Postgres
database.
</properties>
</persistence-unit>
```
-Build with Postgres dependency and run Polaris service:
+
+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 polaris-service/build/libs/polaris-service-*.jar server
./polaris-server.yml
