IBM
diff --git a/‎mcpgateway/alembic/env.py
Lines changed: 41 additions & 0 deletions b/‎mcpgateway/alembic/env.py
Lines changed: 41 additions & 0 deletions
diff --git a/‎mcpgateway/alembic/versions/b77ca9d2de7e_uuid_pk_and_slug_refactor.py
Lines changed: 88 additions & 0 deletions b/‎mcpgateway/alembic/versions/b77ca9d2de7e_uuid_pk_and_slug_refactor.py
Lines changed: 88 additions & 0 deletions
@@ -1,4 +1,45 @@
 # -*- coding: utf-8 -*-
+"""Alembic environment configuration for database migrations.
+
+Copyright 2025
+SPDX-License-Identifier: Apache-2.0
+Authors: Mihai Criveti, Madhav Kandukuri
+
+This module configures the Alembic migration environment for the MCP Gateway
+application. It sets up both offline and online migration modes, configures
+logging, and establishes the database connection parameters.
+
+The module performs the following key functions:
+- Configures Alembic to locate migration scripts in the mcpgateway package
+- Sets up Python logging based on the alembic.ini configuration
+- Imports the SQLAlchemy metadata from the application models
+- Configures the database URL from application settings
+- Provides functions for running migrations in both offline and online modes
+
+Offline mode generates SQL scripts without connecting to the database, while
+online mode executes migrations directly against a live database connection.
+
+Attributes:
+    config (Config): The Alembic configuration object loaded from alembic.ini.
+    target_metadata (MetaData): SQLAlchemy metadata object containing all
+        table definitions from the application models.
+
+Examples:
+    Running migrations in offline mode::
+
+        alembic upgrade head --sql
+
+    Running migrations in online mode::
+
+        alembic upgrade head
+
+    The module is typically not imported directly but is used by Alembic
+    when executing migration commands.
+
+Note:
+    This file is automatically executed by Alembic and should not be
+    imported or run directly by application code.
+"""
 # Standard
 from importlib.resources import files
 from logging.config import fileConfig
 
@@ -31,13 +31,68 @@
 # Helpers
 # ──────────────────────────────────────────────────────────────────────────────
 def _use_batch() -> bool:
+    """Determine if batch operations are required for the current database.
+
+    SQLite requires batch mode for certain ALTER TABLE operations like dropping
+    columns or altering column types. This helper checks the database dialect
+    to determine if batch operations should be used.
+
+    Returns:
+        bool: True if the database is SQLite (requires batch mode), False otherwise.
+
+    Examples:
+        >>> # In a SQLite context
+        >>> _use_batch()  # doctest: +SKIP
+        True
+        >>> # In a PostgreSQL context
+        >>> _use_batch()  # doctest: +SKIP
+        False
+    """
     return op.get_bind().dialect.name == "sqlite"
 
 
 # ──────────────────────────────────────────────────────────────────────────────
 # Upgrade
 # ──────────────────────────────────────────────────────────────────────────────
 def upgrade() -> None:
+    """Migrate database schema from integer to UUID primary keys with slugs.
+
+    This migration performs a comprehensive schema transformation in three stages:
+
+    Stage 1 - Add placeholder columns:
+        - Adds UUID columns (id_new) to gateways, tools, and servers
+        - Adds slug columns for human-readable identifiers
+        - Adds columns to preserve original tool names before prefixing
+
+    Stage 2 - Data migration:
+        - Generates UUIDs for all primary keys
+        - Creates slugs from names (e.g., "My Gateway" -> "my-gateway")
+        - Prefixes tool names with gateway slugs (e.g., "my-tool" -> "gateway-slug-my-tool")
+        - Updates all foreign key references to use new UUIDs
+
+    Stage 3 - Schema finalization:
+        - Drops old integer columns
+        - Renames new UUID columns to replace old ones
+        - Recreates primary keys and foreign key constraints
+        - Adds unique constraints on slugs and URLs
+
+    The migration is designed to work with both SQLite (using batch operations)
+    and other databases. It preserves all existing data relationships while
+    transforming the schema.
+
+    Note:
+        - Skips migration if database is fresh (no gateways table)
+        - Uses batch operations for SQLite compatibility
+        - Commits data changes before schema alterations
+
+    Examples:
+        >>> # Running the migration
+        >>> upgrade()  # doctest: +SKIP
+        Fresh database detected. Skipping migration.
+        >>> # Or for existing database
+        >>> upgrade()  # doctest: +SKIP
+        Existing installation detected. Starting data and schema migration...
+    """
     bind = op.get_bind()
     sess = Session(bind=bind)
     inspector = sa.inspect(bind)
@@ -402,6 +457,39 @@ def upgrade() -> None:
 
 
 def downgrade() -> None:
+    """Revert database schema from UUID primary keys back to integers.
+
+    This downgrade reverses the UUID migration but with significant limitations:
+    - Schema structure is restored but data is NOT preserved
+    - All UUID values and slug fields are lost
+    - Foreign key relationships are broken (columns will be NULL)
+    - Original integer IDs cannot be recovered
+
+    The downgrade operates in reverse order of the upgrade:
+
+    Stage 1 - Revert schema changes:
+        - Drops UUID-based constraints and keys
+        - Renames UUID columns back to temporary names
+        - Re-adds integer columns (empty/NULL)
+
+    Stage 2 - Data migration (skipped):
+        - Original integer IDs cannot be restored from UUIDs
+        - Relationships cannot be reconstructed
+
+    Stage 3 - Remove temporary columns:
+        - Drops all UUID and slug columns
+        - Leaves database with original schema but no data
+
+    Warning:
+        This downgrade is destructive and should only be used if you need
+        to revert the schema structure. All data in affected tables will
+        need to be manually restored from backups.
+
+    Examples:
+        >>> # Running the downgrade
+        >>> downgrade()  # doctest: +SKIP
+        # Schema reverted but data is lost
+    """
     # ── STAGE 1 (REVERSE): Revert Schema to original state ─────────────────
     # This reverses the operations from STAGE 3 of the upgrade.
     # Data from the new columns will be lost, which is expected.