DarkflameServer/docs/CDClientFdb.md

CDClient: the client's cdclient.fdb

Reading rows from the fdb

ComponentsRegistry, ItemComponent and Objects read their rows from a memory-mapped copy of the client's cdclient.fdb (FdbReader, CDFdb), shared between all server processes through the OS page cache. CDServer.sqlite stays the source of truth: at load each table compares its rows in both files and reads the ids whose rows the cdserver migrations changed from SQLite (CDFdb::FindChangedKeys). Other tables read CDServer.sqlite as before.

Copies, not the client's file

No server opens the client's <res>/cdclient.fdb. Master copies it into resServer, named by the 64-bit FNV-1a hash of its bytes, and makes the matching SQLite file:

File	What
resServer/cdclient-<hash>.fdb	copy of the client's fdb; the hash is of the copy's bytes
resServer/CDServer-<hash>.sqlite	made from that copy with FdbToSqlite and every cdserver migration
resServer/cdclient-current	two lines: the fdb copy and the SQLite file every server opens
resServer/CDServer.sqlite	the file used before copies existed; still used when the pointer names it

A new version of the fdb gets new names, so nothing is replaced or truncated while a process has it mapped or open. Every file is written under a temporary name and renamed into place. Windows can't rename over or delete an open file, and the content-addressed names avoid both. The client's file is only read and never locked, since it is copied and not mapped.

On the first start with copies, master copies the fdb and points at the existing CDServer.sqlite. If the client's fdb changed while master was down, master makes the new CDServer-<hash>.sqlite at startup. Master then runs the cdserver migrations on whichever SQLite file is current, as before. Worlds read cdclient-current at startup (FdbSnapshot::Resolve). If it is missing, or names a file that isn't there, they use CDServer.sqlite without an fdb. A client with only packed files (no loose cdclient.fdb) keeps using CDServer.sqlite, and nothing is watched.

Hot reload

Master checks the client's fdb every cdclient_watch_seconds (default 5, 0 = off). It compares the size and mtime and starts a reload once they differ from the current version and have stayed the same for one poll, so a file still being copied in isn't read halfway. A reload can also be started by:

• /reloadcdclient (GM 9, paired with the cdclient_reload dashboard permission);
• a CDCLIENT_RELOAD message with no names sent to master (what /reloadcdclient sends; master also accepts it from the dashboard).

A reload runs these steps:

1. Worker thread (master): copy and hash the file. If the hash is the current one, stop. Otherwise make CDServer-<hash>.sqlite on its own SQLite connection (convert, then every cdserver migration, recorded in its migration_history), and compare the old and new copies table by table (row count and a content hash). The worker never logs or touches RakNet, the game database, the shared CDClient connection or config.
2. Main thread (master): switch master's own CDClient connection and tables, write cdclient-current, log the changed tables (for example Objects: 16012 -> 16015 rows), and send CDCLIENT_RELOAD with both names to every ready world.
3. Each world, between frames: CDClientDatabase::Reconnect opens the new SQLite file before closing the old one, and CDClientManager::Reload empties every table, maps the new copy and loads again (the changed-row lists are rebuilt). The old table entries and the old fdb view are kept alive, so objects already spawned keep what they loaded, and objects made afterwards read the new data. The world logs how long the switch took.

Master keeps the current and previous copies and removes older ones after each reload and at startup. On POSIX, a removed file that is still mapped stays readable until it is closed. On Windows the removal fails while a process maps it, and master tries again next time.

Limits

• The world reloads its cached tables on the main thread, so a reload costs about as long as the CDClient part of startup, once per reload.
• Data copied out of the tables into other caches (for example behaviors already built, or zone data read at world start) keeps the old values until those objects are made again.
• The UGC and dashboard servers don't switch on a reload yet; they read the current files when they start.
• The dashboard has no reload button yet; use /reloadcdclient or let master see the file change.
• A world that starts while master is making a new copy can read the old pointer and miss the broadcast; it catches up at the next reload or restart.