Refactor database schema to use UUIDs for primary keys and foreign keys

[Thushani-Jayasekera]

• Updated the schema for organizations, projects, applications, artifacts, rest_apis, subscription_plans, subscriptions, gateways, gateway_custom_policies, gateway_custom_policy_usages, gateway_tokens, deployments, deployment_status, and association_mappings tables to replace VARCHAR(40) with UUID for uuid and related foreign key fields.
• Added new indexes for improved query performance on various tables, including api_keys, gateway_custom_policy_usages, and events.

[coderabbitai]

📝 Walkthrough

Database Schema Refactoring to UUID Identifiers

This pull request refactors the database schema to use UUID types for primary keys and foreign key references across the platform. The changes are applied consistently across PostgreSQL, SQLite, and generic SQL schema files.

UUID Migration

The refactoring converts VARCHAR(40) identifier columns to native UUID types across 14 core tables:

• Organizations, projects, applications, and artifacts
• REST APIs, subscription plans, and subscriptions
• Gateways, gateway custom policies, gateway tokens, and gateway state tracking
• Deployments and deployment status tracking
• Association mappings and developer portals
• LLM providers, proxies, and related services (MCP, WebSub, WebBroker)
• API keys and application associations

The gateway_tokens table is redefined to use gateway_uuid as a foreign key reference to gateways(uuid).

Performance Improvements

New indexes are added to optimize common query patterns:

• API key lookups by status and expiration
• Gateway custom policy usage queries by API
• MCP proxy lookups by project
• REST API filtering by lifecycle status
• Subscription plan filtering by status
• Event entity tracking by type and ID

Referential Integrity

A foreign key constraint is added to the gateway_states table linking gateway_id to gateways(uuid) with cascading deletes.

The publication_mappings table constraint is simplified by removing a redundant uniqueness constraint while preserving the primary key enforcement.

Walkthrough

The PostgreSQL schema (schema.postgres.sql) migrates all identifier columns across 25+ core tables—including organizations, projects, applications, artifacts, REST APIs, subscription plans, subscriptions, gateways, gateway custom policies, gateway tokens, deployments, deployment status, association mappings, dev portals, publication mappings, LLM-related tables, MCP/WebSub/WebBroker proxies, API keys, and application mapping tables—from VARCHAR(40) to the native UUID type. The gateway_tokens table is also restructured with a proper UUID-typed FK referencing gateways(uuid). Across all three schema files (PostgreSQL, generic SQL, SQLite), the redundant UNIQUE constraint is removed from publication_mappings, a referential integrity FK (ON DELETE CASCADE) is added to gateway_states, and several new indexes are added for api_keys, gateway_custom_policy_usages, mcp_proxies, rest_apis, subscription_plans, and events.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The PR description is incomplete. It mentions the schema changes and new indexes but lacks required template sections including Purpose (why), Goals, Approach, User stories, Documentation, Automation tests, Security checks, Samples, Related PRs, and Test environment.	Complete the PR description using the repository template. Add sections explaining the business rationale, implementation approach, testing methodology, security considerations, and test environment details.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and accurately summarizes the main change: refactoring database schema to use UUIDs for primary and foreign keys, which aligns with the extensive schema modifications across multiple tables.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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 unit tests (beta)

• Create PR with unit tests

---

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]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

platform-api/src/internal/database/schema.postgres.sql (1)

469-486: ⚠️ Potential issue | 🔴 Critical

Align gateway ID column types in schema.

gateway_states.gateway_id and events.gateway_id are TEXT, but the foreign key at line 473 references gateways(uuid), which is UUID. PostgreSQL enforces type compatibility for foreign keys; this mismatch will prevent schema creation. Change both columns to UUID:

• Line 470: gateway_id UUID PRIMARY KEY
• Line 477: gateway_id UUID NOT NULL

Proposed fix

 CREATE TABLE IF NOT EXISTS gateway_states (
-    gateway_id TEXT PRIMARY KEY,
+    gateway_id UUID PRIMARY KEY,
     version_id TEXT NOT NULL DEFAULT '',
     updated_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
     FOREIGN KEY (gateway_id) REFERENCES gateways(uuid) ON DELETE CASCADE
 );

 CREATE TABLE IF NOT EXISTS events (
-    gateway_id TEXT NOT NULL,
+    gateway_id UUID NOT NULL,
     processed_timestamp TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
     originated_timestamp TIMESTAMPTZ NOT NULL,
     entity_type TEXT NOT NULL,

🤖 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 `@platform-api/src/internal/database/schema.postgres.sql` around lines 469 -
486, The gateway_id columns in both the gateway_states and events tables are
defined as TEXT type, but the foreign key constraint in gateway_states
references gateways(uuid) which is a UUID type, causing a type mismatch that
will prevent schema creation. PostgreSQL requires foreign key columns to have
compatible types with their referenced columns. Change the gateway_id column in
the gateway_states table from TEXT PRIMARY KEY to UUID PRIMARY KEY, and change
the gateway_id column in the events table from TEXT NOT NULL to UUID NOT NULL to
align with the UUID type in the gateways table and ensure proper foreign key
relationships.

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

Outside diff comments:
In `@platform-api/src/internal/database/schema.postgres.sql`:
- Around line 469-486: The gateway_id columns in both the gateway_states and
events tables are defined as TEXT type, but the foreign key constraint in
gateway_states references gateways(uuid) which is a UUID type, causing a type
mismatch that will prevent schema creation. PostgreSQL requires foreign key
columns to have compatible types with their referenced columns. Change the
gateway_id column in the gateway_states table from TEXT PRIMARY KEY to UUID
PRIMARY KEY, and change the gateway_id column in the events table from TEXT NOT
NULL to UUID NOT NULL to align with the UUID type in the gateways table and
ensure proper foreign key relationships.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: fb3b5d7d-e096-4c95-bd5e-0c70aef5eaf8

📥 Commits

Reviewing files that changed from the base of the PR and between 01d2cb2 and 6443b1c.

📒 Files selected for processing (3)

• platform-api/src/internal/database/schema.postgres.sql
• platform-api/src/internal/database/schema.sql
• platform-api/src/internal/database/schema.sqlite.sql