Configuring SQLite API

SqliteModule requires at least one argument, but optionally takes two:

fileName: The String fileName argument tells the SQLite API what the SQLite DB should be named when it's written to disk. The SQLite API automatically creates this in your plugin's data folder, and should include the .db file extension.
config: The SqliteConfig config argument tells Java's SQLite Driver how to configure and use the DB. It also includes configuration for the built-in SqliteCache, which we'll read more about later.
An alternate constructor exists which replaces the SqliteConfig config argument with Function <BytePluginConfig, SqliteConfig> configFactory. This allows you to define a function that can access your BytePluginConfig to configure SQLite via a configuration file.
An example of using this is if you want to allow server administrators to tweak DB cache or other behaviors.

Basic usage

            // An example providing a concrete configuration
            new SqliteModule("data.db", SqliteConfig.defaults());
        

            // An example providing a lambda which allows configuration of the module at runtime.
            new SqliteModule("data.db", byteConfig -> {
                SqliteConfig base = SqliteConfig.defaults();
                return new SqliteConfig(
                    true,
                    "WAL",
                    "NORMAL",
                    5000,
                    // Configure mainThreadTimeout timeout via config
                    java.time.Duration.ofMillis(byteConfig.config().getInt("main-thread-timeout")),
                    SqliteConfig.MainThreadPolicy.WARN,
                    SqliteConfig.TimeoutBehavior.THROW,
                    java.time.Duration.ofMillis(10),
                    base.cache()
                );
            });

`SqliteConfig` options

foreignKeys (boolean)

Controls PRAGMA foreign_keys=ON.
Values: true, false.
Default: true.

journalMode (String)

Passed directly to PRAGMA journal_mode=<value>.
The library does not validate this value.
Common SQLite values: WAL, DELETE, TRUNCATE, PERSIST, MEMORY, OFF.
Default: "WAL".

synchronous (String)

Passed directly to PRAGMA synchronous=<value>.
The library does not validate this value.
Common SQLite values: OFF, NORMAL, FULL, EXTRA (or numeric 0 - 3).
Default: "NORMAL".

busyTimeoutMs (int)

Passed to PRAGMA busy_timeout=<value>.
Unit: milliseconds.
Default: 5000.

mainThreadTimeout (Duration)

Timeout applied to blocking DB calls made on the Bukkit main thread.
null, zero, or negative disables timeout behavior for main-thread calls.
Default: Duration.ofMillis(20).

mainThreadPolicy (MainThreadPolicy)

Controls what happens when DB calls are made on the main thread.
Values:
- ALLOW: permit silently
- WARN: permit and allow slow-call warnings
- DISALLOW: throw DbMainThreadDisallowedException
Default: WARN.

timeoutBehavior (TimeoutBehavior)

Controls behavior when a main-thread call exceeds mainThreadTimeout.
Values:
- FAIL_OPEN: return fallback result (null; query wrappers convert to empty list)
- FAIL_CLOSED: throw DbTimeoutException
- THROW: throw DbTimeoutException
Default: THROW.

slowQueryWarnThreshold (Duration)

Used only when mainThreadPolicy == WARN.
If the elapsed main-thread DB call time is greater than or equal to this threshold, a warning is logged.
null, zero, or negative disables slow-query warning logs.
Default: Duration.ofMillis(10).

cache (SqliteConfig.CacheConfig)

Query result cache settings.
Default: SqliteConfig.CacheConfig.defaults().

`CacheConfig` options

ttl (Duration)

Time-to-live for cache entries.
null, zero, or negative means entries do not expire by TTL.
Default: Duration.ofSeconds(30).

refreshAfter (Duration)

Age after which reads may trigger background refresh.
null, zero, or negative disables refresh-after behavior.
Default: Duration.ofSeconds(10).

serveStaleWhileRefreshing (boolean)

If true, stale entries can be served while a refresh is running.
Values: true, false.
Default: true.

maxSize (int)

Maximum number of cached query keys.
Special values:
- 0: disable cache
- -1: unlimited cache size
- < -1: disable cache
Default: 50000.

Defaults snapshot

            SqliteConfig.defaults();
            // foreignKeys=true
            // journalMode="WAL"
            // synchronous="NORMAL"
            // busyTimeoutMs=5000
            // mainThreadTimeout=Duration.ofMillis(20)
            // mainThreadPolicy=MainThreadPolicy.WARN
            // timeoutBehavior=TimeoutBehavior.THROW
            // slowQueryWarnThreshold=Duration.ofMillis(10)
            // cache=CacheConfig.defaults()
            CacheConfig.defaults();
            // ttl=Duration.ofSeconds(30)
            // refreshAfter=Duration.ofSeconds(10)
            // serveStaleWhileRefreshing=true
            // maxSize=50_000
        

11 March 2026