Repository navigation
docs: document the Liquibase bootstrap for libSQL - #269
Merged
magnusp merged 3 commits intoOct 31, 2026
Merged
Conversation
This was referenced Oct 31, 2026
magnusp
force-pushed
the
docs/262-liquibase-bootstrap
branch
from
October 31, 2026 00:50
dbe055d to
50281a3
Compare
magnusp
changed the title
magnusp
force-pushed
the
docs/262-liquibase-bootstrap
branch
from
October 31, 2026 02:01
a78d1a0 to
515467b
Compare
Liquibase resolves a driver from the URL before it connects, and its SQLite implementation claims only jdbc:sqlite:. Document the three supported configurations and pin the explicit-driver DatabaseFactory path. Closes #262.
The five-argument DatabaseFactory.openDatabase overload treats its fourth argument as a property-provider class, not a driver, so the probe failed with a ClassCastException. Use the eight-argument overload that names the driver explicitly, and correct the README snippet.
Liquibase's SQLite implementation claims jdbc:sqlite: and selects its dialect from the database product name, which is now exactly SQLite. The driver maps the alias to sqld, so document and pin that form with the explicit LibsqlDriver class that Liquibase still needs.
magnusp
force-pushed
the
docs/262-liquibase-bootstrap
branch
from
October 31, 2026 02:08
515467b to
2411fc9
Compare
magnusp
added a commit
that referenced
this pull request
Oct 31, 2026
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
) 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.
magnusp
added a commit
that referenced
this pull request
Oct 31, 2026
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 #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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Part 2 of the 4-PR stack (#268 → #269 → #270 → #271). Closes #262. Builds on #261.
What changed
README.mdcovering the three supported bootstraps:DatabaseFactory.openDatabase(...)with thejdbc:sqlite:prefix andLibsqlDrivernamed explicitly.liquibase.propertieswithdriver=io.github.magnusp.libsql.jdbc.LibsqlDriver.DataSourcedriver class.jdbc:sqlite:prefix is the one Liquibase's SQLite implementation claims, and the product name is exactlySQLite(Report database product name as exactly SQLite so dialect detection works #261), so Liquibase selects its SQLite dialect through the normalDatabaseFactorypath. The driver maps the alias to sqld.LiquibaseIT#databaseFactoryOpensASqliteAliasUrlWithAnExplicitDriver, which uses the eight-argumentopenDatabaseoverload that names the driver and asserts it resolves aSQLiteDatabase.jdbc:libsql:URL cannot resolve a driver without an explicit class.Verification
LiquibaseITagainst the pinned sqld container./mvnw spotless:check