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

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 runs before 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 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 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 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 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 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 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 creates indexes and stored functions for the admin dashboard's revenue, churn, and generation-volume visualizations.

Migration 8: Case Favorites

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 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 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 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.

# 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:

# 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	Credit system foundation
supabase/migrations/20260509090000_membership_billing.sql	Subscription and payment infrastructure
supabase/migrations/20260512090000_google_account_center.sql	Enhanced generation usage controls
supabase/migrations/20260721090000_alipay_webpay.sql	Alipay payment processing
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) 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}