TDGroupe with a database and several servers
Mod version shipped with FlammiCraft: 0.29.0
From version 0.23.0, TDGroupe can store groups, ranks, invitations, titles and active time in MariaDB instead of the world folder. Several backend servers of a cluster then share the same state. Without a database, everything stays in the world as before.
Switch on the database
From version 0.26.0 TDGroupe has no database setting of its own. A dedicated server stores in MariaDB as soon as [database] enabled = true is set in config/tdlibrary-database.toml. That file also holds the connection (host, port, database, user, password, TLS) and migration_conflicts: REFUSE stops the first database start when the database already holds different data, KEEP_DATABASE keeps the database copy. TDGroupe reads changes of other backends every [cluster] poll_millis. Single-player worlds always store in data/tdgroupe.dat and data/tdgroupe_titles.dat. The tables start with tdgroupe_ and are created on the first start. An old config/tdgroupe-database.toml is no longer read and can be deleted.
For several backends, enable [cluster] in tdlibrary-database.toml on each backend. Give each server root a cluster-node.toml with its unique id and owned_dimensions. TDGroupe 0.27.0 requires TDLibrary 0.68.0 and matching TDGroupe client and server builds.
From 0.28.0 TDGroupe borrows its database connection from TDLibrary's shared pool and requires TDLibrary 0.74.0 or newer. A change that waits more than three seconds for a row another server holds locked fails with an error and can be tried again; the connection stays usable.
TDGroupe reserves the backend ID world for imported active time. On the first database start, title rules from the server configuration fill a missing rules document even in a fresh world.
What is shared
- Groups, members, roles, colors, names, player profiles, global ranks and their assignments.
- Invitations and pending group notifications. In a cluster, one elected backend offers confirmed group notice revisions to TDLibrary regardless of where the recipient is playing. TDLibrary queues the handoff and archives it before sending a live hint. The inbox, read status and presentation settings follow the player across backends.
- Title ownership, selection, revocation blocks and the unlock rules from the title editor.
- The group member limit, lifetime of new invitations, public group tags and the inactive time threshold for title progress. Edit them with
/tdgroupe config. Existing invitation deadlines are kept. - Active time. Each backend counts only the players currently playing on it, into a row of its own. The sum of all rows is the active time, so changing servers never counts a second twice or loses one.
- Private group chat, waypoints and online status reach members on other backends.
- Waystones team sharing uses the shared group state.
Title purchases still go through TDEconomy, without a fixed version requirement. Once unlocked, a title is stored in the database and applies on every backend, even when TDEconomy's quest or purchase records exist on only one backend.
Worlds, waypoints and maps
Set a stable world_id and explicit owned_dimensions in cluster-node.toml for clusters with several worlds. Two Overworlds need distinct IDs. A waypoint link identifies its world and dimension. Open it on the backend serving that route. Without an explicit route, the link uses the ID in the world's data/tdgroupe_world_id.txt.
Map files stay in tdgroupe-maps on the backend serving the dimension. On the first successful database-mode load, TDGroupe binds the active dataset to the save's data/tdgroupe_world_id.txt. Back up this file and the map archive together. When moving a world, keep both and preserve its configured world_id. For an unrelated or reset world, use a fresh map dataset and world identity, as described in the map archive reference. If the archive belongs to another world, TDGroupe logs the mismatch and leaves map sync disabled. Restore the matching files or select the correct dataset.
First switch
Use a copy of the world and an empty test database first, not the production database.
- Stop the server, enter the connection in
tdlibrary-database.tomland set[database] enabled = true. - Start the server. On the first start with existing world files, TDGroupe copies
data/tdgroupe.datanddata/tdgroupe_titles.dattotdgroupe-migration-backups/<timestamp>/, validates them completely and imports them. Only then does it remove the world files and write the markerdata/tdgroupe_database.json. - A database document that matches the world is left unchanged. A differing one stops the start under
REFUSEbefore anything is written. Active time from the world goes into theworldrow; importing the same world twice does not count it twice. - In a cluster, switch the backend holding the existing data first (previously backend A), then the others with fresh or matching worlds.
A world carrying the marker refuses to start in WORLD mode, so it never runs on silently empty groups. If world files appear again despite the marker, the server also refuses to start until one of them is removed deliberately.
A server in DATABASE mode does not start without a reachable database.
When upgrading an existing cluster, stop the old backends and start the upgraded backend with the intended group settings first. Its server configuration seeds the new group_rules document. Start the other upgraded backends with their original world directories so TDLibrary can import existing notification archives and pending writes. In database mode, /tdgroupe config changes the shared settings and reload requests a database refresh. Use /tdgroupe storage status to check pending writes and conflicts.
Operation and outages
Changes apply immediately on the local backend and are written in the background. Every document has a revision. When another backend wrote first, TDGroupe merges the local change onto the newer state: changes to different groups or players are both kept. When two backends change the same group, or the titles of the same player, at the same time, the state written first wins. If merging would break a rule, such as two groups with the same name, the database state applies completely.
Other backends read a change feed without gaps. If entries are missing because a backend could not read for too long, it reloads the complete state.
While the database is unreachable during play, TDGroupe refuses group and title changes by players with a message. Changes already made locally and active time are written once the database answers again. On shutdown, the server waits briefly for pending writes.
Active time is written every 30 seconds and on logout. A crash loses at most the last 30 seconds counted by the crashed backend.
Operator commands
/tdgroupe storage statusshows the mode, backend, database state, change feed position, revisions, pending changes and the number of conflicts and fallbacks./tdgroupe storage exportwrites the shared state in world format totdgroupe-export/<timestamp>/(tdgroupe.dat,tdgroupe_titles.datwith summed active time, andtitle-rules.json).
Returning to world storage
- Run
/tdgroupe storage exportand stop the server. - Copy the exported files into
data/and deletedata/tdgroupe_database.json. - Copy the exported settings from
title-rules.jsonintoserverconfig/tdgroupe-server.toml. The three group settings go at the top level.idleSecondsand the title rules go under[titles]. - Set
[database] enabled = falseintdlibrary-database.tomland start. This applies to every TD mod on this server.
Acceptance
Source tests cover settings initialization and conflicts, an invitation accepted on a second backend and synced to a third, and world and map archive separation. On a test cluster, invite a player while they are offline, then connect them on a different backend. Check that the inbox and invitation action work there, then transfer again and check membership and read state. Repeat while switching during delivery. Test two Overworlds with distinct routes and check that a link cannot open in the other world.