diff --git a/README.md b/README.md index 33ee6d2..01c42fd 100644 --- a/README.md +++ b/README.md @@ -133,6 +133,59 @@ DOCKER_CONFIG="$PWD/libsql-conformance/src/test/docker-config" ./mvnw clean veri The compliance profile is in [`docs/jdbc-appendix-b-compliance.md`](docs/jdbc-appendix-b-compliance.md). +## Integrations + +### Liquibase + +Liquibase's SQLite implementation claims the `jdbc:sqlite:` prefix and selects its +dialect from the database product name. The driver maps `jdbc:sqlite:http://...` to +sqld and reports the product name as exactly `SQLite`, so the two work together. + +Liquibase still resolves a JDBC driver class from the URL before it opens a connection. +It maps `jdbc:sqlite:` to `org.sqlite.JDBC`, which is not on the classpath, so name +`LibsqlDriver` explicitly or pass a `DataSource`. + +Use one of these configurations: + +**API with an explicit driver class** + +```java +import io.github.magnusp.libsql.jdbc.LibsqlDriver; +import liquibase.database.Database; +import liquibase.database.DatabaseFactory; +import liquibase.resource.ClassLoaderResourceAccessor; + +Database database = DatabaseFactory.getInstance().openDatabase( + "jdbc:sqlite:http://localhost:8080", + null, // username + null, // password + LibsqlDriver.class.getName(), // driver + null, // database class + null, // driver properties file + null, // property provider class + new ClassLoaderResourceAccessor()); +``` + +**Liquibase Maven plugin or `liquibase.properties`** + +```properties +url=jdbc:sqlite:http://localhost:8080 +driver=io.github.magnusp.libsql.jdbc.LibsqlDriver +``` + +**Spring Boot or a connection pool** + +Pass a `DataSource` and set the driver class explicitly: + +```properties +spring.datasource.url=jdbc:sqlite:http://localhost:8080 +spring.datasource.driver-class-name=io.github.magnusp.libsql.jdbc.LibsqlDriver +``` + +Use the `jdbc:sqlite:` prefix so Liquibase's SQLite implementation claims the URL. +`jdbc:libsql:` also reaches the driver, but Liquibase cannot resolve a driver from it +and still needs the explicit driver class. + ## Contributing We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines and development workflow, and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for community standards. diff --git a/libsql-jdbc/src/test/java/io/github/magnusp/libsql/jdbc/liquibase/LiquibaseIT.java b/libsql-jdbc/src/test/java/io/github/magnusp/libsql/jdbc/liquibase/LiquibaseIT.java index f50d60b..37d2f1d 100644 --- a/libsql-jdbc/src/test/java/io/github/magnusp/libsql/jdbc/liquibase/LiquibaseIT.java +++ b/libsql-jdbc/src/test/java/io/github/magnusp/libsql/jdbc/liquibase/LiquibaseIT.java @@ -1,5 +1,6 @@ package io.github.magnusp.libsql.jdbc.liquibase; +import io.github.magnusp.libsql.jdbc.LibsqlDriver; import liquibase.Contexts; import liquibase.LabelExpression; import liquibase.Liquibase; @@ -161,6 +162,32 @@ void databaseFactoryResolvesTheSqliteImplementation() throws Exception { } } + /** + * The supported bootstrapping path: use the {@code jdbc:sqlite:} prefix that + * Liquibase's SQLite implementation claims and name the driver class + * explicitly. The driver maps that prefix to sqld. + */ + @Test + void databaseFactoryOpensASqliteAliasUrlWithAnExplicitDriver() throws Exception { + // The five-argument openDatabase overload names a property-provider class, not a + // driver. The eight-argument overload takes the driver explicitly. + Database database = DatabaseFactory.getInstance() + .openDatabase( + sqliteJdbcUrl(), + null, + null, + LibsqlDriver.class.getName(), + null, + null, + null, + new ClassLoaderResourceAccessor()); + try { + assertThat(database).isInstanceOf(SQLiteDatabase.class); + } finally { + database.close(); + } + } + /** * Pins the second bootstrapping gap: Liquibase resolves a JDBC driver class * from the URL before it opens a connection, and its SQLite implementation diff --git a/libsql-jdbc/src/test/java/io/github/magnusp/libsql/jdbc/liquibase/LiquibaseSqldSupport.java b/libsql-jdbc/src/test/java/io/github/magnusp/libsql/jdbc/liquibase/LiquibaseSqldSupport.java index 3f606ac..98d6128 100644 --- a/libsql-jdbc/src/test/java/io/github/magnusp/libsql/jdbc/liquibase/LiquibaseSqldSupport.java +++ b/libsql-jdbc/src/test/java/io/github/magnusp/libsql/jdbc/liquibase/LiquibaseSqldSupport.java @@ -37,6 +37,11 @@ static String jdbcUrl() { return "jdbc:libsql:http://" + LIBSQL.getHost() + ":" + LIBSQL.getMappedPort(PORT); } + /** The prefix Liquibase's SQLite implementation claims; the driver maps it to sqld. */ + static String sqliteJdbcUrl() { + return "jdbc:sqlite:http://" + LIBSQL.getHost() + ":" + LIBSQL.getMappedPort(PORT); + } + private static String requireLibsqlImage() { String image = System.getProperty("libsql.image"); if (image == null || image.isBlank()) {