Imported from natilusky/verdis (.claude/skills/verdis-db/SKILL.md). Install upstream with npx skills add natilusky/verdis --skill verdis-db. Copyright stays with the author.

verdis-db Skill

When to Use

When creating/modifying SQLAlchemy models or running Alembic migrations.

Steps

1. Models live in src/verdis/db/models/
2. Use SQLAlchemy 2.0 mapped_column style (not legacy Column)
3. All engines must be async (aiosqlite)
4. After model changes: uv run alembic revision --autogenerate -m "description"
5. Apply: uv run alembic upgrade head
6. Verify: uv run alembic current

Rules

• Always use render_as_batch=True in Alembic env.py (SQLite requirement)
• Enable WAL mode: PRAGMA journal_mode=WAL
• Use sqlite-vec for vector columns (NOT sqlite-vss)
• Add indexes for frequently queried columns
• Use UNIQUE constraints where appropriate

Key Files

• src/verdis/db/ — models, repositories, session management
• migrations/ — Alembic migration files
• alembic.ini — Alembic configuration