Add Alembic migration framework for PostgreSQL

[cmeans]

Summary

Version-tracked database migrations using Alembic with raw SQL (no SQLAlchemy ORM). Replaces inline migration code in PostgresStore.

• alembic/ directory with env.py reading AWARENESS_DATABASE_URL
• Initial schema migration: baseline capturing current v0.3.1 schema
• pgvector extension migration: CREATE EXTENSION IF NOT EXISTS vector
• mcp-awareness-migrate CLI: upgrade, stamp, current, history, downgrade
• Dockerfile: includes alembic.ini and migration files
• RDS-compatible: standard Postgres connection strings, SSL support

SQLite retains inline migrations — Alembic is Postgres-only.

Origin

Code review flagged "no schema versioning" as weakness #10. Inline _create_tables migrations don't track versions, making it impossible to know what state a database is in or roll back changes.

CHANGELOG

• Updated under [Unreleased]

README

• No tool count or status changes needed

QA: Manual testing steps

Prerequisites

• This branch checked out: git checkout alembic-migrations
• pip install -e ".[dev]" to pick up alembic + sqlalchemy
• Postgres running locally (docker compose up -d postgres)

1. Check current migration status

AWARENESS_DATABASE_URL=postgresql://awareness:awareness-dev@localhost:5432/awareness \
mcp-awareness-migrate --current

• Shows a0f1c4855eb2 (head) or 9184f91831f8 (head)

2. For existing database — stamp as current

If running against a database that was created before Alembic:

AWARENESS_DATABASE_URL=postgresql://awareness:awareness-dev@localhost:5432/awareness \
mcp-awareness-migrate --stamp

• Prints "Database stamped as current"
• alembic_version table exists with current revision

3. For fresh database — run migrations

# Create a test database
psql postgresql://awareness:awareness-dev@localhost:5432/awareness -c "CREATE DATABASE awareness_test"

AWARENESS_DATABASE_URL=postgresql://awareness:awareness-dev@localhost:5432/awareness_test \
mcp-awareness-migrate

• Prints "Migrations complete"
• Table entries exists with all columns including logical_key
• pgvector extension installed

4. View history

AWARENESS_DATABASE_URL=postgresql://awareness:awareness-dev@localhost:5432/awareness \
mcp-awareness-migrate --history

• Shows two revisions: initial schema → pgvector extension

5. Start server and verify it works

AWARENESS_BACKEND=postgres \
AWARENESS_DATABASE_URL=postgresql://awareness:awareness-dev@localhost:5432/awareness \
AWARENESS_TRANSPORT=streamable-http \
AWARENESS_PORT=8421 \
python -m mcp_awareness.server

• Server starts without migration-related errors
• Tools work normally (get_briefing, remember, etc.)

5b. Docker rebuild (production deployment)

git checkout main && git pull
docker compose build && docker compose up -d

docker compose build && docker compose up -d

• Container starts and shows healthy
• Docker logs show "Running database migrations..." followed by "Migrations complete"
• Server starts normally after migrations

6. Cleanup

• psql ... -c "DROP DATABASE IF EXISTS awareness_test" (if created in step 3)

Automated tests

• 155 tests pass
• ruff/mypy/format clean

🤖 Generated with Claude Code