# Complete Supabase Migration Sequence for awesome-gpt-image-2: Required vs Optional Migrations

> Learn the complete Supabase migration sequence for awesome-gpt-image-2. Apply core migrations 1-8 and optional migrations 9-11 for Watcha OAuth, Alipay, or paid-community features.

- Repository: [苍何/awesome-gpt-image-2](https://github.com/freestylefly/awesome-gpt-image-2)
- Tags: migration-guide
- Published: 2026-09-02

---

**Apply migrations 1–8 for core functionality, then add 9–11 only if you enable Watcha OAuth, Alipay payments, or paid-community features.**

The `awesome-gpt-image-2` repository by `freestylefly` manages its database schema through timestamped SQL migrations in the `supabase/migrations/` directory. Each file prefix (`YYYYMMDDhhmmss`) determines execution order, ensuring dependent objects exist before later scripts reference them. The sequence spans from foundational credit tables to optional payment and community features.

## Understanding the Migration Numbering System

Supabase migrations use UTC timestamps as version control. The CLI applies files in ascending chronological order, making the numeric prefix critical for dependencies. For example, [`202605090001_user_credits.sql`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/202605090001_user_credits.sql) runs before [`202605090002_auth_policy_lints.sql`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/202605090002_auth_policy_lints.sql) because `202605090001` < `202605090002`.

## Core Migrations 1–8 (Required for All Deployments)

These eight migrations establish the minimal viable schema for running the application.

### Migration 1: User Credits Foundation

[`202605090001_user_credits.sql`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/202605090001_user_credits.sql) creates the three core tables and credit-handling functions:

- `profiles` – user identity and metadata
- `credit_transactions` – ledger for credit balance changes
- `generation_reservations` – pending credit holds during image generation

This migration also installs helper functions for atomic credit debits and reservation management.

### Migration 2: Row-Level Security Policies

[`202605090002_auth_policy_lints.sql`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/202605090002_auth_policy_lints.sql) locks down the core tables with **RLS (Row-Level Security)** policies. Without this, authenticated users could read or modify any profile, transaction, or reservation.

### Migration 3: Membership Index Optimization

[`20260509091500_membership_plan_index.sql`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/20260509091500_membership_plan_index.sql) adds a single index on `user_memberships.plan_id`. This small performance optimization runs before the billing tables exist, preparing for the heavy membership queries to come.

### Migration 4: Billing Infrastructure

[`20260509090000_membership_billing.sql`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/20260509090000_membership_billing.sql) introduces the subscription economy:

- `membership_plans` – recurring subscription tiers
- `credit_packs` – one-time credit purchases
- `user_memberships` – links users to active plans
- `payment_orders` – tracks pending and completed payments

Security policies for these tables are included in the same file.

### Migration 5: Enhanced Generation Controls

[`20260512090000_google_account_center.sql`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/20260512090000_google_account_center.sql) performs two upgrades:

1. Replaces `reserve_generation_usage()` with a version supporting **forced credit consumption** (bypassing free tiers when needed)
2. Adds a usage-reporting helper view for account dashboards

### Migration 6: Product Catalog Seeding

[`20260512143000_pricing_admin_metrics.sql`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/20260512143000_pricing_admin_metrics.sql) populates `membership_plans` and `credit_packs` with default pricing. Without this data, the billing UI shows empty product lists.

### Migration 7: Admin Analytics

[`20260513095141_admin_metrics_charts.sql`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/20260513095141_admin_metrics_charts.sql) creates indexes and stored functions for the admin dashboard's revenue, churn, and generation-volume visualizations.

### Migration 8: Case Favorites

[`20260515090000_case_favorites.sql`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/20260515090000_case_favorites.sql) adds the `case_favorites` table with RLS policies, enabling users to bookmark generated image cases for later reference.

## Optional Migrations 9–11 (Feature-Specific)

These three migrations depend on external integrations or premium features. Skip them if you don't need the capability.

### Migration 9: Watcha OAuth (Optional)

[`20260528090000_watcha_oauth_accounts.sql`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/20260528090000_watcha_oauth_accounts.sql) creates `watcha_accounts` for Korean streaming service authentication. **Required only if** you enable Watcha login as an identity provider.

### Migration 10: Alipay Web Payments (Optional)

[`20260721090000_alipay_webpay.sql`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/20260721090000_alipay_webpay.sql) extends the schema for Chinese mobile payments:

- Adds Alipay-specific columns to `payment_orders`
- Creates `alipay_notifications` for async webhook handling
- Implements `complete_alipay_order()` and `refund_alipay_order()` RPCs

**Skip unless** you process payments through Alipay.

### Migration 11: Paid Community (Optional)

[`20260722090000_paid_community.sql`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/20260722090000_paid_community.sql) enables monetized community features:

- Protected QR code generation
- Alipay onboarding flows for community creators
- Revenue sharing tables and functions

**Apply only when** deploying the paid-community product variant.

## Applying the Complete Supabase Migration Sequence

Use the Supabase CLI to deploy these in order. Core migrations must run sequentially; optional migrations can be added later without rebuilding the database.

```bash

# Reset local database (development only)

supabase db reset

# Core migrations 1-8 (mandatory)

supabase db push

# Or individually for troubleshooting:

supabase db push --file supabase/migrations/202605090001_user_credits.sql
supabase db push --file supabase/migrations/202605090002_auth_policy_lints.sql
supabase db push --file supabase/migrations/20260509091500_membership_plan_index.sql
supabase db push --file supabase/migrations/20260509090000_membership_billing.sql
supabase db push --file supabase/migrations/20260512090000_google_account_center.sql
supabase db push --file supabase/migrations/20260512143000_pricing_admin_metrics.sql
supabase db push --file supabase/migrations/20260513095141_admin_metrics_charts.sql
supabase db push --file supabase/migrations/20260515090000_case_favorites.sql

```

Add optional services post-deployment:

```bash

# Enable Watcha login

supabase db push --file supabase/migrations/20260528090000_watcha_oauth_accounts.sql

# Enable Alipay payments

supabase db push --file supabase/migrations/20260721090000_alipay_webpay.sql

# Enable paid community

supabase db push --file supabase/migrations/20260722090000_paid_community.sql

```

## Key Source Files in the awesome-gpt-image-2 Repository

| File Path | Purpose |
|-----------|---------|
| [`supabase/migrations/202605090001_user_credits.sql`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/supabase/migrations/202605090001_user_credits.sql) | Credit system foundation |
| [`supabase/migrations/20260509090000_membership_billing.sql`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/supabase/migrations/20260509090000_membership_billing.sql) | Subscription and payment infrastructure |
| [`supabase/migrations/20260512090000_google_account_center.sql`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/supabase/migrations/20260512090000_google_account_center.sql) | Enhanced generation usage controls |
| [`supabase/migrations/20260721090000_alipay_webpay.sql`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/supabase/migrations/20260721090000_alipay_webpay.sql) | Alipay payment processing |
| [`supabase/migrations/20260722090000_paid_community.sql`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/supabase/migrations/20260722090000_paid_community.sql) | Community monetization features |

All files reside in the `supabase/migrations/` directory and follow the timestamp naming convention enforced by the Supabase CLI.

## Summary

- **Migrations 1–8 are mandatory** for any functional deployment of awesome-gpt-image-2
- Timestamp prefixes enforce execution order regardless of filename
- **Migrations 9–11 are opt-in** based on your feature requirements
- The `supabase db push` command applies pending migrations automatically in chronological order
- Core tables (`profiles`, `credit_transactions`, `generation_reservations`) have no dependencies on optional features

## Frequently Asked Questions

### What happens if I skip migration 3 (membership plan index)?

The application will still function, but queries against `user_memberships.plan_id` will perform full table scans. This becomes noticeable at scale with hundreds of active memberships. The index is lightweight and safe to apply retroactively.

### Can I add migrations 10 and 11 without migration 9?

Yes. The Watcha OAuth migration ([`20260528090000_watcha_oauth_accounts.sql`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/20260528090000_watcha_oauth_accounts.sql)) has no schema dependencies on the Alipay or paid-community features. Each optional migration is self-contained and references only core tables from migrations 1–8.

### How do I verify which migrations have been applied?

Run `supabase db status` or query the `supabase_migrations.schema_migrations` table directly. The CLI tracks applied timestamps to prevent duplicate execution.

### What if I need to rollback a migration?

Supabase migrations are forward-only by design. To revert, create a new migration file that undoes the changes (DROP TABLE, REMOVE COLUMN, etc.) with a later timestamp. Test rollbacks in a staging environment before production deployment.