Skip to content

Configuration and Database

Jump to bottom
coayo-x edited this page Mar 15, 2026 · 1 revision

Configuration and Database

Configuration overview

This project uses config.py as the central configuration layer.

config.py loads environment variables at import time. The current documented configuration surface includes:

  • DB_PATH
  • ROTATION_INTERVAL
  • DISPLAY_BRIGHTNESS

Example .env file:

DB_PATH=content.db
ROTATION_INTERVAL=300
DISPLAY_BRIGHTNESS=0.7

If .env does not exist, the application still runs using default values from config.py.

Important configuration notes

  • Configuration values are loaded once at import time.
  • Changing .env while the app is already running does not update the running process.
  • ROTATION_INTERVAL is intended for slot timing configuration.
  • DISPLAY_BRIGHTNESS exists in config, but current documentation notes that it is not fully wired into matrix output yet.

Database overview

The project uses SQLite for runtime state.

The database file is controlled by:

DB_PATH

By default, it points to:

content.db

The database is runtime state, not source code. The app depends on SQLite state for daily Pokémon rotation, joke deduplication, and slot-stable joke and science selection.

Automatic initialization

The schema is created and patched by db_manager.init_db(). There is still no real migration framework. Existing databases are updated by checking column existence and issuing ALTER TABLE ... ADD COLUMN ... when needed.

The database is initialized automatically when the app connects to the configured DB path. This allows a fresh clone or deployment to create the DB file automatically without manual schema setup.

Active tables

The current documented active tables are:

  • meta
  • system_state
  • pokemon_rotation
  • used_jokes

Legacy tables still created but unused by current runtime:

  • category_rotation
  • jokes_rotation

Do not build new features on the legacy tables unless you intentionally revive that older design.

Runtime file rules

Database files should not be committed to Git. The project now treats content.db as runtime data, not a tracked repository artifact.

Useful ignore entries include:

  • .env
  • content.db
  • *.db
  • SQLite sidecars such as content.db-wal and content.db-shm

The current bug audit still warns that runtime artifacts may not be fully ignored in all cases, especially preview outputs and SQLite sidecar files.

Current limitations

The database layer is better than before, but not perfect:

  • it still uses add-column checks rather than real ordered migrations
  • Pokémon, joke, and science state are still coupled together in one wide singleton row
  • replacing a DB file at the same path during a running process can confuse initialization caching until the process restarts

Use the database as runtime storage, not as a source-controlled artifact.

Raspberry Pi LED Matrix

Built with caffeine, stubbornness, and way too many test runs on a Raspberry Pi.

This project was created as a learning space for exploring Python, APIs, Raspberry Pi hardware, and real development workflows.
Yes, it is “just” an LED matrix project.
No, that does not mean you should edit rotation_engine.py blindly and summon chaos.

If you are new here, start with Getting Started and Developer Guide.
If you want to understand how the project works, read Architecture.
If something breaks, check Troubleshooting before inventing new bugs.

If you are a student contributor:

Created and maintained by coayo-x

Wiki

Clone this wiki locally