Database Initialization

Relevant source files

The following files were used as context for generating this wiki page:

• database/init_db.py
• app.py
• models/team.py
• models/submission.py
• README.md
• admin_reset.py

Database Initialization in the Debug Arena project encompasses the setup, configuration, and schema creation for the platform's persistent storage. The system utilizes SQLAlchemy as an ORM to manage data for teams and their respective submissions, supporting both SQLite for development and PostgreSQL for production environments.

The initialization process ensures that the physical storage directory exists, establishes the connection string based on the environment, and executes the creation of all defined database tables within the Flask application context. This ensures a consistent state for Authentication and Scoring systems.
Sources: app.py:20-30, database/init_db.py:10-20, README.md:65-72

Core Configuration and Environment Setup

The database configuration is managed within the primary application entry point, where the SQLALCHEMY_DATABASE_URI is determined by environment variables or local fallbacks. The system defaults to an instance/db.sqlite3 file for local development.

Database Connection Logic

The application uses the basedir to locate the project root and ensures an instance folder exists to prevent file system errors during SQLite database creation.
Sources: app.py:11-38

Parameter	Type	Default Value	Description
SECRET_KEY	String	dev-key-123	Used for session encryption.
SQLALCHEMY_DATABASE_URI	String	sqlite:///instance/db.sqlite3	Connection string for the database engine.
SQLALCHEMY_TRACK_MODIFICATIONS	Boolean	False	Disables overhead of tracking object modifications.

Sources: app.py:20-32

Database Schema and Models

The database architecture is defined through two primary models: Team and Submission. These models define the structure of the tables created during initialization.

Entity Relationship Structure

The Team entity serves as the primary participant record, while the Submission entity tracks individual level attempts and scores.

The diagram shows the one-to-many relationship between teams and their code submissions.
Sources: models/team.py:5-24, models/submission.py:4-16

Execution Flow

The initialization can be triggered in two ways: automatically when the Flask app starts, or manually via a dedicated utility script.

Initialization Sequence

1. Path Resolution: The script identifies the project root and adds it to sys.path.
2. Directory Creation: Ensures the database/ or instance/ directory exists on the host system.
3. Application Context: The initialization occurs within the app.app_context() to allow SQLAlchemy to access the configuration.
4. Schema Creation: db.create_all() is invoked to generate tables based on the imported models.

Implementation Snippet

The following logic from database/init_db.py demonstrates the manual initialization process:

# database/init_db.py:14-20
# Ensure database directory exists
DB_DIR = os.path.join(PROJECT_ROOT, "database")
os.makedirs(DB_DIR, exist_ok=True)

with app.app_context():
    db.create_all()
    print("✅ Database initialized successfully at database/db.sqlite3")

Sources: database/init_db.py:14-20

Administrative Utilities

Beyond initial creation, the system provides administrative hooks to interact with the database directly for management tasks. For example, admin_reset.py allows for manual updates to team status in the database.

• Team Reinstatement: Resets the violations counter for a specific team in the team table.
• Context Management: Like the initialization script, administrative tools must run within the app.app_context() to perform db.session.commit().

Sources: admin_reset.py:5-20

Summary

Database initialization in Debug Arena is a foundational process that leverages SQLAlchemy to abstract the underlying storage engine (SQLite/PostgreSQL). By providing both automated setup within app.py and a dedicated init_db.py script, the project ensures the persistence layer is robustly configured and the schema is correctly applied before any competitive sessions begin.