Align SQLite CLI URL forms across languages

CHANGELOG.md

@@ -9,6 +9,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- Accept `sqlite:path` and `sqlite::memory:` in the CLI alongside the existing `sqlite://` forms, including offline migration SQL export. [PR #1588](https://github.com/riverqueue/river/pull/1588).
+- Reject empty SQLite paths in commands that connect to a database; bare prefixes remain valid for offline migration SQL export. [PR #1588](https://github.com/riverqueue/river/pull/1588).
 - Fixed `JobListParams.Where` writing into the first `NamedArgs` it's given when merging multiple sets of named arguments, which could leak arguments into a map the caller reused for another query. It also no longer panics when the first set is `nil`. [PR #1575](https://github.com/riverqueue/river/pull/1575).
 
 ## [0.51.1] - 2026-11-05

cmd/river/rivercli/command.go

@@ -70,9 +70,13 @@ func RunCommand[TOpts CommandOpts](ctx context.Context, bundle *RunCommandBundle
 			protocol = "postgres"
 		} else if bundle.DatabaseURL != nil {
 			databaseURL = bundle.DatabaseURL
-			var ok bool
-			protocol, urlWithoutProtocol, ok = strings.Cut(*databaseURL, "://")
-			if !ok {
+			var hasProtocol bool
+			if sqlitePath, sqlite := strings.CutPrefix(*databaseURL, "sqlite:"); sqlite {
+				protocol, urlWithoutProtocol, hasProtocol = "sqlite", strings.TrimPrefix(sqlitePath, "//"), true
+			} else {
+				protocol, urlWithoutProtocol, hasProtocol = strings.Cut(*databaseURL, "://")
+			}
+			if !hasProtocol {
 				return false, fmt.Errorf("expected database URL (`%s`) to be formatted like `postgres://...`", *bundle.DatabaseURL)
 			}
 		}
@@ -95,6 +99,10 @@ func RunCommand[TOpts CommandOpts](ctx context.Context, bundle *RunCommandBundle
 				}
 
 			case "sqlite":
+				if _, isMigrateGet := any(command).(*migrateGet); urlWithoutProtocol == "" && !isMigrateGet {
+					return false, fmt.Errorf("SQLite database URL (`%s`) needs a path or `:memory:`", *databaseURL)
+				}
+
 				dbPool, err := openSQLitePool(protocol, urlWithoutProtocol)
 				if err != nil {
 					return false, err

cmd/river/rivercli/river_cli.go

@@ -151,7 +151,7 @@ default.
 	}
 
 	addDatabaseURLFlag := func(cmd *cobra.Command, databaseURL *string) {
-		cmd.Flags().StringVar(databaseURL, "database-url", "", "URL of the database (should look like `postgres://...`)")
+		cmd.Flags().StringVar(databaseURL, "database-url", "", "URL of the database (postgres://..., sqlite://path, or sqlite:path)")
 	}
 	addLineFlag := func(cmd *cobra.Command, line *string) {
 		cmd.Flags().StringVar(line, "line", "", "migration line to operate on (default: main)")
@@ -412,7 +412,7 @@ func (c *bench) Run(ctx context.Context, opts *benchOpts) (bool, error) {
 		// In the special case of a purely ephemeral memory database, migrate
 		// the schema up to make sure it's fully prepared for use. (Otherwise
 		// there's no way to raise it.)
-		if parsedDatabaseURL.Host == ":memory:" {
+		if parsedDatabaseURL.Host == ":memory:" || parsedDatabaseURL.Opaque == ":memory:" {
 			migrator, err := c.DriverProcurer.GetMigrator(&rivermigrate.Config{
 				Schema: opts.Schema,
 			})

cmd/river/rivercli/river_cli_test.go

@@ -8,6 +8,8 @@ import (
 	"fmt"
 	"maps"
 	"net/url"
+	"os"
+	"path/filepath"
 	"runtime/debug"
 	"strconv"
 	"strings"
@@ -544,6 +546,100 @@ SELECT 'up 1' FROM river_table
 		`), strings.TrimSpace(out.String()))
 }
 
+func TestBaseCommandSetSQLiteURLs(t *testing.T) {
+	t.Parallel()
+
+	runFunc := func(t *testing.T, databaseURL string, args ...string) string {
+		t.Helper()
+
+		var out bytes.Buffer
+		cli := NewCLI(&Config{Name: "River"})
+		cli.SetOut(&out)
+		cmd := cli.BaseCommandSet()
+		cmd.SetArgs(append(args, "--database-url", databaseURL))
+		require.NoError(t, cmd.Execute())
+		return out.String()
+	}
+
+	t.Run("BenchMemory", func(t *testing.T) {
+		t.Parallel()
+
+		for _, databaseURL := range []string{"sqlite::memory:", "sqlite://:memory:"} {
+			t.Run(databaseURL, func(t *testing.T) {
+				t.Parallel()
+
+				runFunc(t, databaseURL, "bench", "--num-total-jobs", "10")
+			})
+		}
+	})
+
+	t.Run("DialectHint", func(t *testing.T) {
+		t.Parallel()
+
+		for _, databaseURL := range []string{"sqlite:", "sqlite://"} {
+			sql := runFunc(t, databaseURL, "migrate-get", "--version", "1", "--up")
+			require.Contains(t, sql, "id integer PRIMARY KEY")
+		}
+	})
+
+	t.Run("EmptyPathRejected", func(t *testing.T) {
+		t.Parallel()
+
+		for _, databaseURL := range []string{"sqlite:", "sqlite://"} {
+			for _, command := range []string{"bench", "migrate-down", "migrate-list", "migrate-up", "validate"} {
+				t.Run(databaseURL+"/"+command, func(t *testing.T) {
+					t.Parallel()
+
+					cli := NewCLI(&Config{Name: "River"})
+					cli.SetOut(&bytes.Buffer{})
+					cmd := cli.BaseCommandSet()
+					cmd.SetArgs([]string{command, "--database-url", databaseURL})
+					require.ErrorContains(t, cmd.Execute(), "needs a path or `:memory:`")
+				})
+			}
+		}
+	})
+
+	t.Run("File", func(t *testing.T) {
+		t.Parallel()
+
+		for _, prefix := range []string{"sqlite:", "sqlite://"} {
+			t.Run(prefix, func(t *testing.T) {
+				t.Parallel()
+
+				path := filepath.Join(t.TempDir(), "river.db")
+				workingDir, err := os.Getwd()
+				require.NoError(t, err)
+				relativePath, err := filepath.Rel(workingDir, path)
+				require.NoError(t, err)
+				databaseURL := prefix + relativePath
+
+				sql := runFunc(t, databaseURL, "migrate-get", "--version", "1", "--up")
+				require.Contains(t, sql, "CREATE TABLE")
+				require.NoFileExists(t, path)
+				runFunc(t, databaseURL, "migrate-up")
+				require.FileExists(t, path)
+				runFunc(t, "sqlite://"+path, "validate")
+			})
+		}
+	})
+
+	t.Run("Memory", func(t *testing.T) {
+		t.Parallel()
+
+		for _, databaseURL := range []string{"sqlite::memory:", "sqlite://:memory:"} {
+			t.Run(databaseURL, func(t *testing.T) {
+				t.Parallel()
+
+				sql := runFunc(t, databaseURL, "migrate-get", "--version", "1", "--up")
+				require.Contains(t, sql, "CREATE TABLE")
+				out := runFunc(t, databaseURL, "migrate-up")
+				require.Contains(t, out, "applied migration 008")
+			})
+		}
+	})
+}
+
 func TestMigrateGet(t *testing.T) {
 	t.Parallel()
 

docs/sqlite-urls.md

@@ -0,0 +1,29 @@
+# SQLite CLI URLs
+
+The Go, Java, JavaScript, Ruby, and Rust migration CLIs accept the same SQLite
+prefixes. The `//` after `sqlite:` is optional:
+
+| Database | Long form | Short form |
+| --- | --- | --- |
+| Relative file | `sqlite://river.db` | `sqlite:river.db` |
+| Absolute file | `sqlite:///var/lib/app/river.db` | `sqlite:/var/lib/app/river.db` |
+| In memory | `sqlite://:memory:` | `sqlite::memory:` |
+
+Relative paths are resolved from the command's working directory. An in-memory
+database lasts only for that invocation; use a file to share a database between
+migration commands and application processes.
+
+Commands that connect to a database reject an empty SQLite path. Use an explicit
+`:memory:` path if you want a temporary database.
+
+For `migrate-get`, `--database-url` only selects the SQL dialect. Both `sqlite:`
+and `sqlite://` work without a path, and export never opens or creates a database.
+
+Ruby also accepts `sqlite3:` and `sqlite3://` with either Active Record or Sequel.
+Java also accepts native `jdbc:sqlite:` URLs, passed unchanged to the JDBC driver.
+These aliases are specific to those languages. Query parameters and
+percent-encoding are handled differently by each language and can select a
+different file, or turn an in-memory database into an on-disk file. For portable
+URLs, avoid `?` and `%` in paths, and don't add parameters to `:memory:`.
+Driver-specific URI options are not portable; for example, Rust's `?mode=rwc`
+creates a missing database file.

java/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Fixed
+
+- Normalize `sqlite://` URLs before opening JDBC connections so relative paths remain relative and `sqlite://:memory:` opens an in-memory database. Preserve `sqlite:` and native `jdbc:sqlite:` URLs. [PR #1588](https://github.com/riverqueue/river/pull/1588).
+  - **Upgrade note:** `sqlite://var/lib/x.db` now opens `./var/lib/x.db` instead of `/var/lib/x.db`. Use `sqlite:///var/lib/x.db` to keep targeting the absolute path.
+- Reject empty SQLite paths in commands that connect to a database; bare prefixes remain valid for offline migration SQL export. [PR #1588](https://github.com/riverqueue/river/pull/1588).
+
 ## [0.4.0] - 2026-11-06
 
 ### Added

java/DIFFERENCES.md

@@ -10,6 +10,9 @@
 - A `DataSource` and its pool belong to the application. `Database.connect`
   uses DriverManager without pooling; callers wanting pooled connections supply
   a data source. River-owned JDBC connections are closed after each transaction.
+- SQLite connections accept the shared `sqlite:` and `sqlite://` forms, plus
+  native `jdbc:sqlite:` URLs passed unchanged to JDBC. See the
+  [SQLite URL reference](../docs/sqlite-urls.md) for the portable forms.
 - Caller-owned transactions use JDBC savepoints. Hooks run within those
   savepoints, so a failed River operation leaves the outer transaction usable.
 - Cancellation is cooperative and followed by interruption after the configured

java/README.md

@@ -88,6 +88,10 @@ for each operation. River never closes an application-owned data source. An
 
 ## Migration CLI
 
+SQLite connections accept `sqlite://path` and `sqlite:path`, as well as native
+`jdbc:sqlite:` URLs. See the shared [SQLite URL reference](../docs/sqlite-urls.md)
+for relative paths and in-memory databases.
+
 The CLI runs with Java 21 or newer. [JBang](https://www.jbang.dev/documentation/jbang/latest/installation.html)
 resolves the thin CLI JAR and its dependencies and installs a reusable command:
 

java/cli/src/main/java/com/riverqueue/cli/MigrationCli.java

@@ -46,6 +46,8 @@ private static Database database(
         && !url.startsWith("sqlite:")
         && !url.startsWith("jdbc:sqlite:"))
       throw new Usage("Expected a Postgres URL or a SQLite JDBC URL");
+    if (!offline && Set.of("sqlite:", "sqlite://", "jdbc:sqlite:").contains(url))
+      throw new Usage("SQLite database URL needs a path or `:memory:`");
     Database database;
     try {
       database =

java/cli/src/test/java/com/riverqueue/cli/MigrationCliTest.java

@@ -117,6 +117,42 @@ void operationFailureHasNonzeroExit() {
     assertTrue(result.out().isEmpty());
   }
 
+  @Test
+  void sqliteEmptyPathsAreRejected() {
+    for (String url : List.of("sqlite:", "sqlite://", "jdbc:sqlite:")) {
+      for (String command : List.of("migrate-down", "migrate-list", "migrate-up")) {
+        var result = run(Map.of(), command, "--database-url", url);
+        assertEquals(2, result.exit(), result.err());
+        assertTrue(result.err().contains("needs a path or `:memory:`"), result.err());
+        assertTrue(result.out().isEmpty());
+      }
+    }
+  }
+
+  @Test
+  void sqliteUrlForms() {
+    for (String prefix : List.of("sqlite:", "sqlite://", "jdbc:sqlite:")) {
+      var hint = run(Map.of(), "migrate-get", "--database-url", prefix, "--version", "1", "--up");
+      assertEquals(0, hint.exit(), hint.err());
+      assertTrue(hint.out().contains("id integer PRIMARY KEY"));
+      Path file = directory.resolve("forms-" + prefix.length() + ".db");
+      String relative = Path.of("").toAbsolutePath().relativize(file).toString();
+      String url = prefix + relative;
+      var exported = run(Map.of(), "migrate-get", "--database-url", url, "--version", "1", "--up");
+      assertEquals(0, exported.exit(), exported.err());
+      assertTrue(exported.out().contains("id integer PRIMARY KEY"));
+      assertFalse(java.nio.file.Files.exists(file));
+      var up = run(Map.of(), "migrate-up", "--database-url", url);
+      assertEquals(0, up.exit(), up.err());
+      assertTrue(java.nio.file.Files.exists(file));
+      var listed = run(Map.of(), "migrate-list", "--database-url", "sqlite://" + file);
+      assertEquals(0, listed.exit(), listed.err());
+      assertTrue(listed.out().contains("008      applied"), listed.out());
+      var memory = run(Map.of(), "migrate-list", "--database-url", prefix + ":memory:");
+      assertEquals(0, memory.exit(), memory.err());
+    }
+  }
+
   @Test
   void targetsLimitsAndDryRunsPreserveExpectedHistory() {
     var environment = Map.of("DATABASE_URL", "jdbc:sqlite:" + directory.resolve("river.db"));

java/river/src/main/java/com/riverqueue/Database.java

@@ -41,7 +41,12 @@ public static Database connect(String url) {
 
   public static Database connect(String url, String applicationName) {
     if (url.startsWith("sqlite:") || url.startsWith("jdbc:sqlite:")) {
-      String jdbc = url.startsWith("jdbc:") ? url : "jdbc:" + url;
+      String jdbc;
+      if (url.startsWith("jdbc:")) jdbc = url;
+      else {
+        String path = url.substring("sqlite:".length());
+        jdbc = "jdbc:sqlite:" + (path.startsWith("//") ? path.substring(2) : path);
+      }
       return new Database(() -> DriverManager.getConnection(jdbc), Dialect.SQLITE, "");
     }
     String jdbc;

js/CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Fixed
+
+- Accept `sqlite:path` and `sqlite::memory:` in the CLI alongside the existing `sqlite://` forms, including offline migration SQL export. [PR #1588](https://github.com/riverqueue/river/pull/1588).
+
 ## [0.3.1] - 2026-11-05
 
 ### Fixed

js/cli/README.md

@@ -28,8 +28,10 @@ Run `npx riverqueue --help` for every command, and
 - `postgres://…` or `postgresql://…` for Postgres. Without
   `--database-url`, Postgres commands use the standard `PG*` environment
   variables when `PGDATABASE` is set.
-- `sqlite://PATH` for SQLite, for example `sqlite:///var/lib/app/river.db`
-  for an absolute path or `sqlite://river.db` for a relative one.
+- `sqlite://PATH` or `sqlite:PATH` for SQLite, for example
+  `sqlite:///var/lib/app/river.db` for an absolute path or `sqlite://river.db`
+  for a relative one. `sqlite::memory:` and `sqlite://:memory:` use an in-memory
+  database. See the shared [SQLite URL reference](../../docs/sqlite-urls.md).
 
 Other common flags:
 

js/cli/src/database.ts

@@ -43,7 +43,8 @@ const SQLITE_BUSY_TIMEOUT_MS = 5_000;
  *
  * `postgres://` and `postgresql://` URLs select Postgres. `sqlite://PATH`
  * selects SQLite, where `PATH` is a file path (`sqlite:///abs/river.db` or
- * `sqlite://relative/river.db`), `:memory:`, or a `file:` URL. Without a URL,
+ * `sqlite://relative/river.db`), `:memory:`, or a `file:` URL. The `//` is
+ * optional: `sqlite:relative/river.db` and `sqlite::memory:` also work. Without a URL,
  * Postgres is configured from `PG*` environment variables when
  * `PGDATABASE` is set, as node-postgres and River's Go CLI do.
  */
@@ -63,13 +64,15 @@ export function parseDatabaseUrl(
     );
   }
 
-  const scheme = /^([a-z][a-z0-9+.-]*):\/\//i.exec(url)?.[1]?.toLowerCase();
+  const scheme = /^sqlite:/i.test(url)
+    ? "sqlite"
+    : /^([a-z][a-z0-9+.-]*):\/\//i.exec(url)?.[1]?.toLowerCase();
   switch (scheme) {
     case "postgres":
     case "postgresql":
       return { backend: "postgres", connectionString: url };
     case "sqlite": {
-      const path = url.slice("sqlite://".length);
+      const path = url.slice("sqlite:".length).replace(/^\/\//, "");
       if (path.length === 0) {
         throw new UsageError(
           "a SQLite --database-url needs a path, such as sqlite:///var/lib/river.db",

js/cli/src/migrate-commands.ts

@@ -457,9 +457,9 @@ function sqlDialect(
   url: string | undefined
 ): MigrationBackend {
   if (url === undefined) return "postgres";
+  if (/^sqlite:/i.test(url)) return "sqlite";
   const scheme = /^([a-z][a-z0-9+.-]*):\/\//i.exec(url)?.[1]?.toLowerCase();
   if (scheme === "postgres" || scheme === "postgresql") return "postgres";
-  if (scheme === "sqlite") return "sqlite";
   throw new UsageError(
     "--database-url must start with postgres://, postgresql://, or sqlite://",
     command