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 Fabric or NeoForge — vanilla Minecraft ships no JDBC drivers at all
• You're on a Bukkit fork that's stripped the bundled driver (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 Using a newer engine via the public API 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:

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

// 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:

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

Probe at startup: