fix: drop v2 key verification aggregation chain from default db

[Flo4604]

What does this PR do?

Removes the v2 key verification aggregation chain from ClickHouse, which has been fully replaced by the v3 chain that provides better partitioning and longer TTL. This cleanup removes the deprecated materialized views and tables for minute, hour, day, and month aggregations.

The migration drops the v2 aggregation chain in the correct order (leaf materialized views first, then upstream views, then tables) to avoid dependency conflicts.

Fixes # (issue)

Type of change

• Bug fix (non-breaking change which fixes an issue)
• Chore (refactoring code, technical debt, workflow improvements)
• Enhancement (small improvements)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• This change requires a documentation update

How should this be tested?

• Verify that the migration runs successfully without errors
• Confirm that v3 aggregation chain continues to function properly
• Check that no queries are still referencing the v2 tables/views

Checklist

Required

• Filled out the "How to test" section in this PR
• Read Contributing Guide
• Self-reviewed my own code
• Commented on my code in hard-to-understand areas
• Ran pnpm build
• Ran pnpm fmt
• Ran make fmt on /go directory
• Checked for warnings, there are none
• Removed all console.logs
• Merged the latest changes from main onto my branch with git pull origin main
• My changes don't cause any responsiveness issues

Appreciated

• If a UI change was made: Added a screen recording or screenshots to this PR
• Updated the Unkey Docs if changes were necessary

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
dashboard	Ready	Preview, Comment	Mar 16, 2026 2:48pm

[Flo4604]

• fix: drop legacy clickhouse tables and remove v1 schema #5230
• fix: drop v2 key verification aggregation chain from default db #5231 👈 (View in Graphite)
• fix: remove v2 aggregation tables from default allowed tables #5229
• fix: use v3 verification aggregation tables in keys overview #5228
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR removes ClickHouse v2 aggregation tables and materialized views for key verifications analytics, including per-minute, per-hour, per-day, and per-month aggregation tables, along with their supporting materialized views and migration steps. Legacy schema definitions are also deleted. Materialized views are subsequently recreated pointing to v3 tables instead.

Changes

Cohort / File(s)	Summary
Aggregation v2 schema files pkg/clickhouse/schema/002_key_verifications_per_minute_v2.sql, pkg/clickhouse/schema/003_key_verifications_per_hour_v2.sql, pkg/clickhouse/schema/004_key_verifications_per_day_v2.sql, pkg/clickhouse/schema/005_key_verifications_per_month_v2.sql	Removed time-based aggregation tables and their corresponding materialized views, eliminating the per-minute, per-hour, per-day, and per-month aggregation pipeline for key verifications metrics.
Legacy schema cleanup pkg/clickhouse/schema/000_legacy.sql	Deleted entire legacy ClickHouse schema file containing comprehensive database, table, and materialized view definitions across verifications, ratelimits, metrics, billing, and business schemas.
Migration initialization removal pkg/clickhouse/migrations/20250903085516_init.sql	Removed bulk schema initialization that created multiple databases, tables, and materialized views for billing, metrics, ratelimits, and verifications.
Temporary sync view cleanup pkg/clickhouse/schema/001_key_verifications_raw_v2.sql, pkg/clickhouse/schema/006_ratelimits_raw_v2.sql, pkg/clickhouse/schema/012_api_requests_raw_v2.sql	Removed temporary materialized views (temp_sync_*) used for zero-downtime migration from v1 to v2 schemas.
Aggregation pipeline reorganization pkg/clickhouse/migrations/20250911070454.sql, pkg/clickhouse/migrations/20251010160229.sql	Removed multiple key_verifications per-day/hour/minute/month materialized view and table creation blocks; removed deprecated MV dependencies and legacy synchronization views.
Migration view cleanup pkg/clickhouse/migrations/20250925091254.sql	Removed migration steps for temp_sync materialized views.
v3 materialization setup pkg/clickhouse/migrations/20251125075943.sql	Created two new materialized views (active_workspaces_keys_per_month_mv_v2 and billable_verifications_per_month_mv_v2) pointing to v3 key_verifications aggregation tables instead of v2.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

• feat: add external_id to order key #4379: Adds v3 equivalents of key_verifications aggregation tables and updates materialized views to source from v3 instead of v2, directly complementing the v2 removal in this PR.
• feat: add ratelimits/api ch columns #4016: Modifies the same key_verifications schema files being deleted here (adding columns, removing PARTITION clauses), representing prior iterations of the same aggregation pipeline refactor.
• chore: switch clickhouse reads to new tables #4262: Updates application code and tests to reference removed ClickHouse v2 objects (default.key_verifications_raw_v2, key_verifications_per_hour/day/month_v2), making it dependent on this migration.

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: removing the v2 key verification aggregation chain from the default database.
Description check	✅ Passed	The description provides a clear explanation of what the PR does and why (v2 replaced by v3), includes the correct type of change (Chore), and provides testing guidance.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch fix/drop-v2-verification-aggregation-chain

📝 Coding Plan

• Generate coding plan for human review comments

---

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

Tip

You can customize the tone of the review comments and chat replies.

Configure the tone_instructions setting to customize the tone of the review comments and chat replies. For example, you can set the tone to Act like a strict teacher, Act like a pirate and more.

[coderabbitai]

🧹 Nitpick comments (1)

pkg/clickhouse/migrations/20260306000001.sql (1)

1-3: Confirm public alias behavior stays stable during this cleanup.

Since this removes internal v2 objects, just ensure public-facing alias mappings remain unchanged unless query results changed for users.

Based on learnings: public-facing table aliases should only be bumped when changes affect user-visible behavior or query results.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@pkg/clickhouse/migrations/20260306000001.sql` around lines 1 - 3, Verify that
removing the v2 aggregation chain does not change any public aliases: audit all
public-facing alias mappings and view/table names that reference the "v2" chain
(leaf MVs, upstream MVs, tables) and ensure they either (a) continue to point to
the same query results or (b) are explicitly remapped to the v3 equivalents only
if query results are identical; update the migration to keep existing public
aliases unchanged unless you intentionally replace them, add atomic swaps or
create temporary aliases to preserve queries during the drop, and add/execute
automated integration tests and a diff-of-query-results check comparing v2 vs v3
for each public alias to confirm no user-visible change.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@pkg/clickhouse/migrations/20260306000001.sql`:
- Around line 1-3: Verify that removing the v2 aggregation chain does not change
any public aliases: audit all public-facing alias mappings and view/table names
that reference the "v2" chain (leaf MVs, upstream MVs, tables) and ensure they
either (a) continue to point to the same query results or (b) are explicitly
remapped to the v3 equivalents only if query results are identical; update the
migration to keep existing public aliases unchanged unless you intentionally
replace them, add atomic swaps or create temporary aliases to preserve queries
during the drop, and add/execute automated integration tests and a
diff-of-query-results check comparing v2 vs v3 for each public alias to confirm
no user-visible change.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: dfb19dda-183f-48d6-b42e-0ac1a77155f3

📥 Commits

Reviewing files that changed from the base of the PR and between f138801 and b920cc7.

📒 Files selected for processing (5)

• pkg/clickhouse/migrations/20260306000001.sql
• pkg/clickhouse/schema/002_key_verifications_per_minute_v2.sql
• pkg/clickhouse/schema/003_key_verifications_per_hour_v2.sql
• pkg/clickhouse/schema/004_key_verifications_per_day_v2.sql
• pkg/clickhouse/schema/005_key_verifications_per_month_v2.sql

💤 Files with no reviewable changes (4)

• pkg/clickhouse/schema/004_key_verifications_per_day_v2.sql
• pkg/clickhouse/schema/002_key_verifications_per_minute_v2.sql
• pkg/clickhouse/schema/003_key_verifications_per_hour_v2.sql
• pkg/clickhouse/schema/005_key_verifications_per_month_v2.sql

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@pkg/clickhouse/migrations/20260306000000.sql`:
- Around line 79-84: Before executing each DROP DATABASE IF EXISTS (for
databases `verifications`, `ratelimits`, `metrics`, `billing`, and `business`)
add a safety guard that checks the database is empty and aborts the migration if
any tables remain; specifically, query the system.tables (or information_schema)
for each database name and raise an error or fail the migration if the query
returns any rows, only proceeding to the DROP DATABASE when the check confirms
zero tables. Ensure this emptiness check runs for each of the five databases and
provides a clear error message identifying the database with leftover objects so
the migration fails fast rather than silently deleting unexpected data.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: b1747880-8623-4a49-acb2-351cd05689e6

📥 Commits

Reviewing files that changed from the base of the PR and between b920cc7 and bf0295e.

📒 Files selected for processing (6)

• pkg/clickhouse/migrations/20250903085516_init.sql
• pkg/clickhouse/migrations/20260306000000.sql
• pkg/clickhouse/schema/000_legacy.sql
• pkg/clickhouse/schema/001_key_verifications_raw_v2.sql
• pkg/clickhouse/schema/006_ratelimits_raw_v2.sql
• pkg/clickhouse/schema/012_api_requests_raw_v2.sql

💤 Files with no reviewable changes (5)

• pkg/clickhouse/schema/006_ratelimits_raw_v2.sql
• pkg/clickhouse/schema/001_key_verifications_raw_v2.sql
• pkg/clickhouse/schema/012_api_requests_raw_v2.sql
• pkg/clickhouse/schema/000_legacy.sql
• pkg/clickhouse/migrations/20250903085516_init.sql

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@pkg/clickhouse/migrations/20250911070454.sql`:
- Line 209: The change to the materialized view in migration 20250911070454.sql
will not affect clusters that already ran that migration; create a new forward
migration that drops the existing materialized view `ratelimits_last_used_mv_v2`
and recreates it with the updated definition targeting `ratelimits_last_used_v2`
(SELECT workspace_id, namespace_id, identifier, maxSimpleState(time) AS time
FROM default.ratelimits_raw_v2 GROUP BY ...), and include a backfill step or
one-time populate of `ratelimits_last_used_v2` as needed so already-migrated
environments get the new MV behavior without editing the old migration file.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 12ccce9c-ba7a-43d0-9483-81cdbf803d50

📥 Commits

Reviewing files that changed from the base of the PR and between bf0295e and 898d9eb.

📒 Files selected for processing (4)

• pkg/clickhouse/migrations/20250911070454.sql
• pkg/clickhouse/migrations/20250925091254.sql
• pkg/clickhouse/migrations/20251010160229.sql
• pkg/clickhouse/migrations/20251125075943.sql

💤 Files with no reviewable changes (3)

• pkg/clickhouse/migrations/20250925091254.sql
• pkg/clickhouse/migrations/20251010160229.sql
• pkg/clickhouse/migrations/20251125075943.sql