SkStorage

This is my 5th time drafting this documentation, please forgive me, I forgot to format it. SkStorage is a Skript variable-storage backend. Drop-in replacement for the SQLibrary plugin that Skript ships with by default. SQLibrary was last released in 2013. It uses rollback-journal SQLite (no WAL), one giant monolithic variables.db, and ships zero PRAGMAs. On a server with hundreds of online players writing constantly, you get "variables cannot be saved at sufficient speed" warnings and slow startup. SkStorage replaces that with three storage scopes routed automatically by variable name shape. Persistent scope handles cross-player queryable data like leaderboards and economy, stored in one file with dict-encoding so repeated names take 60 to 70 percent less space. Player scope keeps each player's data in a separate file at player//.db, opened on join and closed on quit. Server scope holds global state with the sf:: prefix. Anything not matched stays in Skript's RAM and surfaces stray names that should have been caught. Every connection runs in WAL mode with synchronous=NORMAL, mmap, page cache, and busy timeout properly set. Writes are batched into transactions flushed every 200 milliseconds, which cuts fsync overhead by roughly two orders of magnitude. Player files are lazy-loaded on PlayerJoinEvent. There is no multi-minute boot hang on a 500MB+ database. After boot, a paced background loader drips offline players into Skript's RAM so cross-player loops still work for offline data. The loader is throttled and walks biggest files first, so heavy players hit memory in seconds and lightweight files come last. Player metadata is auto-tracked in playerdata.db without any script involvement: uuid, name, name history, first and last join, last quit, total playtime, total sessions, last world, and head texture data pulled from the player's already-authenticated Paper profile (zero Mojang API calls, no rate limits). Optional HMAC-SHA256 hashed last IP for alt-detection, off by default. Tiny per-player files can be auto-discarded on quit and on boot. A bare- schema file is about 20KB. With auto_discard_on_leave_kb set to 24, a player who joins once and never returns has their file cleaned up automatically. Their identity in playerdata.db is preserved either way. A migration tool reads SQLibrary's variables21 schema and writes directly to the scope files, async on a worker thread so the main server thread keeps ticking. It tolerates SQLITE_CORRUPT in the source: salvages up to the bad page and reports partial success with instructions to recover the rest via sqlite3 .recover. PlotSquared integration subscribes to PostPlotDeleteEvent (Guava EventBus, not Bukkit events) and sweeps server.db for variables containing the deleted plot's world name or plot ID. Off by default, soft-dependency on PlotSquared. Useful for cleaning up plant data, hooks, plot shops, and similar location-keyed state when a plot is wiped. Season reset wipes seasonal scopes (server.db and every player file) and leaves persistent.db and playerdata.db alone. Confirmation flow uses a single-use token that expires after 60 seconds. REQUIREMENTS Paper 1.21 or newer, Skript 2.15.0 or newer, Java 21 or newer. INSTALL Drop SkStorage-x.y.z.jar into plugins/ and restart once. Default config gets written to plugins/SkStorage/config.yml. Open Skript's config.sk and find the databases section. Replace the existing default block with these three entries (keep your original default block but set its type to disabled, as a rollback option): persistent: type: skstorage-persistent pattern: .* file: ./plugins/SkStorage/persistent.db backup interval: 6 hours backups to keep: 8 monitor changes: false monitor interval: 20 seconds player: type: skstorage-player pattern: .* directory: ./plugins/SkStorage/player backup interval: 0 backups to keep: -1 monitor changes: false monitor interval: 20 seconds server: type: skstorage-server pattern: .* file: ./plugins/SkStorage/server.db backup interval: 6 hours backups to keep: 8 monitor changes: false monitor interval: 20 seconds Restart and watch the log for "Registered Skript storage types". If you have existing data in SQLibrary's variables.db, run a dry-run first to see how rows would be routed: /skstorage migrate sqlibrary ./plugins/Skript/variables.db --dry-run Look at the routing report. If you have variables that show up as UNROUTED that you want to keep, either add patterns to the persistent allowlist in plugins/SkStorage/config.yml, or set server.legacy_fallthrough to true (which makes server.db catch every unclaimed name, the way the old SQLibrary default did). Then run the live migration: /skstorage migrate sqlibrary ./plugins/Skript/variables.db --i-have-backed-up After a week of stable operation, delete the SQLibrary jar from plugins/ and the old variables.db. SkStorage has no SQLibrary dependency. If anything breaks during the migration window, change the skstorage-* types in Skript's config.sk back to disabled and re-enable your original SQLibrary block. Your old variables.db was never modified by SkStorage, it's intact.