feat(db): migration runner + ordered migrations (#197, #196)

[AndresL230]

What

Phase 0 of the staging-environment plan (#246): a minimal, reproducible migration runner so migrations apply identically across environments instead of being hand-pasted into the Supabase SQL editor. Self-contained and useful on its own.

Closes#197. Closes#196.

Changes

• backend/db/migrate.py — the runner. discover_migrations (ordered) + pending_migrations (pure, unit-tested); ensure_tracking_table / applied_filenames / apply_migration over psycopg; a --baseline mode to adopt the runner on an already-migrated DB; a CLI reading SUPABASE_DB_URL (Supabase direct connection, not the pooler).
• backend/db/migrations/ — existing migration_*.sql + supabase_schema.sql moved here with NNNN_ prefixes that lock apply order (pure renames, zero content change). seed.sql and archive/ stay put.
• backend/db/migrations/0009_cosmetics.sql — every ADD CONSTRAINT guarded on pg_constraint so re-runs no longer error (migration_cosmetics.sql adds FK constraints non-idempotently — re-run fails #196).
• backend/requirements.txt — psycopg[binary]>=3.2,<4, clearly scoped as admin-only tooling (app runtime stays on PostgREST via db/connection.py).

Why a direct Postgres connection

App runtime goes through PostgREST (db/connection.py::table()), which cannot run DDL. Migrations are raw DDL, so the runner is the one sanctioned direct-Postgres path. This is documented in the module docstring.

Testing

• pytest tests/test_migrate.py — 2 passed (ordering + pending-filter logic).
• CLI guard verified: missing SUPABASE_DB_URL prints a friendly error and exits 1.
• Not yet runtime-verified:apply/--baseline and the migration_cosmetics.sql adds FK constraints non-idempotently — re-run fails #196 idempotency re-run need a live Postgres, which lands with the staging project (Phase 1). The pg_constraint guard is the standard idempotency pattern.

Adoption note

Before first use against the existing prod DB, run python -m db.migrate --baseline once to record all current migrations as applied (so it doesn't try to re-run already-applied SQL). Fresh DBs (staging) just run python -m db.migrate.

Relates to #246 (design + full plan).

🤖 Generated with Claude Code

[coderabbitai]

Warning

Review limit reached

@AndresL230, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 45 minutes and 52 seconds. Learn how PR review limits work.

Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file).

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based credits.

🚦 How do rate limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan refill rate.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, the refill rate gradually slows as usage increases. The highest same-day bursts are limited more strictly.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: f0311d2e-af29-4358-820e-0724994ac523

📥 Commits

Reviewing files that changed from the base of the PR and between 4521305 and 3541cb9.

📒 Files selected for processing (21)

• backend/db/migrate.py
• backend/db/migrations/0001_baseline_schema.sql
• backend/db/migrations/0002_roles.sql
• backend/db/migrations/0003_google_auth.sql
• backend/db/migrations/0004_onboarding_fields.sql
• backend/db/migrations/0005_profile_settings.sql
• backend/db/migrations/0006_add_is_approved.sql
• backend/db/migrations/0007_achievements.sql
• backend/db/migrations/0008_newsletter.sql
• backend/db/migrations/0009_cosmetics.sql
• backend/db/migrations/0010_admin_portal.sql
• backend/db/migrations/0011_avatars_bucket.sql
• backend/db/migrations/0012_gradebook.sql
• backend/db/migrations/0013_drop_legacy_grade_tables.sql
• backend/db/migrations/0014_notes.sql
• backend/db/migrations/0015_concept_notes.sql
• backend/db/migrations/0016_flashcard_course_id.sql
• backend/db/migrations/0017_encryption_text_columns.sql
• backend/db/migrations/0018_documents_request_id.sql
• backend/requirements.txt
• backend/tests/test_migrate.py

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/db-migration-runner

---

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.}

[cloudflare-workers-and-pages]

Deploying with Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Updated (UTC)
❌ Deployment failed View logs	frontend	3541cb9	Jun 22 2026, 04:11 AM

[AndresL230]

What

Phase 0 of the staging-environment plan (#246): a minimal, reproducible migration runner so migrations apply identically across environments instead of being hand-pasted into the Supabase SQL editor. Self-contained and useful on its own.

Closes#197. Closes#196.

Changes

• backend/db/migrate.py — the runner. discover_migrations (ordered) + pending_migrations (pure, unit-tested); ensure_tracking_table / applied_filenames / apply_migration over psycopg; a --baseline mode to adopt the runner on an already-migrated DB; a CLI reading SUPABASE_DB_URL (Supabase direct connection, not the pooler).
• backend/db/migrations/ — existing migration_*.sql + supabase_schema.sql moved here with NNNN_ prefixes that lock apply order (pure renames, zero content change). seed.sql and archive/ stay put.
• backend/db/migrations/0009_cosmetics.sql — every ADD CONSTRAINT guarded on pg_constraint so re-runs no longer error (migration_cosmetics.sql adds FK constraints non-idempotently — re-run fails #196).
• backend/requirements.txt — psycopg[binary]>=3.2,<4, clearly scoped as admin-only tooling (app runtime stays on PostgREST via db/connection.py).

Why a direct Postgres connection

App runtime goes through PostgREST (db/connection.py::table()), which cannot run DDL. Migrations are raw DDL, so the runner is the one sanctioned direct-Postgres path. This is documented in the module docstring.

Testing

• pytest tests/test_migrate.py — 2 passed (ordering + pending-filter logic).
• CLI guard verified: missing SUPABASE_DB_URL prints a friendly error and exits 1.
• Not yet runtime-verified:apply/--baseline and the migration_cosmetics.sql adds FK constraints non-idempotently — re-run fails #196 idempotency re-run need a live Postgres, which lands with the staging project (Phase 1). The pg_constraint guard is the standard idempotency pattern.

Adoption note

Before first use against the existing prod DB, run python -m db.migrate --baseline once to record all current migrations as applied (so it doesn't try to re-run already-applied SQL). Fresh DBs (staging) just run python -m db.migrate.

Relates to #246 (design + full plan).

🤖 Generated with Claude Code

[coderabbitai]

Warning

Review limit reached

@AndresL230, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 45 minutes and 52 seconds. Learn how PR review limits work.

Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file).

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based credits.

🚦 How do rate limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan refill rate.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, the refill rate gradually slows as usage increases. The highest same-day bursts are limited more strictly.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: f0311d2e-af29-4358-820e-0724994ac523

📥 Commits

Reviewing files that changed from the base of the PR and between 4521305 and 3541cb9.

📒 Files selected for processing (21)

• backend/db/migrate.py
• backend/db/migrations/0001_baseline_schema.sql
• backend/db/migrations/0002_roles.sql
• backend/db/migrations/0003_google_auth.sql
• backend/db/migrations/0004_onboarding_fields.sql
• backend/db/migrations/0005_profile_settings.sql
• backend/db/migrations/0006_add_is_approved.sql
• backend/db/migrations/0007_achievements.sql
• backend/db/migrations/0008_newsletter.sql
• backend/db/migrations/0009_cosmetics.sql
• backend/db/migrations/0010_admin_portal.sql
• backend/db/migrations/0011_avatars_bucket.sql
• backend/db/migrations/0012_gradebook.sql
• backend/db/migrations/0013_drop_legacy_grade_tables.sql
• backend/db/migrations/0014_notes.sql
• backend/db/migrations/0015_concept_notes.sql
• backend/db/migrations/0016_flashcard_course_id.sql
• backend/db/migrations/0017_encryption_text_columns.sql
• backend/db/migrations/0018_documents_request_id.sql
• backend/requirements.txt
• backend/tests/test_migrate.py

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/db-migration-runner

---

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.}

[cloudflare-workers-and-pages]

Deploying with Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Updated (UTC)
❌ Deployment failed View logs	frontend	3541cb9	Jun 22 2026, 04:11 AM

[AndresL230]

What

Phase 0 of the staging-environment plan (#246): a minimal, reproducible migration runner so migrations apply identically across environments instead of being hand-pasted into the Supabase SQL editor. Self-contained and useful on its own.

Closes#197. Closes#196.

Changes

• backend/db/migrate.py — the runner. discover_migrations (ordered) + pending_migrations (pure, unit-tested); ensure_tracking_table / applied_filenames / apply_migration over psycopg; a --baseline mode to adopt the runner on an already-migrated DB; a CLI reading SUPABASE_DB_URL (Supabase direct connection, not the pooler).
• backend/db/migrations/ — existing migration_*.sql + supabase_schema.sql moved here with NNNN_ prefixes that lock apply order (pure renames, zero content change). seed.sql and archive/ stay put.
• backend/db/migrations/0009_cosmetics.sql — every ADD CONSTRAINT guarded on pg_constraint so re-runs no longer error (migration_cosmetics.sql adds FK constraints non-idempotently — re-run fails #196).
• backend/requirements.txt — psycopg[binary]>=3.2,<4, clearly scoped as admin-only tooling (app runtime stays on PostgREST via db/connection.py).

Why a direct Postgres connection

App runtime goes through PostgREST (db/connection.py::table()), which cannot run DDL. Migrations are raw DDL, so the runner is the one sanctioned direct-Postgres path. This is documented in the module docstring.

Testing

• pytest tests/test_migrate.py — 2 passed (ordering + pending-filter logic).
• CLI guard verified: missing SUPABASE_DB_URL prints a friendly error and exits 1.
• Not yet runtime-verified:apply/--baseline and the migration_cosmetics.sql adds FK constraints non-idempotently — re-run fails #196 idempotency re-run need a live Postgres, which lands with the staging project (Phase 1). The pg_constraint guard is the standard idempotency pattern.

Adoption note

Before first use against the existing prod DB, run python -m db.migrate --baseline once to record all current migrations as applied (so it doesn't try to re-run already-applied SQL). Fresh DBs (staging) just run python -m db.migrate.

Relates to #246 (design + full plan).

🤖 Generated with Claude Code

[coderabbitai]

Warning

Review limit reached

@AndresL230, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 45 minutes and 52 seconds. Learn how PR review limits work.

Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file).

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based credits.

🚦 How do rate limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan refill rate.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, the refill rate gradually slows as usage increases. The highest same-day bursts are limited more strictly.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: f0311d2e-af29-4358-820e-0724994ac523

📥 Commits

Reviewing files that changed from the base of the PR and between 4521305 and 3541cb9.

📒 Files selected for processing (21)

• backend/db/migrate.py
• backend/db/migrations/0001_baseline_schema.sql
• backend/db/migrations/0002_roles.sql
• backend/db/migrations/0003_google_auth.sql
• backend/db/migrations/0004_onboarding_fields.sql
• backend/db/migrations/0005_profile_settings.sql
• backend/db/migrations/0006_add_is_approved.sql
• backend/db/migrations/0007_achievements.sql
• backend/db/migrations/0008_newsletter.sql
• backend/db/migrations/0009_cosmetics.sql
• backend/db/migrations/0010_admin_portal.sql
• backend/db/migrations/0011_avatars_bucket.sql
• backend/db/migrations/0012_gradebook.sql
• backend/db/migrations/0013_drop_legacy_grade_tables.sql
• backend/db/migrations/0014_notes.sql
• backend/db/migrations/0015_concept_notes.sql
• backend/db/migrations/0016_flashcard_course_id.sql
• backend/db/migrations/0017_encryption_text_columns.sql
• backend/db/migrations/0018_documents_request_id.sql
• backend/requirements.txt
• backend/tests/test_migrate.py

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/db-migration-runner

---

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.}

[cloudflare-workers-and-pages]

Deploying with Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Updated (UTC)
❌ Deployment failed View logs	frontend	3541cb9	Jun 22 2026, 04:11 AM

[AndresL230]

What

Phase 0 of the staging-environment plan (#246): a minimal, reproducible migration runner so migrations apply identically across environments instead of being hand-pasted into the Supabase SQL editor. Self-contained and useful on its own.

Closes#197. Closes#196.

Changes

• backend/db/migrate.py — the runner. discover_migrations (ordered) + pending_migrations (pure, unit-tested); ensure_tracking_table / applied_filenames / apply_migration over psycopg; a --baseline mode to adopt the runner on an already-migrated DB; a CLI reading SUPABASE_DB_URL (Supabase direct connection, not the pooler).
• backend/db/migrations/ — existing migration_*.sql + supabase_schema.sql moved here with NNNN_ prefixes that lock apply order (pure renames, zero content change). seed.sql and archive/ stay put.
• backend/db/migrations/0009_cosmetics.sql — every ADD CONSTRAINT guarded on pg_constraint so re-runs no longer error (migration_cosmetics.sql adds FK constraints non-idempotently — re-run fails #196).
• backend/requirements.txt — psycopg[binary]>=3.2,<4, clearly scoped as admin-only tooling (app runtime stays on PostgREST via db/connection.py).

Why a direct Postgres connection

App runtime goes through PostgREST (db/connection.py::table()), which cannot run DDL. Migrations are raw DDL, so the runner is the one sanctioned direct-Postgres path. This is documented in the module docstring.

Testing

• pytest tests/test_migrate.py — 2 passed (ordering + pending-filter logic).
• CLI guard verified: missing SUPABASE_DB_URL prints a friendly error and exits 1.
• Not yet runtime-verified:apply/--baseline and the migration_cosmetics.sql adds FK constraints non-idempotently — re-run fails #196 idempotency re-run need a live Postgres, which lands with the staging project (Phase 1). The pg_constraint guard is the standard idempotency pattern.

Adoption note

Before first use against the existing prod DB, run python -m db.migrate --baseline once to record all current migrations as applied (so it doesn't try to re-run already-applied SQL). Fresh DBs (staging) just run python -m db.migrate.

Relates to #246 (design + full plan).

🤖 Generated with Claude Code

[coderabbitai]

Warning

Review limit reached

@AndresL230, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 45 minutes and 52 seconds. Learn how PR review limits work.

Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file).

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based credits.

🚦 How do rate limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan refill rate.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, the refill rate gradually slows as usage increases. The highest same-day bursts are limited more strictly.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: f0311d2e-af29-4358-820e-0724994ac523

📥 Commits

Reviewing files that changed from the base of the PR and between 4521305 and 3541cb9.

📒 Files selected for processing (21)

• backend/db/migrate.py
• backend/db/migrations/0001_baseline_schema.sql
• backend/db/migrations/0002_roles.sql
• backend/db/migrations/0003_google_auth.sql
• backend/db/migrations/0004_onboarding_fields.sql
• backend/db/migrations/0005_profile_settings.sql
• backend/db/migrations/0006_add_is_approved.sql
• backend/db/migrations/0007_achievements.sql
• backend/db/migrations/0008_newsletter.sql
• backend/db/migrations/0009_cosmetics.sql
• backend/db/migrations/0010_admin_portal.sql
• backend/db/migrations/0011_avatars_bucket.sql
• backend/db/migrations/0012_gradebook.sql
• backend/db/migrations/0013_drop_legacy_grade_tables.sql
• backend/db/migrations/0014_notes.sql
• backend/db/migrations/0015_concept_notes.sql
• backend/db/migrations/0016_flashcard_course_id.sql
• backend/db/migrations/0017_encryption_text_columns.sql
• backend/db/migrations/0018_documents_request_id.sql
• backend/requirements.txt
• backend/tests/test_migrate.py

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/db-migration-runner

---

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.}

[cloudflare-workers-and-pages]

Deploying with Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Updated (UTC)
❌ Deployment failed View logs	frontend	3541cb9	Jun 22 2026, 04:11 AM

[AndresL230]

What

Phase 0 of the staging-environment plan (#246): a minimal, reproducible migration runner so migrations apply identically across environments instead of being hand-pasted into the Supabase SQL editor. Self-contained and useful on its own.

Closes#197. Closes#196.

Changes

• backend/db/migrate.py — the runner. discover_migrations (ordered) + pending_migrations (pure, unit-tested); ensure_tracking_table / applied_filenames / apply_migration over psycopg; a --baseline mode to adopt the runner on an already-migrated DB; a CLI reading SUPABASE_DB_URL (Supabase direct connection, not the pooler).
• backend/db/migrations/ — existing migration_*.sql + supabase_schema.sql moved here with NNNN_ prefixes that lock apply order (pure renames, zero content change). seed.sql and archive/ stay put.
• backend/db/migrations/0009_cosmetics.sql — every ADD CONSTRAINT guarded on pg_constraint so re-runs no longer error (migration_cosmetics.sql adds FK constraints non-idempotently — re-run fails #196).
• backend/requirements.txt — psycopg[binary]>=3.2,<4, clearly scoped as admin-only tooling (app runtime stays on PostgREST via db/connection.py).

Why a direct Postgres connection

App runtime goes through PostgREST (db/connection.py::table()), which cannot run DDL. Migrations are raw DDL, so the runner is the one sanctioned direct-Postgres path. This is documented in the module docstring.

Testing

• pytest tests/test_migrate.py — 2 passed (ordering + pending-filter logic).
• CLI guard verified: missing SUPABASE_DB_URL prints a friendly error and exits 1.
• Not yet runtime-verified:apply/--baseline and the migration_cosmetics.sql adds FK constraints non-idempotently — re-run fails #196 idempotency re-run need a live Postgres, which lands with the staging project (Phase 1). The pg_constraint guard is the standard idempotency pattern.

Adoption note

Before first use against the existing prod DB, run python -m db.migrate --baseline once to record all current migrations as applied (so it doesn't try to re-run already-applied SQL). Fresh DBs (staging) just run python -m db.migrate.

Relates to #246 (design + full plan).

🤖 Generated with Claude Code

[coderabbitai]

Warning

Review limit reached

@AndresL230, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 45 minutes and 52 seconds. Learn how PR review limits work.

Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file).

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based credits.

🚦 How do rate limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan refill rate.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, the refill rate gradually slows as usage increases. The highest same-day bursts are limited more strictly.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: f0311d2e-af29-4358-820e-0724994ac523

📥 Commits

Reviewing files that changed from the base of the PR and between 4521305 and 3541cb9.

📒 Files selected for processing (21)

• backend/db/migrate.py
• backend/db/migrations/0001_baseline_schema.sql
• backend/db/migrations/0002_roles.sql
• backend/db/migrations/0003_google_auth.sql
• backend/db/migrations/0004_onboarding_fields.sql
• backend/db/migrations/0005_profile_settings.sql
• backend/db/migrations/0006_add_is_approved.sql
• backend/db/migrations/0007_achievements.sql
• backend/db/migrations/0008_newsletter.sql
• backend/db/migrations/0009_cosmetics.sql
• backend/db/migrations/0010_admin_portal.sql
• backend/db/migrations/0011_avatars_bucket.sql
• backend/db/migrations/0012_gradebook.sql
• backend/db/migrations/0013_drop_legacy_grade_tables.sql
• backend/db/migrations/0014_notes.sql
• backend/db/migrations/0015_concept_notes.sql
• backend/db/migrations/0016_flashcard_course_id.sql
• backend/db/migrations/0017_encryption_text_columns.sql
• backend/db/migrations/0018_documents_request_id.sql
• backend/requirements.txt
• backend/tests/test_migrate.py

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/db-migration-runner

---

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.}

[cloudflare-workers-and-pages]

Deploying with Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Updated (UTC)
❌ Deployment failed View logs	frontend	3541cb9	Jun 22 2026, 04:11 AM

[AndresL230]

What

Phase 0 of the staging-environment plan (#246): a minimal, reproducible migration runner so migrations apply identically across environments instead of being hand-pasted into the Supabase SQL editor. Self-contained and useful on its own.

Closes#197. Closes#196.

Changes

• backend/db/migrate.py — the runner. discover_migrations (ordered) + pending_migrations (pure, unit-tested); ensure_tracking_table / applied_filenames / apply_migration over psycopg; a --baseline mode to adopt the runner on an already-migrated DB; a CLI reading SUPABASE_DB_URL (Supabase direct connection, not the pooler).
• backend/db/migrations/ — existing migration_*.sql + supabase_schema.sql moved here with NNNN_ prefixes that lock apply order (pure renames, zero content change). seed.sql and archive/ stay put.
• backend/db/migrations/0009_cosmetics.sql — every ADD CONSTRAINT guarded on pg_constraint so re-runs no longer error (migration_cosmetics.sql adds FK constraints non-idempotently — re-run fails #196).
• backend/requirements.txt — psycopg[binary]>=3.2,<4, clearly scoped as admin-only tooling (app runtime stays on PostgREST via db/connection.py).

Why a direct Postgres connection

App runtime goes through PostgREST (db/connection.py::table()), which cannot run DDL. Migrations are raw DDL, so the runner is the one sanctioned direct-Postgres path. This is documented in the module docstring.

Testing

• pytest tests/test_migrate.py — 2 passed (ordering + pending-filter logic).
• CLI guard verified: missing SUPABASE_DB_URL prints a friendly error and exits 1.
• Not yet runtime-verified:apply/--baseline and the migration_cosmetics.sql adds FK constraints non-idempotently — re-run fails #196 idempotency re-run need a live Postgres, which lands with the staging project (Phase 1). The pg_constraint guard is the standard idempotency pattern.

Adoption note

Before first use against the existing prod DB, run python -m db.migrate --baseline once to record all current migrations as applied (so it doesn't try to re-run already-applied SQL). Fresh DBs (staging) just run python -m db.migrate.

Relates to #246 (design + full plan).

🤖 Generated with Claude Code

[coderabbitai]

Warning

Review limit reached

@AndresL230, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 45 minutes and 52 seconds. Learn how PR review limits work.

Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file).

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based credits.

🚦 How do rate limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan refill rate.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, the refill rate gradually slows as usage increases. The highest same-day bursts are limited more strictly.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: f0311d2e-af29-4358-820e-0724994ac523

📥 Commits

Reviewing files that changed from the base of the PR and between 4521305 and 3541cb9.

📒 Files selected for processing (21)

• backend/db/migrate.py
• backend/db/migrations/0001_baseline_schema.sql
• backend/db/migrations/0002_roles.sql
• backend/db/migrations/0003_google_auth.sql
• backend/db/migrations/0004_onboarding_fields.sql
• backend/db/migrations/0005_profile_settings.sql
• backend/db/migrations/0006_add_is_approved.sql
• backend/db/migrations/0007_achievements.sql
• backend/db/migrations/0008_newsletter.sql
• backend/db/migrations/0009_cosmetics.sql
• backend/db/migrations/0010_admin_portal.sql
• backend/db/migrations/0011_avatars_bucket.sql
• backend/db/migrations/0012_gradebook.sql
• backend/db/migrations/0013_drop_legacy_grade_tables.sql
• backend/db/migrations/0014_notes.sql
• backend/db/migrations/0015_concept_notes.sql
• backend/db/migrations/0016_flashcard_course_id.sql
• backend/db/migrations/0017_encryption_text_columns.sql
• backend/db/migrations/0018_documents_request_id.sql
• backend/requirements.txt
• backend/tests/test_migrate.py

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/db-migration-runner

---

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.}

[cloudflare-workers-and-pages]

Deploying with Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Updated (UTC)
❌ Deployment failed View logs	frontend	3541cb9	Jun 22 2026, 04:11 AM

[AndresL230]

What

Phase 0 of the staging-environment plan (#246): a minimal, reproducible migration runner so migrations apply identically across environments instead of being hand-pasted into the Supabase SQL editor. Self-contained and useful on its own.

Closes#197. Closes#196.

Changes

• backend/db/migrate.py — the runner. discover_migrations (ordered) + pending_migrations (pure, unit-tested); ensure_tracking_table / applied_filenames / apply_migration over psycopg; a --baseline mode to adopt the runner on an already-migrated DB; a CLI reading SUPABASE_DB_URL (Supabase direct connection, not the pooler).
• backend/db/migrations/ — existing migration_*.sql + supabase_schema.sql moved here with NNNN_ prefixes that lock apply order (pure renames, zero content change). seed.sql and archive/ stay put.
• backend/db/migrations/0009_cosmetics.sql — every ADD CONSTRAINT guarded on pg_constraint so re-runs no longer error (migration_cosmetics.sql adds FK constraints non-idempotently — re-run fails #196).
• backend/requirements.txt — psycopg[binary]>=3.2,<4, clearly scoped as admin-only tooling (app runtime stays on PostgREST via db/connection.py).

Why a direct Postgres connection

App runtime goes through PostgREST (db/connection.py::table()), which cannot run DDL. Migrations are raw DDL, so the runner is the one sanctioned direct-Postgres path. This is documented in the module docstring.

Testing

• pytest tests/test_migrate.py — 2 passed (ordering + pending-filter logic).
• CLI guard verified: missing SUPABASE_DB_URL prints a friendly error and exits 1.
• Not yet runtime-verified:apply/--baseline and the migration_cosmetics.sql adds FK constraints non-idempotently — re-run fails #196 idempotency re-run need a live Postgres, which lands with the staging project (Phase 1). The pg_constraint guard is the standard idempotency pattern.

Adoption note

Before first use against the existing prod DB, run python -m db.migrate --baseline once to record all current migrations as applied (so it doesn't try to re-run already-applied SQL). Fresh DBs (staging) just run python -m db.migrate.

Relates to #246 (design + full plan).

🤖 Generated with Claude Code

[coderabbitai]

Warning

Review limit reached

@AndresL230, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 45 minutes and 52 seconds. Learn how PR review limits work.

Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file).

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based credits.

🚦 How do rate limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan refill rate.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, the refill rate gradually slows as usage increases. The highest same-day bursts are limited more strictly.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: f0311d2e-af29-4358-820e-0724994ac523

📥 Commits

Reviewing files that changed from the base of the PR and between 4521305 and 3541cb9.

📒 Files selected for processing (21)

• backend/db/migrate.py
• backend/db/migrations/0001_baseline_schema.sql
• backend/db/migrations/0002_roles.sql
• backend/db/migrations/0003_google_auth.sql
• backend/db/migrations/0004_onboarding_fields.sql
• backend/db/migrations/0005_profile_settings.sql
• backend/db/migrations/0006_add_is_approved.sql
• backend/db/migrations/0007_achievements.sql
• backend/db/migrations/0008_newsletter.sql
• backend/db/migrations/0009_cosmetics.sql
• backend/db/migrations/0010_admin_portal.sql
• backend/db/migrations/0011_avatars_bucket.sql
• backend/db/migrations/0012_gradebook.sql
• backend/db/migrations/0013_drop_legacy_grade_tables.sql
• backend/db/migrations/0014_notes.sql
• backend/db/migrations/0015_concept_notes.sql
• backend/db/migrations/0016_flashcard_course_id.sql
• backend/db/migrations/0017_encryption_text_columns.sql
• backend/db/migrations/0018_documents_request_id.sql
• backend/requirements.txt
• backend/tests/test_migrate.py

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/db-migration-runner

---

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.}

[cloudflare-workers-and-pages]

Deploying with Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Updated (UTC)
❌ Deployment failed View logs	frontend	3541cb9	Jun 22 2026, 04:11 AM

[AndresL230]

What

Phase 0 of the staging-environment plan (#246): a minimal, reproducible migration runner so migrations apply identically across environments instead of being hand-pasted into the Supabase SQL editor. Self-contained and useful on its own.

Closes#197. Closes#196.

Changes

• backend/db/migrate.py — the runner. discover_migrations (ordered) + pending_migrations (pure, unit-tested); ensure_tracking_table / applied_filenames / apply_migration over psycopg; a --baseline mode to adopt the runner on an already-migrated DB; a CLI reading SUPABASE_DB_URL (Supabase direct connection, not the pooler).
• backend/db/migrations/ — existing migration_*.sql + supabase_schema.sql moved here with NNNN_ prefixes that lock apply order (pure renames, zero content change). seed.sql and archive/ stay put.
• backend/db/migrations/0009_cosmetics.sql — every ADD CONSTRAINT guarded on pg_constraint so re-runs no longer error (migration_cosmetics.sql adds FK constraints non-idempotently — re-run fails #196).
• backend/requirements.txt — psycopg[binary]>=3.2,<4, clearly scoped as admin-only tooling (app runtime stays on PostgREST via db/connection.py).

Why a direct Postgres connection

App runtime goes through PostgREST (db/connection.py::table()), which cannot run DDL. Migrations are raw DDL, so the runner is the one sanctioned direct-Postgres path. This is documented in the module docstring.

Testing

• pytest tests/test_migrate.py — 2 passed (ordering + pending-filter logic).
• CLI guard verified: missing SUPABASE_DB_URL prints a friendly error and exits 1.
• Not yet runtime-verified:apply/--baseline and the migration_cosmetics.sql adds FK constraints non-idempotently — re-run fails #196 idempotency re-run need a live Postgres, which lands with the staging project (Phase 1). The pg_constraint guard is the standard idempotency pattern.

Adoption note

Before first use against the existing prod DB, run python -m db.migrate --baseline once to record all current migrations as applied (so it doesn't try to re-run already-applied SQL). Fresh DBs (staging) just run python -m db.migrate.

Relates to #246 (design + full plan).

🤖 Generated with Claude Code

[coderabbitai]

Warning

Review limit reached

@AndresL230, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 45 minutes and 52 seconds. Learn how PR review limits work.

Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file).

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based credits.

🚦 How do rate limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan refill rate.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, the refill rate gradually slows as usage increases. The highest same-day bursts are limited more strictly.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: f0311d2e-af29-4358-820e-0724994ac523

📥 Commits

Reviewing files that changed from the base of the PR and between 4521305 and 3541cb9.

📒 Files selected for processing (21)

• backend/db/migrate.py
• backend/db/migrations/0001_baseline_schema.sql
• backend/db/migrations/0002_roles.sql
• backend/db/migrations/0003_google_auth.sql
• backend/db/migrations/0004_onboarding_fields.sql
• backend/db/migrations/0005_profile_settings.sql
• backend/db/migrations/0006_add_is_approved.sql
• backend/db/migrations/0007_achievements.sql
• backend/db/migrations/0008_newsletter.sql
• backend/db/migrations/0009_cosmetics.sql
• backend/db/migrations/0010_admin_portal.sql
• backend/db/migrations/0011_avatars_bucket.sql
• backend/db/migrations/0012_gradebook.sql
• backend/db/migrations/0013_drop_legacy_grade_tables.sql
• backend/db/migrations/0014_notes.sql
• backend/db/migrations/0015_concept_notes.sql
• backend/db/migrations/0016_flashcard_course_id.sql
• backend/db/migrations/0017_encryption_text_columns.sql
• backend/db/migrations/0018_documents_request_id.sql
• backend/requirements.txt
• backend/tests/test_migrate.py

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/db-migration-runner

---

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.}

[cloudflare-workers-and-pages]

Deploying with Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Updated (UTC)
❌ Deployment failed View logs	frontend	3541cb9	Jun 22 2026, 04:11 AM