---
name: supabase-migration-63f571541c0b
description: >-
  Supabase migration 檔與 schema DDL 規範。觸發：supabase migration new、CREATE FUNCTION / ALTER TABLE / CREATE INDEX。NOT for RLS policy 的內容設計（走 supabase-rls）。
---


# Supabase Migration 規範

核心規則（`supabase migration new`、search_path、SECURITY DEFINER 不放 exposed schema、view `security_invoker`、不改已 apply 的 migration、timestamp 契約、MCP 禁 DDL、reset → lint → gen types → typecheck、advisors、pending migration 分類、expand-contract）在 `rules/modules/db-schema/supabase/migration.md`，本 skill 不複述，只補實作細節。

> **PR-isolated DB preview env / schema diff gate / production data sanitization** 規約見 `rules/core/db-preview-env.md`（capability + safety contract）與 `rules/modules/db-runtime/supabase-self-hosted/preview-env.md`（self-host 實作層 + image trip-wires）。Cookbook 範本：`vendor/snippets/db-preview-env/`。

# SOP

## Phase 1 -- 建立 migration 檔

1. READ 讀取 module rule `rules/modules/db-schema/supabase/migration.md`（或 runtime 已交付的同名規約；改 `supabase/migrations/**/*.sql` 時已自動載入就不重讀）。
2. DELEGATE 執行 `supabase migration new <topic>` 產生檔名；一個 migration 只放一個主題。

## Phase 2 -- 撰寫 DDL

1. READ 讀取 `rules/DDL撰寫慣例判準.md`。
2. WRITE 需要 `SECURITY DEFINER` 函式時，讀取 `templates/security-definer-function.md` 與 `templates/security-definer-function.example.md` 撰寫；要讓 PostgREST（Data API）呼叫時，再讀取 `templates/public-thin-wrapper.md` 與 `templates/public-thin-wrapper.example.md` 在 `public` 建 wrapper。
3. WRITE 其餘 DDL 依已載入規則撰寫；RLS policy 的內容設計轉 `supabase-rls` skill。

## Phase 3 -- 本機驗證

1. DELEGATE 依 module rule 對**每一個**新增或修改的 migration 跑 reset → lint → gen types → typecheck，再跑 `supabase db advisors` 並逐條處置 security 類 finding。
2. DELEGATE 檢查有沒有 migration 被改名：

   ```bash
   git diff --cached --diff-filter=R -- 'supabase/migrations/' | grep -q . && echo "BLOCK: migration renamed" || echo "OK"
   ```

   印 `BLOCK` 時 STOP，把檔名還原成 main 上的檔名，不 commit 新 timestamp（判準見 `migration.md` § Timestamp 不可變）。

## Phase 4 -- Production 韌性分類與 gate（self-host production）

1. DELEGATE 執行 `node scripts/postgrest-resilience/classify-migration.mjs <migration.sql>`（本 skill 目錄下的投影資源）；找不到投影資源時 **NEVER** 改用其他 runtime 的路徑猜一個，回報標準未送達並保留 evidence 要求。
2. THINK 讀取 `rules/Production韌性分類判準.md`，依分類器的 `overall` 決定 online、expand-contract 或 hard stop。
3. DELEGATE online 路線部署時執行 `node scripts/postgrest-resilience/ready-watch.mjs --url=<admin-ready-url>` 與 `node scripts/postgrest-resilience/smoke-runner.mjs --endpoint=<name=url>`，保存 `/ready`、smoke summary 與 PostgREST logs 作為 evidence。

## Phase 5 -- 疑難排解

1. READ 執行或部署遇錯時，讀取 `rules/疑難排解與Owner修復判準.md` 依症狀處置；owner 修復是 MCP 跑 DDL 的唯一例外，只照該 rule 的四步做。


## Claude host contract

The resource declaration projects helpers under `.claude/skills/supabase-migration/scripts/postgrest-resilience/`. Run each `.mjs` helper with Claude `Bash` and the Node runner from the repository cwd; preserve the returned terminal output as evidence.


---
Source attribution: YuDefine
Original project: https://github.com/YuDefine/nuxt-supabase-starter/blob/2987d936c8a6ea7f676c42528192416901bb3ee3/template/.claude/skills/supabase-migration/SKILL.md
License: MIT
License information: https://opensource.org/license/mit
Original upstream instructions; downloaded from Mega AI Hub.

## Upstream license notice

MIT License

Copyright (c) 2025-present YuDefine - 域定資訊工作室

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.



# Mega AI Hub resource metadata

Creator / publisher: YuDefine
Original project: https://github.com/YuDefine/nuxt-supabase-starter/blob/2987d936c8a6ea7f676c42528192416901bb3ee3/template/.claude/skills/supabase-migration/SKILL.md
Attribution basis: Source repository record

Fields of work: Development & Engineering
Roles: Backend Developer, Database Administrator, Data Engineer
Specialties: Database
Tools: Supabase
Country applicability: Country not specified
Classification basis: Source category, role and specialization labels
Instruction SHA-256: b418a79eb87bafb7001ea0e20b923a10ab62c08a74732b8426eeb3b1e0282ac8