Skip to content

Commit 3ab0f21

Browse files
ting-lan-wangting-lan-wang
authored
Add pkl support (#227)
* Add ojdbc-provider-pkl module * Rebase the branch and update the README.md * Update pom.xml * Update github action using JDK 17 * Update github action using JDK 17 * Remove unused dependencies
1 parent 4679521 commit 3ab0f21

File tree

12 files changed

+2970
-3
lines changed

12 files changed

+2970
-3
lines changed

‎.github/workflows/run-tests.yaml‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -16,10 +16,11 @@ jobs:
1616
steps:
1717
- name: Checkout the repository
1818
uses: actions/checkout@v4
19-
- name: Set up JDK 11
20-
uses: actions/setup-java@v1
19+
- name: Set up JDK 17
20+
uses: actions/setup-java@v5
2121
with:
22-
java-version: 11
22+
distribution: 'oracle'
23+
java-version: '17'
2324
- name: Cache Maven packages
2425
uses: actions/cache@v4
2526
with:

‎README.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,8 @@ Each module of this project contains a set of providers.
3030
<dt><a href="ojdbc-provider-jackson-oson/README.md">Oracle JDBC Jackson OSON</a></dt>
3131
<dd>Provider for <a href="https://docs.oracle.com/en/database/oracle/oracle-database/23/adjsn/json-in-oracle-database.html#GUID-A8A58B49-13A5-4F42-8EA0-508951DAE0BB">OSON</a> through the JACKSON APIs.
3232
This provider can be used for seamless integration of applications that use the JACKSON APIs with the Oracle JSON type.</dd>
33+
<dt><a href="ojdbc-provider-pkl/README.md">Oracle JDBC Pkl Parser</a></dt>
34+
<dd>Parser for integration with Pkl that can be used by providers</dd>
3335
</dl>
3436
Visit any of the links above to learn about providers which are available for
3537
a particular platform.
@@ -144,6 +146,8 @@ this project:
144146

145147
[ojdbc-provider-jackson-oson](ojdbc-provider-jackson-oson/README.md#installation)
146148

149+
[ojdbc-provider-pkl](ojdbc-provider-pkl/README.md#installation)
150+
147151

148152
Each module listed above is distributed on the Maven Central Repository as a
149153
separate jar file. Coordinates can be found by visiting the links above.

‎ojdbc-provider-pkl/README.md‎

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
# Oracle JDBC Configuration Provider Parser for Pkl
2+
3+
This module provides a parser that integrates **Oracle JDBC** with **Pkl**, a modern configuration language.
4+
It implements the `OracleConfigurationParser` interface to parse and read `.pkl` files for database configuration.
5+
6+
With the Oracle JDBC Pkl Parser, developers can store JDBC configurations in `.pkl` files and load them dynamically through Oracle JDBC Driver Extensions.
7+
8+
> **Note:** This parser works only with providers that extend `OracleConfigurationParsableProvider`, such as `file`, `https`, `ociobject`, `awss3`, and others.
9+
>
10+
## Installation
11+
12+
All providers in this module are distributed as single jar on the Maven Central
13+
Repository. The jar is compiled for JDK 8, and is forward compatible with later
14+
JDK versions. The coordinates for the latest release are:
15+
16+
```xml
17+
<dependency>
18+
<groupId>com.oracle.database.jdbc</groupId>
19+
<artifactId>ojdbc-provider-pkl</artifactId>
20+
<version>1.0.6</version>
21+
</dependency>
22+
```
23+
24+
## Usage
25+
26+
To use the Oracle JDBC Pkl Parser:
27+
28+
1. Prepare a .pkl configuration file (see examples below).
29+
2. Add this artifact to your application's classpath.
30+
3. Reference the .pkl file in the JDBC URL.
31+
32+
The parser type is inferred from the file extension. In this case, it’s "pkl".
33+
If the file name doesn’t include an extension, you can specify the parser explicitly using the parser option.
34+
All other options (like key, label, etc.) follow the same format as other providers.
35+
36+
Example using the file configuration provider:
37+
38+
```java
39+
jdbc:oracle:thin:@config-file://{pkl-file-name}[?parser=pkl&key=prefix&label=value&option1=value1&option2=value2...]
40+
```
41+
42+
## Writing .pkl Configuration
43+
44+
There are two approaches to filling out a template: **amends** and **import**.
45+
46+
### 1. Using `amends`
47+
48+
#### myJdbcConfig.pkl
49+
50+
```yaml
51+
amends "https://raw.githubusercontent.com/oracle/ojdbc-extensions/ojdbc-provider-pkl/src/main/resources/JdbcConfig.pkl"
52+
53+
connect_descriptor = "dbhost:1521/orclpdb1"
54+
user = "scott"
55+
56+
password {
57+
type = "ocivault"
58+
value = "ocid1.vaultsecret..."
59+
authentication {
60+
["method"] = "OCI_DEFAULT"
61+
}
62+
}
63+
64+
jdbc {
65+
autoCommit = false
66+
`oracle.jdbc.loginTimeout` = 60.s
67+
}
68+
```
69+
70+
#### URL (using file provider):
71+
72+
```java
73+
jdbc:oracle:thin:@config-file://myJdbcConfig.pkl
74+
```
75+
76+
### 2. Using `import`
77+
78+
#### myJdbcConfig.pkl
79+
80+
```yaml
81+
import "https://raw.githubusercontent.com/oracle/ojdbc-extensions/ojdbc-provider-pkl/src/main/resources/JdbcConfig.pkl"
82+
83+
config1 = (JdbcConfig) {
84+
connect_descriptor = "dbhost:1521/orclpdb1"
85+
86+
user = "scott"
87+
88+
password {
89+
type = "ocivault"
90+
value = "ocid1.vaultsecret..."
91+
authentication {
92+
["method"] = "OCI_DEFAULT"
93+
}
94+
}
95+
96+
jdbc {
97+
autoCommit = false
98+
`oracle.jdbc.loginTimeout` = 60.s
99+
}
100+
}
101+
```
102+
103+
#### URL (using file provider):
104+
105+
```java
106+
jdbc:oracle:thin:@config-file://myJdbcConfig.pkl?key=config1
107+
```

‎ojdbc-provider-pkl/pom.xml‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
2+
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
3+
<modelVersion>4.0.0</modelVersion>
4+
5+
<name>Oracle JDBC Providers Pkl Module</name>
6+
7+
<artifactId>ojdbc-provider-pkl</artifactId>
8+
<packaging>jar</packaging>
9+
10+
<parent>
11+
<groupId>com.oracle.database.jdbc</groupId>
12+
<artifactId>ojdbc-extensions</artifactId>
13+
<version>1.0.6</version>
14+
</parent>
15+
16+
<properties>
17+
<pkl.version>0.30.0</pkl.version>
18+
<java.version>17</java.version>
19+
</properties>
20+
21+
<dependencies>
22+
<dependency>
23+
<groupId>com.oracle.database.jdbc</groupId>
24+
<artifactId>ojdbc8</artifactId>
25+
</dependency>
26+
<dependency>
27+
<groupId>org.pkl-lang</groupId>
28+
<artifactId>pkl-config-java</artifactId>
29+
<version>${pkl.version}</version>
30+
</dependency>
31+
<dependency>
32+
<groupId>org.junit.jupiter</groupId>
33+
<artifactId>junit-jupiter-api</artifactId>
34+
</dependency>
35+
<dependency>
36+
<groupId>org.junit.jupiter</groupId>
37+
<artifactId>junit-jupiter-engine</artifactId>
38+
</dependency>
39+
<!-- TEST DEPENDENCIES -->
40+
<dependency>
41+
<groupId>com.oracle.database.jdbc</groupId>
42+
<artifactId>ojdbc-provider-common</artifactId>
43+
<classifier>tests</classifier>
44+
<type>test-jar</type>
45+
</dependency>
46+
</dependencies>
47+
48+
<build>
49+
<plugins>
50+
<plugin>
51+
<artifactId>maven-compiler-plugin</artifactId>
52+
<version>3.11.0</version>
53+
<configuration>
54+
<release>${java.version}</release>
55+
</configuration>
56+
</plugin>
57+
<plugin>
58+
<groupId>org.apache.maven.plugins</groupId>
59+
<artifactId>maven-jar-plugin</artifactId>
60+
<version>3.3.0</version>
61+
<executions>
62+
<execution>
63+
<goals>
64+
<!--
65+
The test classes of this module are used by test classes of
66+
the sibling modules (OCI and Azure).
67+
Maven's jar plugin is configured to generate a test-jar. The
68+
sibling modules then declare a dependency on it.
69+
-->
70+
<goal>test-jar</goal>
71+
</goals>
72+
</execution>
73+
</executions>
74+
</plugin>
75+
</plugins>
76+
<resources>
77+
<resource>
78+
<directory>src/main/resources</directory>
79+
<includes>
80+
<include>**/*.pkl</include>
81+
<include>META-INF/services/oracle.jdbc.spi.*</include>
82+
</includes>
83+
</resource>
84+
</resources>
85+
</build>
86+
87+
</project>

0 commit comments

Comments
 (0)