TinyMUX

Database Persistence

Softcode

Database Persistence

A MUSH server’s database contains every object, attribute, flag, lock, and timestamp in the game. This data must survive server restarts, crashes, and hardware failures. Understanding how persistence works is essential for server administration.

The Database

The database is an in-memory structure holding all objects (rooms, exits, things, players) and their attributes. Each object is identified by a dbref (database reference number). The database grows as objects are created and shrinks as destroyed objects are recycled.

Checkpoints and @dump

The server periodically writes the database to disk. This is called a checkpoint or dump. By default, TinyMUX checkpoints every 3600 seconds (one hour), configurable via dump_interval.

The @dump command triggers an immediate checkpoint. Players see configurable messages when a dump begins and ends (set via dump_msg and postdump_msg).

Forking Dumps

On Unix systems, TinyMUX can fork a child process to write the checkpoint while the game continues running. This avoids the “freeze” that players experience during a synchronous dump on large databases.

The forked child inherits a copy-on-write snapshot of the database. The parent process continues accepting commands. When the child finishes writing, it exits and the parent is notified.

This is controlled by the fork_dump configuration option.

Flatfiles

A flatfile is a portable text representation of the database. It contains every object and attribute in a format that can be loaded by dbconvert or another server.

@dump/flatfile

Flatfiles are the standard interchange format between MUSH servers and versions. They are also the safest form of backup because they are human-readable and not tied to a specific binary format.

The dbconvert utility converts between binary and flatfile formats:

./dbconvert -d data/netmux.dir data/netmux.db > backup.flat   # dump
./dbconvert -l data/netmux.dir data/netmux.db < backup.flat   # load

Database Epochs

TinyMUX tracks a database epoch – a counter incremented with each checkpoint. Checkpoint files are named with the epoch number (e.g., netmux.db.#42#). This prevents a crash during a dump from corrupting the previous good checkpoint.

Crash Recovery

If the server crashes, it restarts from the most recent checkpoint. Any changes made between the last checkpoint and the crash are lost. This is why frequent dumps are important for active games.

TinyMUX also supports panic dumps: if the server detects an unrecoverable error, it attempts to write a flatfile before exiting. This is a last-resort mechanism and may not always succeed.

Startup Sequence

When the server starts:

  1. The binary database is loaded (or a flatfile is loaded via dbconvert).
  2. Database consistency checks run (@dbck).
  3. STARTUP attributes on objects are executed.
  4. The game begins accepting connections.

@dbck

The @dbck command runs consistency checks on the database: verifying that all object references are valid, that location/contents chains are consistent, and that no objects are in impossible states. It runs automatically at startup and can be run manually.

Backup Strategy

The recommended backup strategy is:

  1. Enable forking dumps to minimize player impact.
  2. Set dump_interval appropriate to your game’s activity level.
  3. Periodically run @dump/flatfile and copy the flatfile offsite.
  4. Keep multiple generations of backups.
  5. Test restoring from flatfile periodically.

Flatfiles are portable across server versions and even across different MUSH server families (with conversion tools like Omega).

Related Topics: @dump, @dbck, Flatfile, Backups.