docs: document the Liquibase bootstrap for libSQL

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.

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;
@@ -135,7 +136,7 @@
         try (Connection conn = DriverManager.getConnection(jdbcUrl())) {
             Liquibase liquibase = liquibase(conn, "liquibase/changelog-sync.xml");
 
             liquibase.changeLogSync(new Contexts());
 
             assertThat(tableExists(conn, "lb_sync_table")).isFalse();
             assertThat(count(conn, "SELECT COUNT(*) FROM databasechangelog WHERE id = 'sync-1'"))
@@ -161,6 +162,32 @@
         }
     }
 
+    /**
+     * 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

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()) {