Database Drivers (Postgres/Mongo/JSON)
Relevant source files
The following files were used as context for generating this wiki page:
The Red Discord Bot utilizes a modular storage system that supports multiple database backends through driver implementations. These drivers manage how data for the core bot and individual cogs is stored, retrieved, and cleared across different storage technologies such as JSON files, MongoDB, and PostgreSQL.
Each driver inherits from a BaseDriver class and implements standardized methods for data manipulation, ensuring the bot remains agnostic of the underlying storage engine. The system supports structured data storage for various scopes, including global, guild, member, user, and channel settings.
Sources: redbot/core/_drivers/_mongo.py:27-31, redbot/core/core_commands.py:2287-2292, redbot/core/_debuginfo.py:166-166
MongoDB Driver Implementation
The MongoDriver manages data storage using MongoDB and the motor asynchronous driver. It organizes data into collections based on the cog name and category identifiers provided by the bot's configuration system.
Data Structure and Keys
The driver uses a specific _id structure to maintain uniqueness across different bot instances and data scopes. Each document in a MongoDB collection contains a RED_uuid for instance identification and a RED_primary_key representing the specific data scope (e.g., Guild ID or User ID).
The diagram shows the logical relationship between collections and documents within the MongoDB driver.
Sources: redbot/core/_drivers/_mongo.py:126-129, redbot/core/_drivers/_mongo.py:206-218
Key Features
| Feature | Description |
|---|---|
| URI Schemes | Supports mongodb and mongodb+srv connection strings. |
| Atomic Operations | Uses transactions for multi-document updates where supported by the DB version. |
| Key Escaping | Escapes special characters like . and $ to ensure compatibility with BSON keys. |
| Bulk Operations | Implements bulk_write for non-transactional environments to improve performance. |
Sources: redbot/core/_drivers/_mongo.py:44-59, redbot/core/_drivers/_mongo.py:155-199, redbot/core/_drivers/_mongo.py:302-315
SQL Support and Schema Management
While the bot uses generalized drivers for configuration, specific modules like Audio utilize raw SQL for complex data requirements such as playlist management and caching.
SQL Statement Definitions
SQL statements are defined as constants and executed against the underlying database (typically SQLite or PostgreSQL depending on the driver in use). The system handles table creation, indexing, and upsert logic.
Data flow for initialization and operation of SQL-based storage in the Audio cog.
Sources: redbot/cogs/audio/sql_statements.py:108-161, redbot/cogs/audio/sql_statements.py:189-222
Data Deletion and Privacy
Drivers implement specific logic to handle Discord data deletion requests. For SQL-based storage, this involves multi-step transactions to update or delete records associated with a specific user_id.
Sources: redbot/cogs/audio/sql_statements.py:90-106
Data Migration Utilities
The bot includes mechanisms to migrate data between schema versions. These utilities are critical when the underlying data structure of a cog changes.
Schema Migration Logic
- The cog checks the current
schema_versionagainst the target version. - If the versions differ, the cog extracts data from the old structure (e.g., from guild Config).
- The data is transformed and saved to the new structure (e.g., custom scopes or specific database tables).
- The
schema_versionis updated in the configuration.
Sources: redbot/cogs/audio/core/utilities/miscellaneous.py:270-327
Driver Selection and Configuration
Users configure the storage backend during the initial bot setup. The data_manager tracks the selected storage_type and provides this information for debugging and core operations.
Configuration Parameters
| Parameter | Driver Support | Description |
|---|---|---|
| HOST | Mongo/Postgres | The database server address. |
| PORT | Mongo/Postgres | The connection port (use 0 for default). |
| USERNAME | Mongo/Postgres | Authentication username. |
| PASSWORD | Mongo/Postgres | Authentication password. |
| DB_NAME | Mongo/Postgres | The specific database instance name. |
Sources: redbot/core/_drivers/_mongo.py:73-89, redbot/core/_debuginfo.py:166-166
Conclusion
The database driver system provides a flexible abstraction layer for Red Discord Bot. By implementing standardized interfaces for JSON, MongoDB, and PostgreSQL, it allows the bot to scale from small personal instances using flat files to large-scale deployments requiring high-performance database clusters. The inclusion of SQL statement management and migration utilities ensures data integrity and user privacy across all supported backends.