Database Architecture & ezdb
Relevant source files
The following files were used as context for generating this wiki page:
The BandaStation database architecture provides a persistent storage layer for game state, player metrics, administrative logs, and whitelists. It utilizes a MySQL/MariaDB backend using the InnoDB engine to ensure data integrity and support complex relationships between players, rounds, and game events.
The system tracks diverse data including player playtime, administrative actions, bans, and specific game module statistics like minesweeper scores. Developers manage the schema through a versioned changelog system, ensuring that updates are applied sequentially across different server environments.
Sources: SQL/bandastation/database_changelog.md:1-10, config/config.txt:30-40
Schema Versioning and Management
The database uses a major and minor versioning system to track schema changes. You must increment the minor number for general changes and the major number for significant architectural shifts. Both values support a range up to 255.
Version Tracking Tables
The project uses specific tables to track the current schema state. Depending on the server configuration, these may use a 220 suffix or an SS13_ prefix.
| Table Name | Purpose | Key Fields |
|---|---|---|
schema_revision_220 | Tracks BandaStation specific schema updates | major, minor, date |
SS13_schema_revision | Tracks standard prefixed schema updates | major, minor, date |
schema_revision | Base tracking table for non-prefixed schemas | major, minor, date |
Sources: SQL/bandastation/database_changelog.md:1-12, SQL/bandastation/bandastation_update.sql:4-10, SQL/tgstation_schema_prefixed.sql:438-444
Update Procedure
When modifying schema files, you must:
- Update the SQL definition in the relevant
.sqlfile. - Update
DB_MAJOR_VERSION_220andDB_MINOR_VERSION_220in the DM defines. - Insert a new record into the
schema_revision_220table.
-- Example update for version 1.3
INSERT INTO `schema_revision_220` (`major`, `minor`) VALUES (1, 3);
Sources: SQL/bandastation/database_changelog.md:3-9
Core Data Structures
Player and Identity Management
The player table serves as the primary registry for users, linking ckey (unique BYOND ID) to connection metadata.
The relationship between players and their activities is tracked across multiple specialized tables.
Sources: SQL/tgstation_schema.sql:356-373, SQL/tgstation_schema.sql:337-343
Administrative and Whitelist Systems
BandaStation implements a robust whitelist and admin management system to control server access and permissions.
- ckey_whitelist: Stores temporary or permanent access grants for specific ports.
- admin_wl: Manages administrative ranks, levels, and permission flags.
- admin_prime: A specific table for high-level administrative feedback and ranking.
Sources: SQL/bandastation/bandastation_update.sql:13-39
Game Statistics and Logging
Round and Event Tracking
The round table acts as a central hub for round-specific data, including start times, map names, and game results. Other logs (death, connection, admin) reference the round_id.
This structure allows for post-round analysis and historical data retrieval for any specific game session.
Sources: SQL/tgstation_schema.sql:415-433, SQL/tgstation_schema.sql:35-46, SQL/tgstation_schema.sql:518-535
Specialized Feature Tables
BandaStation includes tables for specific game features:
- minesweeper: Tracks player performance in the in-game minesweeper module, including
points_per_sec,bombs, andtime. - budget: Manages financial data or credit sources, often linked to
discord_id. - achievements: Stores persistent player progress and metadata for awards.
Sources: SQL/bandastation/database_changelog.md:16-43, SQL/tgstation_schema.sql:484-500
Configuration and Integration
Database behavior is controlled via the config/config.txt file, which includes dbconfig.txt.
Key Configuration Options
| Option | Description |
|---|---|
ADMIN_LEGACY_SYSTEM | If enabled, uses admins.txt instead of the SQL system |
USE_AGE_RESTRICTION_FOR_JOBS | Requires SQL to check player age before allowing certain roles |
USE_EXP_TRACKING | Enables playtime tracking in the role_time table |
PANIC_BUNKER | Uses SQL history to deny connections from unknown ckeys |
Sources: config/config.txt:30-40, config/config.txt:55-65, config/config.txt:460-475
Conclusion
The Database Architecture & ezdb system provides the backbone for BandaStation's persistence. By combining standard SS13 schema elements with custom BandaStation tables like ckey_whitelist and minesweeper, the architecture supports both administrative control and deep player engagement tracking. The versioned changelog system ensures that these complex data structures remain synchronized across development and production environments.