---
name: database-use
description: Any time database-related activity is required.
---

# Database use instructions

## Configuration & Standards
- **Engine**: PostgreSQL only (Port: 5433).
- **Connection string**: sourced from `.env` via `DATABASE_URL` (see `SQLALCHEMY_DATABASE_URI` / `DATABASE_URL` in `config.py`).
- **Testing DB**:
    - By default tests also use the live DB (see `pytest` note below).
    - Optional override: `TEST_DATABASE_URL` (used by `TestingConfig` in `config.py`).
- **SQLAlchemy instance**: Import `db` from `utils_db/database.py`. Do NOT create a new instance in `app.py`.
- **Scripts location**:
    - Canonical database scripts/utilities live in `utils_db/`.
    - No ad-hoc “root scripts” in the repo root.
- **Execution safety**:
    - Do NOT paste multi-line SQL or Python into the terminal.
    - Draft ad-hoc scripts in `temp/` first, then promote reusable ones into `utils_db/`.
- **Testing CSRF**: `TestingConfig` disables CSRF (`WTF_CSRF_ENABLED = False`) specifically for tests.

## Credentials
- Connection credentials: `.env`.
- Users' credentials: `.env`
    User passwords in DB are hashed. Hash is stored in the pw_hashed column.

## Structure
- Schema documentation: `.roo/docs/database_schema.md`
- SQLAlchemy model files: `models/models_*.py` (eg, `models/models_user.py`)
- SQLAlchemy database instance: `utils_db/database.py`
- Schema tools:
    - Primary: `utils_db/schema_inspector.py`
    - Supplemental: `utils_db/schema_compare.py` (writes reports to `temp/`)

## Preferred Utilities
Reuse existing tools in `utils_db/` before writing new ones:
- `utils_db/user_password_utils.py`
- `utils_db/user_management_utils.py`
- `utils_db/media_utils.py`

## Source of Truth Hierarchy
The formal Source of Truth (SoT) hierarchy for database schema information:
1) PGDB (live PostgreSQL)
2) models_*.py (SQLAlchemy) (eg, `models/models_user.py`)
3) `.roo/docs/database_schema.md` (generated)

When there is any doubt about a column, see PGDB. If a column is needed or a column name needs to change, always ask user for permission to make the add/change.

## Schema Update Workflow
When making schema or data changes, follow this workflow in order:
1) Modify PGDB
    - Make changes to the live database (see "Credentials" above).
    - When creating a script to check or change the database:
        - Do NOT paste the script into the terminal.
        - Check `utils_db/` for a suitable or near-suitable script first; reuse/extend if possible.
        - If it’s a true one-off, draft it in `temp/` first.
        - If it’s reusable, create/update a `.py` utility in `utils_db/`.
2) Update models
    - Update the appropriate SQLAlchemy model file(s) under `models/models_*.py`.
3) Regenerate documentation
    - Run: `python utils_db/schema_inspector.py generate-docs` to update `.roo/docs/database_schema.md`.
4) Log changes
    - Record the date and change in `.roo/docs/pgdb_changes.md`.

## Schema Inspector Utility
The `utils_db/schema_inspector.py` tool provides commands for schema management:
- `introspect` - Inspect live database schema and display structure
- `compare-db-models` - Compare live database against SQLAlchemy models to identify discrepancies
- `compare-models-doc` - Compare SQLAlchemy models against `.roo/docs/database_schema.md`
- `generate-docs` - Generate/update `.roo/docs/database_schema.md` from current database state
- `report` - Generate discrepancy reports under `.roo/reports/` (JSON and Markdown)
- `validate` - Verify schema documentation is up-to-date with the database

Usage notes:
- This utility uses the configured database URL (from `.env`) and initializes `db` from `utils_db/database.py`.
- Some schema comparison utilities may emit reports under `.roo/reports/` when run.

Usage examples:
- Introspect schema: `python utils_db/schema_inspector.py introspect`
- Compare: `python utils_db/schema_inspector.py compare-db-models`
- Compare models vs docs: `python utils_db/schema_inspector.py compare-models-doc`
- Generate docs: `python utils_db/schema_inspector.py generate-docs`
- Validate docs: `python utils_db/schema_inspector.py validate`

## Testing
- Run tests with `pytest` against the live PostgreSQL database.
- In `TestingConfig` (`config.py`), CSRF is disabled (`WTF_CSRF_ENABLED = False`).