Skip to content

docs: document the Flyway bootstrap for jdbc:libsql URLs - #271

Merged
magnusp merged 3 commits into
fix/258-connection-scoped-streamfrom
docs/263-flyway-bootstrap
Oct 31, 2026
Merged

docs: document the Flyway bootstrap for jdbc:libsql URLs#271
magnusp merged 3 commits into
fix/258-connection-scoped-streamfrom
docs/263-flyway-bootstrap

Conversation

@magnusp

@magnusp magnusp commented Oct 31, 2026 •
edited
Loading

Copy link
Copy Markdown
Owner

Part 4 of the 4-PR stack (#268 → #269 → #270 → #271). Closes #263. Builds on #258.

What changed

  • Added a Flyway integration section to README.md covering:
    • A DataSource with either jdbc:libsql: or jdbc:sqlite: (the recommended path).
    • URL-based configuration with the jdbc:sqlite: alias and an explicit LibsqlDriver class, for the Maven plugin or flyway.properties.
    • Why jdbc:libsql: cannot be used with URL-based configuration at all.
  • Documented the session-state behavior after Keep a connection-scoped Hrana stream for auto-commit: fix last_insert_rowid() and Flyway clean() #258: auto-commit statements on one connection share a stream, so initSql / afterConnect PRAGMAs apply to later migrations until the idle stream expires.
  • Documented the one Flyway clean() requirement: set PRAGMA foreign_keys = OFF through initSql (or afterConnect), because Flyway wraps clean in a transaction and SQLite ignores that pragma inside a transaction. The driver's multi-statement splitting then runs Flyway's PRAGMA/DROP scripts on one stream.

The two negative pins for URL-based plugin/driver resolution stay in FlywayKnownGapsIT.

Verification

  • ./mvnw -pl libsql-jdbc -am test
  • ./mvnw spotless:check
  • CI (Java 25, Java 26, Xerial Control) is green.

@magnusp
magnusp added this pull request to stack #272 October 31, 2026 00:41
This was referenced Oct 31, 2026
Merged
Merged
Merged
@magnusp
magnusp force-pushed the docs/263-flyway-bootstrap branch from ed39142 to df3fd6d Compare October 31, 2026 00:50
@magnusp
magnusp force-pushed the docs/263-flyway-bootstrap branch 3 times, most recently from 7504bde to 2f2b23a Compare October 31, 2026 01:39
@magnusp
magnusp force-pushed the docs/263-flyway-bootstrap branch from 2b3d4b2 to 8cd5986 Compare October 31, 2026 02:01
@magnusp
docs: document the Flyway bootstrap for jdbc:libsql URLs
a1661a9 
Flyway resolves its plugin and driver from the URL before connecting.
Document the DataSource path, the explicit-driver jdbc:sqlite: alias for
URL configuration, and why jdbc:libsql: cannot use URL configuration.
Record that auto-commit session state survives on one connection and that
clean() is supported. Closes #263.
@magnusp
docs(flyway): explain the foreign-key setup clean() needs
fde75a6 
Flyway wraps clean() in a transaction and SQLite ignores
PRAGMA foreign_keys inside one. Document initSql as the supported way to
disable foreign keys before that transaction, alongside the multi-statement
splitting that runs Flyway's PRAGMA/DROP scripts on one stream.
@magnusp
docs(flyway): use the spring.flyway.init-sqls property
6e1bc12 
Spring Boot maps the initSql list to spring.flyway.init-sqls, not
spring.flyway.init-sql. Correct the clean() setup snippet.
@magnusp
magnusp force-pushed the docs/263-flyway-bootstrap branch from 8cd5986 to 6e1bc12 Compare October 31, 2026 02:08
@magnusp
magnusp merged commit 593b891 into main Oct 31, 2026
10 checks passed
@magnusp
magnusp deleted the docs/263-flyway-bootstrap branch October 31, 2026 02:15
magnusp added a commit that referenced this pull request Oct 31, 2026
@magnusp
fix(jdbc): report SQLite metadata and the JDBC URL (#268)
bda077b 
Part 1 of the 4-PR stack (#268 → #269 → #270 → #271). Closes #261 and
#274.

## What changed

- `DatabaseMetaData.getDatabaseProductName()` now returns exactly
`SQLite`. The libSQL identity stays in `getDriverName()` (`libSQL JDBC
Driver`) and `getDatabaseProductVersion()`.
- `DatabaseMetaData.getURL()` now returns the JDBC URL the caller
connected with (`jdbc:libsql:...` or `jdbc:sqlite:...`) instead of the
transport endpoint (`http://...` / `ws://...`). Credential query
parameters (`authToken`, `jwt`, `password`, `token`) and user info are
redacted.
- Liquibase now resolves `SQLiteDatabase` through the normal
`DatabaseFactory` path instead of falling back to `UnsupportedDatabase`.
- jOOQ 3.21 derives its dialect from `DatabaseMetaData.getURL()`. With
the URL fix, the `jdbc:sqlite:` alias resolves to `SQLDialect.SQLITE`;
`jdbc:libsql:` still returns `SQLDialect.DEFAULT` because jOOQ has no
libsql prefix, so that path needs an explicit dialect.
- Updated the conformance guard, the WebSocket metadata assertion, and
the Liquibase/jOOQ probes to pin the new metadata.

## Verification

- `./mvnw -pl libsql-jdbc -am test`
- `./mvnw -pl libsql-conformance -am -Dtest=LibsqlConformanceGuardTest
-Dsurefire.failIfNoSpecifiedTests=false test`
- Targeted `JooqIT` against the pinned sqld container (libSQL →
`DEFAULT`, SQLite alias → `SQLITE`)
- Targeted `WebSocketTransportIT` against the pinned sqld container
- `./mvnw spotless:check`
- CI (Java 25, Java 26, Xerial Control) is green.
magnusp added a commit that referenced this pull request Oct 31, 2026
@magnusp
docs: document the Liquibase bootstrap for libSQL (#269)
161af09 
Part 2 of the 4-PR stack (#268 → #269 → #270 → #271). Closes #262.
Builds on #261.

## What changed

- Added a Liquibase integration section to `README.md` covering the
three supported bootstraps:
- `DatabaseFactory.openDatabase(...)` with the `jdbc:sqlite:` prefix and
`LibsqlDriver` named explicitly.
- Liquibase Maven plugin / `liquibase.properties` with
`driver=io.github.magnusp.libsql.jdbc.LibsqlDriver`.
  - Spring Boot or a pool with an explicit `DataSource` driver class.
- The `jdbc:sqlite:` prefix is the one Liquibase's SQLite implementation
claims, and the product name is exactly `SQLite` (#261), so Liquibase
selects its SQLite dialect through the normal `DatabaseFactory` path.
The driver maps the alias to sqld.
- Added
`LiquibaseIT#databaseFactoryOpensASqliteAliasUrlWithAnExplicitDriver`,
which uses the eight-argument `openDatabase` overload that names the
driver and asserts it resolves a `SQLiteDatabase`.
- Kept the negative pin that shows why a `jdbc:libsql:` URL cannot
resolve a driver without an explicit class.

## Verification

- Targeted `LiquibaseIT` against the pinned sqld container
- `./mvnw spotless:check`
- CI (Java 25, Java 26, Xerial Control) is green.
magnusp added a commit that referenced this pull request Oct 31, 2026
@magnusp
fix(jdbc): keep one connection-scoped Hrana stream for auto-commit (#270
e18336e 
)

Part 3 of the 4-PR stack (#268 → #269 → #270 → #271). Closes #258.

## What changed

Auto-commit now keeps one lazily opened Hrana stream per JDBC connection
instead of running every statement one-shot.

- `last_insert_rowid()`, `PRAGMA` settings, and other session state
survive between auto-commit statements on the same connection and do not
cross connections.
- A manual transaction begin is tracked explicitly, so an already-open
auto-commit stream cannot make the driver skip `BEGIN`. If that stream
expired while idle, the begin is retried once on a fresh stream.
- `Connection.close()` closes the session stream.
- An expired auto-commit stream is dropped and the statement is retried
once on a fresh stream. Session state set before expiry is gone, and
that reset is documented.
- Added `SqlScript`, a SQLite-aware statement splitter that handles
quoted text, comments, and trigger bodies. Multi-statement scripts run
in order on the same stream, sum update counts, expose the final result
set, and stop at the first failure.
- Multi-statement input with parameters is rejected with
`SQLFeatureNotSupportedException`.
- Updated the Flyway, Hibernate, jOOQ, and conformance probes:
  - The two xerial multi-statement cases are un-gated.
  - Hibernate runs with auto-commit at its default.
  - jOOQ auto-commit identity reads expect the generated value.
- Flyway `clean()` runs when `initSql` disables foreign keys on the
connection. Flyway wraps clean in a transaction, and SQLite ignores
`PRAGMA foreign_keys` inside one, so the pragma has to run at connection
initialization.
- Replaced the “auto-commit holds no stream” section in the conformance
README with the connection-scoped stream contract.

## Verification

- `./mvnw -pl libsql-jdbc -am test`
- Targeted `JooqIT`, `LiquibaseIT`, `FlywayKnownGapsIT`,
`AutoCommitSessionIT`, and `TransactionLifecycleIT` against the pinned
sqld container
- `./mvnw spotless:check`
- `./tools/export-upstream --verify` and `--self-test`
- CI (Java 25, Java 26, Xerial Control) is green.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Document the supported Flyway bootstrap for jdbc:libsql: URLs

1 participant

@magnusp