Minecraft SQLite JDBC

SQLite JDBC for Minecraft

A maintained fork of the dormant SQLite JDBC for Minecraft mod, now tracking the latest Xerial sqlite-jdbc release with auto-bumps whenever upstream cuts a new version.

The mod does nothing on its own — it ships the SQLite JDBC driver onto the server's classpath so other plugins/mods that want to read or write `.db`/`.sqlite` files via JDBC don't each have to bundle their own copy.

Typical consumers: Dynmap, Plan, LuckPerms, Grim Anti-Cheat, and any plugin that wants embedded SQLite without redistributing 10MB of native binaries themselves.

What's in the jar

`org.xerial:sqlite-jdbc:3.53.0.0` plus minimal loader stubs for Spigot, Forge 1.12, Forge 1.13–1.16, Forge 1.17–1.20, NeoForge 1.21+, and Fabric. The driver classes stay at their canonical `org.sqlite.*` paths — no relocation — so consumers find them with plain `Class.forName("org.sqlite.JDBC")`. `META-INF/services/java.sql.Driver` is preserved so the driver auto-registers with `DriverManager`.

The xerial driver bundles native SQLite binaries for every common platform/architecture (linux x64/aarch64, macos x64/arm64, windows x64). They get extracted to the JVM's tempdir on first use.

Compatibility

| Loader | MC versions | Notes | |---|---|---| | Bukkit / Spigot / Paper / Folia / Purpur | 1.8 → current | drop into `plugins/` | | Fabric | 1.16.1 → current | needs Fabric Loader 0.14+ | | Forge | 1.12 → 1.20 | universal jar, no Mixins | | NeoForge | 1.21 → current | drop into `mods/` |

Java 8+ required. Plain BukkitAPI servers without Java 8 (anything older than ~1.8.8) won't be able to load any modern xerial release; that's an upstream constraint, not this mod.

When you actually need this mod

CraftBukkit/Spigot/Paper have shipped `sqlite-jdbc` on the server's parent classloader since the 1.4-era ebeans commit. Plugin classloaders delegate parent-first, so for the default JDBC path (`Class.forName("org.sqlite.JDBC")` / `DriverManager.getConnection`) the bundled driver always wins, regardless of what's in `plugins/`. Tested empirically on Paper 1.12.2 and 1.21.11.

You need this mod when:

- You're on newer SQLite engine version than your server bundles or newer SQLite engine version than your server bundles — vanilla Minecraft ships no JDBC drivers at all - You're on a newer SQLite engine version than your server bundles (rare, but happens on minified server builds) - You want a newer SQLite engine version than your server bundles — for `RETURNING`, `STRICT` tables, modern UPSERT on a 1.8–1.12 server, or just to track the latest Xerial release. See newer SQLite engine version than your server bundles below.

Using a newer engine via the public API

The default path uses the bundled driver. To use *this* mod's driver instead, your plugin softdepends on this holder and calls `MinecraftSqliteJdbc.connect(url)` directly:

```java // in your plugin.yml softdepend: [sqlite-jdbc] ```

```java // in your plugin code Connection c; try { c = MinecraftSqliteJdbc.connect("jdbc:sqlite:foo.db"); } catch (NoClassDefFoundError | ClassNotFoundException notInstalled) { // holder isn't installed — fall back to the bundled driver c = DriverManager.getConnection("jdbc:sqlite:foo.db"); } ```

`MinecraftSqliteJdbc` wraps a child-first `URLClassLoader` pointing at this jar's URL, parented to the platform classloader so `org.sqlite.*` must come from this jar (not the bundled chain). The returned `Connection` is a standard `java.sql.Connection` — keep your casts to `java.sql.*` interfaces; the impl class `org.sqlite.SQLiteConnection` lives in the child-first classloader and won't down-cast across the boundary.

Verified on Paper 1.12.2 (bundled engine 3.21.0) — same JVM, same boot:

``` baseline DriverManager.getConnection → engine 3.21.0 MinecraftSqliteJdbc.connect() → engine 3.53.0 ```

API surface (all static):

| Method | Returns | |---|---| | `connect(String url)` | open `Connection` through this driver | | `connect(String url, Properties props)` | as above with props | | `driver()` | the `java.sql.Driver` instance | | `engineVersion()` | SQLite engine version (e.g. `"3.53.0"`) | | `driverVersion()` | driver version string (e.g. `"3.53.0.0"`) | | `eagerInit()` | warm the classloader at plugin enable | | `shutdown()` | release file handles + JNI on plugin disable |

Grim Anti-Cheat's SQLite backend uses this API automatically when this holder is installed and ships a newer engine than the bundled one — see Grim's Database wiki page.

Bundled SQLite engine versions on common Bukkit lines

For reference if you're wondering what engine version your server actually ships:

| CraftBukkit / Paper line | Bundled SQLite engine | |---|---| | 1.8 – 1.10 | 3.7.2 | | 1.11 | 3.16.1 | | 1.12 | 3.21.0.1 | | 1.13 | 3.25.2 | | 1.14 | 3.28.0 | | 1.15 | 3.30.1 | | 1.16 – 1.17 | 3.34.0 | | 1.20.6 | 3.45.3.0 | | Paper 1.21.4 | 3.47.0.0 | | Paper 1.21.5 – 1.21.11 | 3.49.1.0 | | master / 26.x | 3.51.3.0 |

This mod ships engine 3.53.0.0 (or whatever the latest xerial release is), but none of that matters on Bukkit-family servers — the bundled engine is what actually runs your queries. If you need a newer engine for features like `RETURNING` (3.35+) or `STRICT` tables (3.37+), upgrade to a Paper version that bundles a recent enough driver, or move that workload to Fabric/NeoForge where you can control the driver.

Using it from a plugin or mod

Declare sqlite-jdbc as `compileOnly`:

```kotlin compileOnly("org.xerial:sqlite-jdbc:3.53.0.0") ```

Probe at startup:

```java try { Class.forName("org.sqlite.JDBC"); } catch (ClassNotFoundException e) { getLogger().warning("SQLite backend disabled — install minecraft-sqlite-jdbc"); return; } try (Connection c = DriverManager.getConnection("jdbc:sqlite:" + dataDir.resolve("data.db"))) { // ... } ```

On Paper 1.17+ each plugin's classloader is isolated. Add this mod to your `plugin.yml` `softdepend` so the driver classes are visible to your plugin:

```yaml softdepend: [minecraft-sqlite-jdbc] ```

Fabric and NeoForge unify all mods on one classloader, so no equivalent declaration is needed there.

Versioning

The jar version tracks Xerial's `sqlite-jdbc` release one-to-one. `3.53.0.0+2026-04-14` ships engine 3.53.0.0; the suffix is the build date. A scheduled GitHub Action checks Maven Central daily — when xerial cuts a new release, an auto-merge PR opens here and the Modrinth release goes out automatically.

License

Apache 2.0 (Xerial / Taro L. Saito). The repackage adds no functional changes and inherits that license. Full text in `LICENSE`.

---

Issues, source: GitHub.