fix: v0.19.1 audit DB upgrade safety, run migrations before SCHEMA_SQL

[vaaraio]

Summary

• Patch fix for an init bug where opening an existing audit DB at any schema version older than the current one crashed on first MCP-server boot with no such column: tenant_id.
• Root cause: SCHEMA_SQL ran before migrations, and SCHEMA_SQL contains indexes on columns that later migrations add.
• Fix: init now runs migrations from the stored version (or from v0 for pre-versioned DBs that have no audit_meta row yet) before running SCHEMA_SQL idempotently. Fresh DBs continue to use the existing single-pass path.

Why this is a patch, not minor

• Behaviour change is bug-fix only. Public API unchanged. Existing fresh-DB path is unchanged.
• Lockstep PyPI 0.19.0 → 0.19.1 + npm @vaara/client 0.19.0 → 0.19.1 per release-PR rule.

Test plan

• Three new tests in TestSchemaUpgrade: pre-versioning (v0), v1, and current-version reopen-is-idempotent.
• All 683 existing tests still pass, 12 skipped, 0 failed.
• Reproduced the crash on an actual v=1 DB and confirmed the fix resolves it.

Summary by CodeRabbit

• Bug Fixes

  • Fixed a critical crash on MCP-server startup when opening existing audit databases with older schema versions. Database initialization now properly migrates legacy schemas before applying the current schema definitions.

• Tests

  • Added comprehensive test coverage for database upgrade paths, verifying successful migrations from pre-versioned and v1 schema states to the current version.

[coderabbitai]

📝 Walkthrough

Walkthrough

This patch release (0.19.1) fixes MCP-server startup crashes when opening existing audit databases with older schema versions. The fix reorders initialization to run schema migrations based on stored version before applying SCHEMA_SQL, with special handling for pre-versioned databases, while preserving single-pass behavior for fresh databases.

Changes

Audit DB Upgrade Safety

Layer / File(s)	Summary
Release version bump and changelog CHANGELOG.md, clients/ts/package.json, pyproject.toml, src/vaara/__init__.py	Version 0.19.1 released, documenting the audit DB upgrade safety fix for older schema versions.
Audit schema initialization refactoring src/vaara/audit/sqlite_backend.py	Helper methods _table_exists() and _stored_schema_version() added. _init_schema() reworked to branch on fresh vs. existing DB: fresh DBs run SCHEMA_SQL once; existing DBs ensure audit_meta exists, resolve stored version (treating missing as v0), run incremental migrations, then apply SCHEMA_SQL idempotently.
Schema upgrade test coverage tests/test_sqlite_backend.py	TestSchemaUpgrade suite seeds v0 (pre-versioning) and v1 databases, then verifies reopening with SQLiteAuditBackend migrates them to current schema with all expected columns and updated version, plus idempotency test for current-schema reopens.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Poem

🐰 A rabbit hops through databases old,
Migrations run as stories are told,
From v0 to v1, all paths are safe,
No tenant_id crashes on the database waif!
Version bumps complete, the patch takes flight. ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 41.67% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title directly and accurately summarizes the main change: fixing audit DB upgrade safety by running migrations before SCHEMA_SQL, with the specific version number contextualized.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/audit-init-upgrade-safety

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

🧹 Nitpick comments (1)

tests/test_sqlite_backend.py (1)

222-237: ⚡ Quick win

Assert the post-migration SCHEMA_SQL artifacts too.

_assert_current() only verifies the version row and migrated columns. That still passes if the final idempotent SCHEMA_SQL call is dropped, so upgraded DBs could silently miss gdpr_redactions, api_keys, or idx_tenant_id. Please assert those as well in this helper.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@tests/test_sqlite_backend.py` around lines 222 - 237, The helper
_assert_current currently only checks schema_version and migrated columns but
must also assert that final SCHEMA_SQL artifacts exist; update _assert_current
to, after connecting to the DB (in the same function), verify presence of the
gdpr_redactions and api_keys tables (or expected objects created by SCHEMA_SQL)
and that the index idx_tenant_id exists (use PRAGMA table_info / sqlite_master
queries to confirm table and index names), and raise assertions if any are
missing so the post-migration SCHEMA_SQL call cannot be omitted silently.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@tests/test_sqlite_backend.py`:
- Around line 222-237: The helper _assert_current currently only checks
schema_version and migrated columns but must also assert that final SCHEMA_SQL
artifacts exist; update _assert_current to, after connecting to the DB (in the
same function), verify presence of the gdpr_redactions and api_keys tables (or
expected objects created by SCHEMA_SQL) and that the index idx_tenant_id exists
(use PRAGMA table_info / sqlite_master queries to confirm table and index
names), and raise assertions if any are missing so the post-migration SCHEMA_SQL
call cannot be omitted silently.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 830b5add-1ad0-44c0-8eb6-a2ed2b11b7aa

📥 Commits

Reviewing files that changed from the base of the PR and between a885358 and 0253180.

📒 Files selected for processing (6)

• CHANGELOG.md
• clients/ts/package.json
• pyproject.toml
• src/vaara/__init__.py
• src/vaara/audit/sqlite_backend.py
• tests/test_sqlite_backend.py