Skip to content

Commit f374ab4

Browse files
aihuaxuaihuaxu
authored
Add the doc on how to configure Postgres as the backend database (apache#296)
1 parent 7373234 commit f374ab4

File tree

4 files changed

+104
-4
lines changed

4 files changed

+104
-4
lines changed

‎docs/configuring-polaris-for-production.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@
2020

2121
# Configuring Apache Polaris (Incubating) for Production
2222

23-
The default `polaris-server.yml` configuration is intended for develoment and testing. When deploying Polaris in production, there are several best practices to keep in mind.
23+
The default `polaris-server.yml` configuration is intended for development and testing. When deploying Polaris in production, there are several best practices to keep in mind.
2424

2525
## Security
2626

@@ -56,7 +56,7 @@ Be sure to secure your metastore backend since it will be storing credentials an
5656

5757
### Configuring EclipseLink
5858

59-
To use [EclipseLink](https://eclipse.dev/eclipselink/) for metastore management, specify the configuration `metaStoreManager.conf-file` to point to an [EclipseLink `persistence.xml` file](https://eclipse.dev/eclipselink/documentation/2.5/solutions/testingjpa002.htm). This file, local to the Polaris service, will contain information on what database to use for metastore management and how to connect to it.
59+
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](./metastores.md) for details.
6060

6161
### Bootstrapping
6262

‎docs/metastores.md

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
<!--
2+
Licensed to the Apache Software Foundation (ASF) under one
3+
or more contributor license agreements. See the NOTICE file
4+
distributed with this work for additional information
5+
regarding copyright ownership. The ASF licenses this file
6+
to you under the Apache License, Version 2.0 (the
7+
"License"); you may not use this file except in compliance
8+
with the License. You may obtain a copy of the License at
9+
10+
http://www.apache.org/licenses/LICENSE-2.0
11+
12+
Unless required by applicable law or agreed to in writing,
13+
software distributed under the License is distributed on an
14+
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15+
KIND, either express or implied. See the License for the
16+
specific language governing permissions and limitations
17+
under the License.
18+
-->
19+
20+
This page documents the general configurations to connect to production database through [EclipseLink](https://eclipse.dev/eclipselink/).
21+
22+
## Polaris Server Configuration
23+
Configure the `metaStoreManager` section in server configuration `polaris-server.yml` as follows:
24+
```
25+
metaStoreManager:
26+
type: eclipse-link
27+
conf-file: META-INF/persistence.xml
28+
persistence-unit: polaris
29+
```
30+
`conf-file` points to the EclipseLink configuration file and `persistence-unit` tells which unit from the configuration file to use for database connection.
31+
32+
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.
33+
34+
`conf-file` by default points to the embedded resource file `META-INF/persistence.xml` in `polaris-eclipselink` module.
35+
To specify an external configuration file,
36+
1) Place `persistence.xml` into a jar file: `jar cvf /tmp/conf.jar persistence.xml`.
37+
2) Use `conf-file: /tmp/conf.jar!/persistence.xml`.
38+
39+
## EclipseLink Configuration - persistence.xml
40+
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.
41+
42+
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 connect to different databases based on the realm.
43+
44+
> Note: some database systems such as Postgres don't create databases automatically. Database admins need to create them manually before running Polaris server.
45+
```xml
46+
<persistence-unit name="polaris" transaction-type="RESOURCE_LOCAL">
47+
<provider>org.eclipse.persistence.jpa.PersistenceProvider</provider>
48+
<class>org.apache.polaris.core.persistence.models.ModelEntity</class>
49+
<class>org.apache.polaris.core.persistence.models.ModelEntityActive</class>
50+
<class>org.apache.polaris.core.persistence.models.ModelEntityChangeTracking</class>
51+
<class>org.apache.polaris.core.persistence.models.ModelEntityDropped</class>
52+
<class>org.apache.polaris.core.persistence.models.ModelGrantRecord</class>
53+
<class>org.apache.polaris.core.persistence.models.ModelPrincipalSecrets</class>
54+
<class>org.apache.polaris.core.persistence.models.ModelSequenceId</class>
55+
<shared-cache-mode>NONE</shared-cache-mode>
56+
<properties>
57+
<property name="jakarta.persistence.jdbc.url"
58+
value="jdbc:h2:file:tmp/polaris_test/filedb_{realm}"/>
59+
<property name="jakarta.persistence.jdbc.user" value="sa"/>
60+
<property name="jakarta.persistence.jdbc.password" value=""/>
61+
<property name="jakarta.persistence.schema-generation.database.action" value="create"/>
62+
</properties>
63+
</persistence-unit>
64+
```
65+
66+
Build with H2 dependency and run Polaris service:
67+
```bash
68+
polaris> ./gradlew --no-daemon --info -PeclipseLink=true -PeclipseLinkDeps=com.h2database:h2:2.3.232 clean shadowJar
69+
polaris> java -jar polaris-service/build/libs/polaris-service-*.jar server ./polaris-server.yml
70+
```
71+
72+
### Postgres
73+
74+
The following shows a sample configuration for Postgres database.
75+
76+
```xml
77+
<persistence-unit name="polaris" transaction-type="RESOURCE_LOCAL">
78+
<provider>org.eclipse.persistence.jpa.PersistenceProvider</provider>
79+
<class>org.apache.polaris.core.persistence.models.ModelEntity</class>
80+
<class>org.apache.polaris.core.persistence.models.ModelEntityActive</class>
81+
<class>org.apache.polaris.core.persistence.models.ModelEntityChangeTracking</class>
82+
<class>org.apache.polaris.core.persistence.models.ModelEntityDropped</class>
83+
<class>org.apache.polaris.core.persistence.models.ModelGrantRecord</class>
84+
<class>org.apache.polaris.core.persistence.models.ModelPrincipalSecrets</class>
85+
<class>org.apache.polaris.core.persistence.models.ModelSequenceId</class>
86+
<shared-cache-mode>NONE</shared-cache-mode>
87+
<properties>
88+
<property name="jakarta.persistence.jdbc.url"
89+
value="jdbc:postgresql://localhost:5432/{realm}"/>
90+
<property name="jakarta.persistence.jdbc.user" value="postgres"/>
91+
<property name="jakarta.persistence.jdbc.password" value="postgres"/>
92+
<property name="jakarta.persistence.schema-generation.database.action" value="create"/>
93+
<property name="eclipselink.persistence-context.flush-mode" value="auto"/>
94+
</properties>
95+
</persistence-unit>
96+
```
97+
Build with Postgres dependency and run Polaris service:
98+
```bash
99+
polaris> ./gradlew --no-daemon --info -PeclipseLink=true -PeclipseLinkDeps=org.postgresql:postgresql:42.7.4 clean shadowJar
100+
polaris> java -jar polaris-service/build/libs/polaris-service-*.jar server ./polaris-server.yml
101+
```

‎extension/persistence/eclipselink/src/main/java/org/apache/polaris/extension/persistence/impl/eclipselink/PolarisEclipseLinkMetaStoreSessionImpl.java

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -147,7 +147,7 @@ private EntityManagerFactory createEntityManagerFactory(
147147
// Currently eclipseLink can only support configuration as a resource inside a jar. To support
148148
// external configuration, persistence.xml needs be placed inside a jar and here is to add the
149149
// jar to the classpath.
150-
// Supported configuration file: META-INFO/persistence.xml, /tmp/conf.jar!/persistence.xml
150+
// Supported configuration file: META-INF/persistence.xml, /tmp/conf.jar!/persistence.xml
151151
int splitPosition = confFile.indexOf("!/");
152152
if (splitPosition != -1) {
153153
String jarPrefixPath = confFile.substring(0, splitPosition);

‎polaris-service/build.gradle.kts

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -111,7 +111,6 @@ dependencies {
111111
testRuntimeOnly("org.junit.platform:junit-platform-launcher")
112112

113113
testRuntimeOnly(project(":polaris-eclipselink"))
114-
testRuntimeOnly(libs.h2)
115114
}
116115

117116
if (project.properties.get("eclipseLink") == "true") {

0 commit comments

Comments
 (0)