calminer/docs/logging_audit.md

Setup Script Logging Audit (2025-10-25)

The following observations capture current logging behaviour in scripts/setup_database.py and highlight areas requiring improved error handling and messaging.

Connection Validation

• validate_admin_connection and validate_application_connection log entry/exit messages and raise RuntimeError with context if connection fails. This coverage is sufficient.
• ensure_database logs creation states but does not surface connection or SQL exceptions beyond the initial connection acquisition. When the inner cursor.execute calls fail, the exceptions bubble without contextual logging.

Migration Runner

• Lists pending migrations and logs each application attempt.
• When the baseline is pending, the script logs whether it is a dry-run or live application and records legacy file marking. However, if _apply_migration_file raises an exception, the caller re-raises after logging the failure; there is no wrapping message guiding users toward manual cleanup.
• Legacy migration marking happens silently (just info logs). Failures during the insert into schema_migrations would currently propagate without added guidance.

Seeding Workflow

• seed_baseline_data announces each seeding phase and skips verification in dry-run mode with a log breadcrumb.
• _verify_seeded_data warns about missing currencies/units and inactive defaults but does not raise errors, meaning CI can pass while the database is incomplete. There is no explicit log when verification succeeds.
• _seed_units logs when the measurement_unit table is missing, which is helpful, but the warning is the only feedback; no exception is raised.

Suggested Enhancements

1. Wrap baseline application and legacy marking in try/except blocks that log actionable remediation steps before re-raising.
2. Promote seed verification failures (missing or inactive records) to exceptions so automated workflows fail fast; add success logs for clarity.
3. Add contextual logging around currency/measurement-unit insert failures, particularly around execute_values calls, to aid debugging malformed data.
4. Introduce structured logging (log codes or phases) for major steps (CONNECT, MIGRATE, SEED, VERIFY) to make scanning log files easier.

These findings inform the remaining TODO subtasks for enhanced error handling.