DUXPLIMA Documentation

Overview

Choosing a backend, the database settings, the tables, and the one-server rule.

uxmClaims stores claims and player records in SQLite, MySQL or PostgreSQL. It creates and updates its own tables at startup, then loads every claim into memory and serves reads from there.

Settings

database:
  type: 'AUTO'
  username: 'root'
  password: 'password'
  url: 'jdbc:sqlite:./plugins/uxmClaims/data/claims.db'
KeyDefaultMeaning
typeAUTOAUTO, SQLITE, MYSQL or POSTGRES
usernamerootDatabase user, used by MySQL and PostgreSQL only
passwordpasswordIts password, used by MySQL and PostgreSQL only
urljdbc:sqlite:./plugins/uxmClaims/data/claims.dbThe JDBC URL

AUTO looks for mysql, postgres or sqlite in the URL, in that order, and refuses to start if it finds none. The drivers and the HikariCP pool are bundled. The pool holds up to 64 connections and has no settings of its own.

The whole section is read once, at startup. /claim reload re-reads config.yml but keeps the connection it has: changing the backend or the credentials needs a restart.

BackendRight for
SQLiteMost servers. The default, a single local file, no setup
MySQLA database you already run and back up centrally, or query from a web panel
PostgreSQLThe same, where PostgreSQL is the house standard

MySQL 8.0 or newer and PostgreSQL 13 or newer are supported.

One server per database

Claims are cached in memory and the write locks are local to one server, so two servers writing to the same database would silently overwrite each other. On MySQL and PostgreSQL the plugin therefore holds a lease: a single row in uxmclaims_server_lease naming the server that owns the data.

SituationResult
The lease is free, or held by this same serverThe server takes it and starts
Another live server holds itThe plugin logs Another server (…) is already using this database. and disables itself
The holder stopped cleanlyThe lease is released at shutdown; the next server starts at once
The holder crashedIts lease is taken over once its heartbeat is 60 seconds old
The lease is taken over while this server runsThe plugin logs it and disables itself

The holder renews the lease every 20 seconds. A server is identified by the id in plugins/uxmClaims/data/server.id plus its port, so a restarted server takes its own lease back immediately. Copying the plugin folder to a second server copies that id too: delete data/server.id on the copy. SQLite needs no lease, because the file is local.

To run claims on several servers, give each server its own database.

Tables

Every table has the prefix uxmclaims_.

TableHolds
playersPlayer name, skin and login dates
claimsName, spawn, creation and expiry dates
claim_chunksThe chunks of each claim
claim_flagsThe flags set on each claim
claim_membersMembers and their role
claim_member_allowed_permissions / claim_member_denied_permissionsPer-member overrides
claim_roles / claim_role_permissionsRoles and their permissions
claim_invites / claim_bansPending invites and bans
claim_warpsWarps, unique per claim and name
claim_blocksThe claim block style and position
claim_vaults / claim_vault_itemsVault contents
server_leaseThe lease row (MySQL and PostgreSQL)

Two views, uxmclaims_view_claims_json and uxmclaims_view_players_json, return each claim and player as one JSON document, which is the easiest way to read the data from outside the game.

Migrations

The schema is versioned by the files under migrations/<backend>/ in the plugin jar, and every start applies the versions the database has not seen. Each version runs in one transaction.

VersionChange
v1The tables and the two views
v2Removes two retired flags
v3Makes warp names unique per claim instead of server-wide
v4Splits member permissions into allowed and denied tables
v5Adds uxmclaims_server_lease
v6Grants USE_WARPS once to every MEMBER and CUSTOM role, so members keep private warp access; owners can remove it afterwards

Applied versions are recorded in schema_migrations with a checksum. Do not edit that table or the schema by hand: a checksum that no longer matches stops the plugin at startup.

Moving between backends

There is no migration command. Changing the URL points the plugin at an empty database; the claims do not follow. To move, export from the old database and import into the new one with your database's own tools, with the server stopped.

A new URL is an empty database

Pointing url at a fresh database means every player's claims are gone until you point it back. Take a copy of data/claims.db, or a dump, before touching this section on a live server.

Backups

BackendBackup
SQLitesqlite3 plugins/uxmClaims/data/claims.db ".backup 'claims-backup.db'", safe while running
MySQLmysqldump -u uxmclaims -p uxmclaims > backup.sql
PostgreSQLpg_dump -U uxmclaims uxmclaims > backup.sql

Take one before any /claim admin bulk … command: they change every loaded claim, without confirmation and without undo.

Related: SQLite, MySQL, PostgreSQL, config.yml