Add JDBC database provider for JVM
This commit is contained in:
sergeych committed
1 parent
ee392daa13
commit
64273ac60a
22 files changed
+1913
-459
No files matched your search
+151
-1
@@ -1,6 +1,6 @@
|
||||
### lyng.io.db — SQL database access for Lyng scripts
|
||||
|
||||
This module provides the portable SQL database contract for Lyng. The first shipped provider is SQLite via `lyng.io.db.sqlite`.
|
||||
This module provides the portable SQL database contract for Lyng. The current shipped providers are SQLite via `lyng.io.db.sqlite` and a JVM-only JDBC bridge via `lyng.io.db.jdbc`.
|
||||
|
||||
> **Note:** `lyngio` is a separate library module. It must be explicitly added as a dependency to your host application and initialized in your Lyng scopes.
|
||||
|
||||
@@ -30,6 +30,28 @@ suspend fun bootstrapDb() {
|
||||
|
||||
`createSqliteModule(...)` also registers the `sqlite:` scheme for generic `openDatabase(...)`.
|
||||
|
||||
For JVM JDBC-backed access, install the JDBC provider as well:
|
||||
|
||||
```kotlin
|
||||
import net.sergeych.lyng.EvalSession
|
||||
import net.sergeych.lyng.Scope
|
||||
import net.sergeych.lyng.io.db.createDbModule
|
||||
import net.sergeych.lyng.io.db.jdbc.createJdbcModule
|
||||
|
||||
suspend fun bootstrapJdbc() {
|
||||
val session = EvalSession()
|
||||
val scope: Scope = session.getScope()
|
||||
createDbModule(scope)
|
||||
createJdbcModule(scope)
|
||||
session.eval("""
|
||||
import lyng.io.db
|
||||
import lyng.io.db.jdbc
|
||||
""".trimIndent())
|
||||
}
|
||||
```
|
||||
|
||||
`createJdbcModule(...)` registers `jdbc:`, `h2:`, `postgres:`, and `postgresql:` for `openDatabase(...)`.
|
||||
|
||||
---
|
||||
|
||||
#### Using from Lyng scripts
|
||||
@@ -66,6 +88,63 @@ val db = openDatabase(
|
||||
)
|
||||
```
|
||||
|
||||
JVM JDBC open with H2:
|
||||
|
||||
```lyng
|
||||
import lyng.io.db.jdbc
|
||||
|
||||
val db = openH2("mem:demo;DB_CLOSE_DELAY=-1")
|
||||
|
||||
val names = db.transaction { tx ->
|
||||
tx.execute("create table person(id bigint auto_increment primary key, name varchar(120) not null)")
|
||||
tx.execute("insert into person(name) values(?)", "Ada")
|
||||
tx.execute("insert into person(name) values(?)", "Linus")
|
||||
tx.select("select name from person order by id").toList()
|
||||
}
|
||||
|
||||
assertEquals("Ada", names[0]["name"])
|
||||
assertEquals("Linus", names[1]["name"])
|
||||
```
|
||||
|
||||
Generic JDBC open through `openDatabase(...)`:
|
||||
|
||||
```lyng
|
||||
import lyng.io.db
|
||||
import lyng.io.db.jdbc
|
||||
|
||||
val db = openDatabase(
|
||||
"jdbc:h2:mem:demo2;DB_CLOSE_DELAY=-1",
|
||||
Map()
|
||||
)
|
||||
|
||||
val answer = db.transaction { tx ->
|
||||
tx.select("select 42 as answer").toList()[0]["answer"]
|
||||
}
|
||||
|
||||
assertEquals(42, answer)
|
||||
```
|
||||
|
||||
PostgreSQL typed open:
|
||||
|
||||
```lyng
|
||||
import lyng.io.db.jdbc
|
||||
|
||||
val db = openPostgres(
|
||||
"jdbc:postgresql://127.0.0.1/appdb",
|
||||
"appuser",
|
||||
"secret"
|
||||
)
|
||||
|
||||
val titles = db.transaction { tx ->
|
||||
tx.execute("create table if not exists task(id bigserial primary key, title text not null)")
|
||||
tx.execute("insert into task(title) values(?)", "Ship JDBC provider")
|
||||
tx.execute("insert into task(title) values(?)", "Test PostgreSQL path")
|
||||
tx.select("select title from task order by id").toList()
|
||||
}
|
||||
|
||||
assertEquals("Ship JDBC provider", titles[0]["title"])
|
||||
```
|
||||
|
||||
Nested transactions use real savepoint semantics:
|
||||
|
||||
```lyng
|
||||
@@ -217,6 +296,76 @@ Open-time validation failures:
|
||||
- malformed URL or bad option shape -> `IllegalArgumentException`
|
||||
- runtime open failure -> `DatabaseException`
|
||||
|
||||
#### JDBC provider
|
||||
|
||||
`lyng.io.db.jdbc` is currently implemented on the JVM target only. The `lyngio-jvm` artifact bundles and explicitly loads these JDBC drivers:
|
||||
|
||||
- SQLite
|
||||
- H2
|
||||
- PostgreSQL
|
||||
|
||||
Typed helpers:
|
||||
|
||||
```lyng
|
||||
openJdbc(
|
||||
connectionUrl: String,
|
||||
user: String? = null,
|
||||
password: String? = null,
|
||||
driverClass: String? = null,
|
||||
properties: Map<String, Object?>? = null
|
||||
): Database
|
||||
|
||||
openH2(
|
||||
connectionUrl: String,
|
||||
user: String? = null,
|
||||
password: String? = null,
|
||||
properties: Map<String, Object?>? = null
|
||||
): Database
|
||||
|
||||
openPostgres(
|
||||
connectionUrl: String,
|
||||
user: String? = null,
|
||||
password: String? = null,
|
||||
properties: Map<String, Object?>? = null
|
||||
): Database
|
||||
```
|
||||
|
||||
Accepted generic URL forms:
|
||||
|
||||
- `jdbc:h2:mem:test;DB_CLOSE_DELAY=-1`
|
||||
- `h2:mem:test;DB_CLOSE_DELAY=-1`
|
||||
- `jdbc:postgresql://localhost/app`
|
||||
- `postgres://localhost/app`
|
||||
- `postgresql://localhost/app`
|
||||
|
||||
Supported `openDatabase(..., extraParams)` keys for JDBC:
|
||||
|
||||
- `driverClass: String`
|
||||
- `user: String`
|
||||
- `password: String`
|
||||
- `properties: Map<String, Object?>`
|
||||
|
||||
Behavior notes for the JDBC bridge:
|
||||
|
||||
- the portable `Database` / `SqlTransaction` API stays the same as for SQLite
|
||||
- nested transactions use JDBC savepoints
|
||||
- JDBC connection properties are built from `user`, `password`, and `properties`
|
||||
- `properties` values are stringified before being passed to JDBC
|
||||
- statements with row-returning clauses still must use `select(...)`, not `execute(...)`
|
||||
|
||||
Platform support for this provider:
|
||||
|
||||
- `lyng.io.db.jdbc` — JVM only
|
||||
- `openH2(...)` — works out of the box with `lyngio-jvm`
|
||||
- `openPostgres(...)` — driver included, but an actual PostgreSQL server is still required
|
||||
|
||||
PostgreSQL-specific notes:
|
||||
|
||||
- `openPostgres(...)` accepts either a full JDBC URL or shorthand forms such as `//localhost/app`
|
||||
- local peer/trust setups may use an empty password string
|
||||
- generated keys work with PostgreSQL `bigserial` / identity columns through `ExecutionResult.getGeneratedKeys()`
|
||||
- for reproducible automated tests, prefer a disposable PostgreSQL instance such as Docker/Testcontainers instead of a long-lived shared server
|
||||
|
||||
---
|
||||
|
||||
#### Lifetime rules
|
||||
@@ -236,5 +385,6 @@ The same lifetime rule applies to generated keys returned by `ExecutionResult.ge
|
||||
|
||||
- `lyng.io.db` — generic contract, available when host code installs it
|
||||
- `lyng.io.db.sqlite` — implemented on JVM and Linux Native in the current release tree
|
||||
- `lyng.io.db.jdbc` — implemented on JVM in the current release tree
|
||||
|
||||
For the broader I/O overview, see [lyngio overview](lyngio.md).
|
||||
+16
-12
@@ -12,7 +12,7 @@
|
||||
|
||||
#### Included Modules
|
||||
|
||||
- **[lyng.io.db](lyng.io.db.md):** Portable SQL database access. Provides `Database`, `SqlTransaction`, `ResultSet`, and SQLite support through `lyng.io.db.sqlite`.
|
||||
- **[lyng.io.db](lyng.io.db.md):** Portable SQL database access. Provides `Database`, `SqlTransaction`, `ResultSet`, SQLite support through `lyng.io.db.sqlite`, and JVM JDBC support through `lyng.io.db.jdbc`.
|
||||
- **[lyng.io.fs](lyng.io.fs.md):** Async filesystem access. Provides the `Path` class for file/directory operations, streaming, and globbing.
|
||||
- **[lyng.io.process](lyng.io.process.md):** External process execution and shell commands. Provides `Process`, `RunningProcess`, and `Platform` information.
|
||||
- **[lyng.io.console](lyng.io.console.md):** Rich console/TTY access. Provides `Console` capability detection, geometry, output, and iterable events.
|
||||
@@ -45,6 +45,7 @@ To use `lyngio` modules in your scripts, you must install them into your Lyng sc
|
||||
```kotlin
|
||||
import net.sergeych.lyng.EvalSession
|
||||
import net.sergeych.lyng.io.db.createDbModule
|
||||
import net.sergeych.lyng.io.db.jdbc.createJdbcModule
|
||||
import net.sergeych.lyng.io.db.sqlite.createSqliteModule
|
||||
import net.sergeych.lyng.io.fs.createFs
|
||||
import net.sergeych.lyng.io.process.createProcessModule
|
||||
@@ -65,6 +66,7 @@ suspend fun runMyScript() {
|
||||
|
||||
// Install modules with policies
|
||||
createDbModule(scope)
|
||||
createJdbcModule(scope)
|
||||
createSqliteModule(scope)
|
||||
createFs(PermitAllAccessPolicy, scope)
|
||||
createProcessModule(PermitAllProcessAccessPolicy, scope)
|
||||
@@ -76,6 +78,7 @@ suspend fun runMyScript() {
|
||||
// Now scripts can import them
|
||||
session.eval("""
|
||||
import lyng.io.db
|
||||
import lyng.io.db.jdbc
|
||||
import lyng.io.db.sqlite
|
||||
import lyng.io.fs
|
||||
import lyng.io.process
|
||||
@@ -84,6 +87,7 @@ suspend fun runMyScript() {
|
||||
import lyng.io.net
|
||||
import lyng.io.ws
|
||||
|
||||
println("H2 JDBC available: " + (openH2("mem:demo;DB_CLOSE_DELAY=-1") != null))
|
||||
println("SQLite available: " + (openSqlite(":memory:") != null))
|
||||
println("Working dir: " + Path(".").readUtf8())
|
||||
println("OS: " + Platform.details().name)
|
||||
@@ -102,7 +106,7 @@ suspend fun runMyScript() {
|
||||
`lyngio` is built with a "Secure by Default" philosophy. Every I/O or process operation is checked against a policy.
|
||||
|
||||
- **Filesystem Security:** Implement `FsAccessPolicy` to restrict access to specific paths or operations (e.g., read-only access to a sandbox directory).
|
||||
- **Database Installation:** Database access is still explicit-capability style. The host must install `lyng.io.db` and at least one provider such as `lyng.io.db.sqlite`; otherwise scripts cannot open databases.
|
||||
- **Database Installation:** Database access is still explicit-capability style. The host must install `lyng.io.db` and at least one provider such as `lyng.io.db.sqlite` or `lyng.io.db.jdbc`; otherwise scripts cannot open databases.
|
||||
- **Process Security:** Implement `ProcessAccessPolicy` to restrict which executables can be run or to disable shell execution entirely.
|
||||
- **Console Security:** Implement `ConsoleAccessPolicy` to control output writes, event reads, and raw mode switching.
|
||||
- **HTTP Security:** Implement `HttpAccessPolicy` to restrict which requests scripts may send.
|
||||
@@ -122,16 +126,16 @@ For more details, see the specific module documentation:
|
||||
|
||||
#### Platform Support Overview
|
||||
|
||||
| Platform | lyng.io.db/sqlite | lyng.io.fs | lyng.io.process | lyng.io.console | lyng.io.http | lyng.io.ws | lyng.io.net |
|
||||
| :--- | :---: | :---: | :---: | :---: | :---: | :---: | :---: |
|
||||
| **JVM** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
|
||||
| **Linux Native** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
|
||||
| **Apple Native** | ❌ | ✅ | ✅ | ✅ | ✅ | ✅ | ⚠️ |
|
||||
| **Windows Native** | ❌ | ✅ | ❌ | ✅ | ✅ | ✅ | ❌ |
|
||||
| **Android** | ⚠️ | ✅ | ❌ | ⚠️ | ✅ | ✅ | ✅ |
|
||||
| **JS / Node** | ❌ | ✅ | ❌ | ⚠️ | ✅ | ✅ | ✅ |
|
||||
| **JS / Browser** | ❌ | ✅ (in-memory) | ❌ | ⚠️ | ✅ | ✅ | ❌ |
|
||||
| **Wasm** | ❌ | ✅ (in-memory) | ❌ | ⚠️ | ❌ | ❌ | ❌ |
|
||||
| Platform | lyng.io.db/sqlite | lyng.io.db/jdbc | lyng.io.fs | lyng.io.process | lyng.io.console | lyng.io.http | lyng.io.ws | lyng.io.net |
|
||||
| :--- | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: |
|
||||
| **JVM** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
|
||||
| **Linux Native** | ✅ | ❌ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
|
||||
| **Apple Native** | ❌ | ❌ | ✅ | ✅ | ✅ | ✅ | ✅ | ⚠️ |
|
||||
| **Windows Native** | ❌ | ❌ | ✅ | ❌ | ✅ | ✅ | ✅ | ❌ |
|
||||
| **Android** | ⚠️ | ❌ | ✅ | ❌ | ⚠️ | ✅ | ✅ | ✅ |
|
||||
| **JS / Node** | ❌ | ❌ | ✅ | ❌ | ⚠️ | ✅ | ✅ | ✅ |
|
||||
| **JS / Browser** | ❌ | ❌ | ✅ (in-memory) | ❌ | ⚠️ | ✅ | ✅ | ❌ |
|
||||
| **Wasm** | ❌ | ❌ | ✅ (in-memory) | ❌ | ⚠️ | ❌ | ❌ | ❌ |
|
||||
|
||||
Legend:
|
||||
- `✅` supported
|
||||
|
||||
Reference in new issue
Block a user