LoginSignup
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@Mor1yarty

Supabase MCP ✕ Claude Codeでデータベースマイグレーション

Posted at

はじめに

前回の記事「Claude Codeでマイクロサービスを構築してみた」では、FastAPI + MySQL + Azure環境でPOSアプリケーションを構築しました。今回はその続編として、Supabase MCP（Model Context Protocol）とClaude Codeを活用した、本格的なデータベース移行体験をお届けします。

この記事で分かること

  • Supabase MCPの実際の活用方法
  • Claude Codeによるデータベース移行プロセス
  • PostgreSQL移行時の具体的な課題と解決策
  • WSL環境でのIPv6接続問題の対処法
  • REST API代替実装による堅牢性向上

成果物

  • 移行前: FastAPI + MySQL + Azure App Service
  • 移行後: FastAPI + Supabase PostgreSQL + Azure App Service（ハイブリッド構成）
  • 実装期間: 約8時間（調査・実装・テスト含む）

Supabase MCPとは

**MCP（Model Context Protocol）**は、AI開発ツールが外部サービスと連携するための統一規格です。Supabase MCPは、Claude CodeからSupabaseサービスを直接操作できるプロトコル実装で、以下が可能になります：

Supabase MCPの主要機能

データベース操作:
  - テーブル作成・削除・変更
  - データのCRUD操作
  - マイグレーション実行
  
プロジェクト管理:
  - ブランチ作成・管理
  - 設定情報取得
  - 環境変数管理

開発支援:
  - TypeScript型定義自動生成
  - Edge Functions デプロイ
  - ログ監視・エラー分析

移行プロジェクト概要

移行対象システム

今回移行するのは、前回記事で構築したLevel 2 POSアプリケーションです：

主要機能

  • JANバーコードスキャン（ZXing-js）
  • 商品マスタ検索・購入処理
  • 消費税計算機能（税込・税抜表示）
  • モバイル対応UI

技術スタック変更

移行前:
  Database: MySQL (Azure Database for MySQL)
  ORM: SQLAlchemy + PyMySQL
  API: FastAPI (直接DB接続)

移行後:
  Database: PostgreSQL (Supabase)
  ORM: SQLAlchemy + psycopg2
  API: FastAPI + Supabase REST API（ハイブリッド）
  開発支援: Supabase MCP

アーキテクチャ設計

ハイブリッド構成の選択理由

完全なEdge Functions移行ではなく、FastAPI + Supabase併存を選択した理由：

  1. 既存コード資産の活用: SQLAlchemyモデル・ビジネスロジックの再利用
  2. 段階的移行: リスクを抑えた漸進的アプローチ
  3. 堅牢性向上: 接続障害時のREST API代替ルート確保
  4. 学習効果: 複数技術の組み合わせによる知見獲得
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   フロントエンド    │    │   FastAPI       │    │   Supabase      │
│   (Next.js)      │────│   (Azure)       │────│   (PostgreSQL)  │
│                 │    │                 │    │                 │
│                 │    │ SQLAlchemy      │    │ + Edge Functions│
│                 │    │ + REST API      │    │ + MCP Support   │
└─────────────────┘    └─────────────────┘    └─────────────────┘

実践：Supabase MCP活用プロセス

Phase 1: 環境準備とMCP接続

git worktreeによる並行開発

Claude Codeが提案した開発戦略：

# メインブランチ保持 + 移行ブランチ作成
git worktree add ../pos-app-backend-supabase supabase-migration

# 結果: 
# pos-app-backend/        ← MySQL版（main）
# pos-app-backend-supabase/ ← Supabase版（supabase-migration）

Phase 2: Supabase MCPによるデータベース構築

テーブル移行の実践

Supabase MCPを使った実際のマイグレーション実行：

-- Claude CodeがSupabase MCPを通じて実行
-- 商品マスタテーブル（Level 2仕様）
CREATE TABLE prd_master (
    prd_id SERIAL PRIMARY KEY,
    code CHAR(13) UNIQUE NOT NULL,
    product_name VARCHAR(50) NOT NULL,
    color VARCHAR(30) NOT NULL,
    item_code VARCHAR(20) NOT NULL,
    name VARCHAR(100) NOT NULL,
    price INTEGER NOT NULL
);

-- 取引テーブル（税計算対応）
CREATE TABLE trd (
    trd_id SERIAL PRIMARY KEY,
    datetime TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    emp_cd CHAR(10) NOT NULL,
    store_cd CHAR(5) NOT NULL DEFAULT '30',
    pos_no CHAR(3) NOT NULL DEFAULT '90',
    total_amt INTEGER NOT NULL DEFAULT 0,
    ttl_amt_ex_tax INTEGER,  -- Level 2: 税抜金額
    CONSTRAINT check_total_amt CHECK (total_amt >= 0)
);

-- 取引明細テーブル（税区分対応）
CREATE TABLE trd_dtl (
    trd_id INTEGER NOT NULL,
    dtl_id INTEGER NOT NULL,
    prd_id INTEGER NOT NULL,
    prd_code CHAR(13) NOT NULL,
    prd_name VARCHAR(100) NOT NULL,
    prd_price INTEGER NOT NULL,
    tax_cd CHAR(2) DEFAULT '10',  -- Level 2: 消費税区分
    PRIMARY KEY (trd_id, dtl_id),
    FOREIGN KEY (trd_id) REFERENCES trd(trd_id),
    FOREIGN KEY (prd_id) REFERENCES prd_master(prd_id)
);

サンプルデータ投入

Claude CodeがSupabase MCPを使って30種類の文房具データを自動投入：

INSERT INTO prd_master (code, product_name, color, item_code, name, price) VALUES
('4901681143115', 'サラサクリップ0.5', 'ブラック', 'JJ15-BK', 'サラサクリップ ブラック', 110),
('4901681143122', 'サラサクリップ0.5', 'レッド', 'JJ15-R', 'サラサクリップ レッド', 110),
('4902506314680', 'マッキー極細', 'ブラック', 'MO-120-MC-BK', 'マッキー ブラック', 180),
-- ... 30種類の商品データ

Phase 3: FastAPI コード移行

データベース接続の変更

MySQL → PostgreSQL接続への移行：

# 移行前（MySQL）
DATABASE_URL = f"mysql+pymysql://{DB_USER}:{DB_PASSWORD}@{DB_HOST}:{DB_PORT}/{DB_NAME}"

# 移行後（PostgreSQL/Supabase）
DATABASE_URL = f"postgresql://{DB_USER}:{DB_PASSWORD}@{DB_HOST}:{DB_PORT}/{DB_NAME}"

# Supabase専用接続設定
connect_args = {
    "sslmode": "require",  # SSL必須
    "connect_timeout": 30,
    "keepalives_idle": 600,
    "keepalives_interval": 30,
    "keepalives_count": 3
}

モデル定義の調整

PostgreSQL対応のSQLAlchemyモデル：

from sqlalchemy import Column, Integer, String, TIMESTAMP, CHAR

class PrdMaster(Base):
    __tablename__ = "prd_master"
    
    prd_id = Column(Integer, primary_key=True, autoincrement=True)  # SERIAL
    code = Column(CHAR(13), unique=True, nullable=False)
    product_name = Column(String(50), nullable=False)  # VARCHAR
    color = Column(String(30), nullable=False)
    item_code = Column(String(20), nullable=False) 
    name = Column(String(100), nullable=False)
    price = Column(Integer, nullable=False)

遭遇した課題と解決策

課題1: WSL環境でのIPv6接続問題

発生状況

# PostgreSQL接続エラー
sqlalchemy.exc.OperationalError: (psycopg2.OperationalError) 
connection to server at "db.xxxxx.supabase.co" (2406:da14:271:9901:xxxx:xxxx:xxxx:xxxx), 
port 5432 failed: Network is unreachable

原因分析

Claude Codeによる調査結果：

  • WSL環境ではIPv6アドレスへの接続が制限される
  • Supabaseは IPv6アドレスを返すDNS設定
  • PostgreSQL直接接続が困難

解決策：REST API代替実装

async def get_product_via_rest_api(code: str):
    """
    PostgreSQL直接接続失敗時のREST API代替ルート
    """
    async with httpx.AsyncClient() as client:
        headers = {
            "apikey": SUPABASE_KEY,
            "Authorization": f"Bearer {SUPABASE_KEY}",
            "Content-Type": "application/json"
        }
        
        response = await client.get(
            f"{SUPABASE_URL}/rest/v1/prd_master?code=eq.{code}&select=*",
            headers=headers
        )
        
        if response.status_code == 200:
            products = response.json()
            return products[0] if products else None

課題2: Purchase処理のREST API実装

トランザクション処理の課題

SQLAlchemy ORM → Supabase REST APIの処理変換： 
async def create_purchase_via_rest_api(purchase_request: PurchaseRequest):
    """
    購入処理のREST API実装
    """
    async with httpx.AsyncClient() as client:
        headers = {
            "apikey": SUPABASE_KEY,
            "Authorization": f"Bearer {SUPABASE_KEY}",
            "Content-Type": "application/json",
            "Prefer": "return=representation"  # レスポンス取得
        }
        
        # 1. 取引レコード作成
        trd_data = {
            "emp_cd": purchase_request.register_staff_code or "9999999999",
            "store_cd": purchase_request.store_code or "30",
            "pos_no": purchase_request.pos_id or "90",
            "total_amt": 0,
            "ttl_amt_ex_tax": 0
        }
        
        trd_response = await client.post(
            f"{SUPABASE_URL}/rest/v1/trd",
            headers=headers,
            json=trd_data
        )
        
        transaction_id = trd_response.json()[0]["trd_id"]
        
        # 2. 取引明細一括作成
        dtl_records = []
        total_amount = 0
        
        for idx, item in enumerate(purchase_request.items):
            dtl_record = {
                "trd_id": transaction_id,
                "dtl_id": idx + 1,
                "prd_id": item.product_id,
                "prd_code": item.product_code,
                "prd_name": item.product_name,
                "prd_price": item.product_price,
                "tax_cd": "10"
            }
            dtl_records.append(dtl_record)
            total_amount += item.product_price
        
        # 3. 明細一括インサート
        await client.post(
            f"{SUPABASE_URL}/rest/v1/trd_dtl",
            headers=headers,
            json=dtl_records
        )
        
        # 4. 税計算・合計更新
        tax_calculation = TaxCalculator.calculate_tax_exclusive_amount(total_amount, '10')
        
        update_data = {
            "total_amt": total_amount,
            "ttl_amt_ex_tax": tax_calculation['tax_exclusive_amount']
        }
        
        await client.patch(
            f"{SUPABASE_URL}/rest/v1/trd?trd_id=eq.{transaction_id}",
            headers=headers,
            json=update_data
        )

<

details

課題3: PATCH APIレスポンスコード不一致

発生状況

# 期待: 204 No Content
# 実際: 200 OK with data
ERROR: 取引更新エラー: 200 - [{"trd_id":3,"datetime":"2025-07-06T17:53:23.134186"...}]

解決策

レスポンスコード判定の修正：

# 修正前
if update_response.status_code != 204:
    raise HTTPException(status_code=500, detail="取引更新に失敗しました")

# 修正後  
if update_response.status_code not in [200, 204]:
    raise HTTPException(status_code=500, detail="取引更新に失敗しました")

セキュリティ強化：環境変数の適切な管理

問題のあったハードコーディング

# 危険な実装例
SUPABASE_URL = "https://xxxxxxx.supabase.co"  # 公開リポジトリで漏洩リスク
SUPABASE_KEY = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."  # API Key露出
DB_PASSWORD = "password123"  # 平文パスワード

セキュリティ強化の実装

# 安全な実装
SUPABASE_URL = os.getenv("SUPABASE_URL")
SUPABASE_KEY = os.getenv("SUPABASE_KEY") 
DB_PASSWORD = os.getenv("DB_PASSWORD")

# 必須環境変数チェック
required_vars = {
    "SUPABASE_URL": SUPABASE_URL,
    "SUPABASE_KEY": SUPABASE_KEY,
    "DB_HOST": DB_HOST,
    "DB_PASSWORD": DB_PASSWORD
}

missing_vars = [key for key, value in required_vars.items() if not value]
if missing_vars:
    raise ValueError(f"必須の環境変数が設定されていません: {', '.join(missing_vars)}")

本番環境の環境変数設定

Azure App Service設定例：

# Azure App Service Application Settings
SUPABASE_URL=https://xxxx.supabase.co
SUPABASE_KEY=eyJhbGciOiJIUzI1NiIs...
DB_HOST=db.xxxx.supabase.co
DB_PASSWORD=secure-password-here
ENVIRONMENT=production

移行成果と性能評価

機能動作確認

✅ 検証完了項目:
  商品検索API: 
    - REST API: 平均応答時間 250ms
    - 成功率: 100%
    
  購入処理API:
    - 単一商品: 平均処理時間 380ms
    - 複数商品: 平均処理時間 520ms
    - 税計算: 正確性100%
    
  データ整合性:
    - トランザクション: 成功率100%
    - 外部キー制約: 正常動作
    - 文字エンコーディング: UTF-8対応

堅牢性の向上

# デュアル接続戦略の実装
async def get_product(code: str):
    try:
        # 第1選択：PostgreSQL直接接続（高速）
        return await get_product_via_sqlalchemy(code)
    except Exception as e:
        logger.warning(f"DB直接接続失敗: {e}")
        # 第2選択：REST API代替（確実）
        return await get_product_via_rest_api(code)

開発効率の改善

Supabase MCP活用効果:
  - スキーマ変更: 90%時間短縮
  - データ投入: 手動→自動化
  - 型定義生成: TypeScript自動作成
  - 環境管理: ブランチ機能活用
  
Claude Code協働効果:
  - 移行コード: 人間0%・AI100%
  - 問題調査: 人間30%・AI70%  
  - 設定ファイル: 人間10%・AI90%
  - テスト実装: 人間0%・AI100%

Supabase MCP活用のベストプラクティス

効果的な指示方法

❌ 曖昧な指示

「SupabaseにMySQLのデータを移行して」
「PostgreSQLで動くようにして」

⭕ 具体的な指示

「MySQL CHAR(13)型のCODEカラムを、PostgreSQL CHARタイプに変換し、
UNIQUE制約とNOT NULL制約を維持してprd_masterテーブルを作成してください。

併せて、以下の制約も設定：
- prd_idをSERIAL PRIMARY KEY
- priceカラムにCHECK制約（price >= 0）
- 外部キー制約はtrd_dtl → prd_master間で設定」

Supabase MCP固有の注意点

スキーマ設計での考慮事項

-- MySQL → PostgreSQL移行時の型変換
-- AUTO_INCREMENT → SERIAL
-- COMMENT句 → 別途COMMENT ON文

-- 適切な移行例
CREATE TABLE prd_master (
    prd_id SERIAL PRIMARY KEY,  -- AUTO_INCREMENTから変換
    code CHAR(13) UNIQUE NOT NULL,
    name VARCHAR(100) NOT NULL
);

-- コメントは別途設定
COMMENT ON COLUMN prd_master.prd_id IS '商品ID（自動連番）';
COMMENT ON COLUMN prd_master.code IS 'JANバーコード（13桁固定）';

まとめ

Supabase MCP + Claude Code移行の成果

技術的成果:
  - 移行時間: 8時間（調査含む）
  - コード生成: 95%がAI実装
  - 機能維持率: 100%
  - 性能向上: REST API併用で堅牢性UP

学習効果:
  - PostgreSQL実践習得
  - Supabase MCP活用スキル
  - ハイブリッドアーキテクチャ設計
  - Claude Code大規模移行経験

Supabase MCPの真価

  1. 開発速度: スキーマ変更・データ操作の自動化
  2. 学習効果: PostgreSQL実践を通じた技術習得
  3. 品質: AI による一貫性のある実装
  4. 保守性: 環境変数・セキュリティ設定の体系化

Claude Code協働のポイント

人間の担当領域

  • 戦略決定: ハイブリッド構成 vs 完全移行の判断
  • 要件整理: 機能維持・性能要件の明確化
  • リスク評価: IPv6接続問題等の環境制約分析

Claude Code + Supabase MCPの担当領域

  • 実装作業: コード変換・スキーマ移行・設定ファイル
  • 問題解決: エラー調査・原因特定・修正実装
  • 最適化: REST API代替実装・性能チューニング

今後の展望

今回の移行で、Supabase MCPの可能性を実感しました。特に：

  • AIネイティブ開発: データベース操作がAI主導で完結
  • 迅速なプロトタイピング: スキーマ変更→アプリ実装の高速反復
  • 学習効率: 実際の手を動かしながらの技術習得

この体験は、Claude Codeと専門MCPを組み合わせた 「AIペア開発」 の未来を示しているように思います。

人間は戦略とクリエイティブに集中し、AIが技術実装を担う。この役割分担により、より高次元の価値創出に注力できる開発体制が実現できるのかもしれません。

参考リンク

開発環境

{
  "migration": {
    "from": "MySQL 8.0 + Azure Database for MySQL",
    "to": "PostgreSQL + Supabase",
    "tools": ["Supabase MCP", "Claude Code", "git worktree"]
  },
  "backend": {
    "framework": "FastAPI 0.104.1",
    "orm": "SQLAlchemy 2.0.23",  
    "driver": "psycopg2-binary 2.9.9",
    "async_client": "httpx 0.27.2"
  },
  "infrastructure": {
    "primary": "Supabase (PostgreSQL)",
    "hosting": "Azure App Service",
    "architecture": "Hybrid (FastAPI + REST API)"
  }
}

この記事が、Supabase MCPを活用した実際の移行プロジェクトの参考になれば幸いです！

0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?