chore(api): fix Alembic offline migration compatibility (#24795)

This PR fixes Alembic offline mode (`--sql` flag) by ensuring data migration functions only execute in online mode. When running in offline mode, these functions now skip data operations and output informational comments to the generated SQL.

.github/workflows/db-migration-test.yml

@@ -34,6 +34,12 @@ jobs:
 
       - name: Install dependencies
         run: uv sync --project api
+      - name: Ensure Offline migration are supported
+        run: |
+          # upgrade
+          uv run --directory api flask db upgrade 'base:head' --sql
+          # downgrade
+          uv run --directory api flask db downgrade 'head:base' --sql
 
       - name: Prepare middleware env
         run: |

api/migrations/versions/2025_08_09_1553-e8446f481c1e_add_provider_credential_pool_support.py

@@ -5,7 +5,7 @@ Revises: 8bcc02c9bd07
 Create Date: 2025-08-09 15:53:54.341341
 
 """
-from alembic import op
+from alembic import op, context
 from libs.uuid_utils import uuidv7
 import models as models
 import sqlalchemy as sa
@@ -43,7 +43,15 @@ def upgrade():
     with op.batch_alter_table('load_balancing_model_configs', schema=None) as batch_op:
         batch_op.add_column(sa.Column('credential_id', models.types.StringUUID(), nullable=True))
 
+    if not context.is_offline_mode():
         migrate_existing_providers_data()
+    else:
+        op.execute(
+            '-- [IMPORTANT] Data migration skipped!!!\n'
+            "-- You should manually run data migration function `migrate_existing_providers_data`\n"
+            f"-- inside file {__file__}\n"
+            "-- Please review the migration script carefully!"
+        )
 
     # Remove encrypted_config column from providers table after migration
     with op.batch_alter_table('providers', schema=None) as batch_op:
@@ -119,7 +127,16 @@ def downgrade():
         batch_op.add_column(sa.Column('encrypted_config', sa.Text(), nullable=True))
 
     # Migrate data back from provider_credentials to providers
+
+    if not context.is_offline_mode():
         migrate_data_back_to_providers()
+    else:
+        op.execute(
+            '-- [IMPORTANT] Data migration skipped!!!\n'
+            "-- You should manually run data migration function `migrate_data_back_to_providers`\n"
+            f"-- inside file {__file__}\n"
+            "-- Please review the migration script carefully!"
+        )
 
     # Remove credential_id columns
     with op.batch_alter_table('load_balancing_model_configs', schema=None) as batch_op:

api/migrations/versions/2025_08_13_1605-0e154742a5fa_add_provider_model_multi_credential.py

@@ -6,7 +6,7 @@ Create Date: 2025-08-13 16:05:42.657730
 
 """
 
-from alembic import op
+from alembic import op, context
 from libs.uuid_utils import uuidv7
 import models as models
 import sqlalchemy as sa
@@ -48,8 +48,16 @@ def upgrade():
     with op.batch_alter_table('load_balancing_model_configs', schema=None) as batch_op:
         batch_op.add_column(sa.Column('credential_source_type', sa.String(length=40), nullable=True))
 
+    if not context.is_offline_mode():
         # Migrate existing provider_models data
         migrate_existing_provider_models_data()
+    else:
+        op.execute(
+            '-- [IMPORTANT] Data migration skipped!!!\n'
+            "-- You should manually run data migration function `migrate_existing_provider_models_data`\n"
+            f"-- inside file {__file__}\n"
+            "-- Please review the migration script carefully!"
+        )
 
     # Remove encrypted_config column from provider_models table after migration
     with op.batch_alter_table('provider_models', schema=None) as batch_op:
@@ -132,8 +140,16 @@ def downgrade():
     with op.batch_alter_table('provider_models', schema=None) as batch_op:
         batch_op.add_column(sa.Column('encrypted_config', sa.Text(), nullable=True))
 
+    if not context.is_offline_mode():
         # Migrate data back from provider_model_credentials to provider_models
         migrate_data_back_to_provider_models()
+    else:
+        op.execute(
+            '-- [IMPORTANT] Data migration skipped!!!\n'
+            "-- You should manually run data migration function `migrate_data_back_to_provider_models`\n"
+            f"-- inside file {__file__}\n"
+            "-- Please review the migration script carefully!"
+        )
 
     with op.batch_alter_table('provider_models', schema=None) as batch_op:
         batch_op.drop_column('credential_id')