Supabase Migration Sequence for GPT-Image-2 Website Deployment: 7 Essential Steps

The correct Supabase migration sequence for deploying the freestylefly/awesome-gpt-image-2 website requires executing seven SQL migration files in a specific dependency order to initialize authentication, credit tracking, and multi-provider billing systems.

The GPT-Image-2 project relies on a Supabase backend to manage user profiles, generation credits, and membership features. When deploying a fresh instance, applying the migrations in the exact sequence documented in the repository ensures that foreign-key constraints, row-level security (RLS) policies, and helper functions resolve correctly without dependency errors.

The Required Supabase Migration Sequence

The supabase/migrations/ directory contains SQL files that must execute in the following order. Because later migrations reference tables and functions created by earlier ones, they cannot be applied arbitrarily.

1. User Accounts and Credit Infrastructure

File: supabase/migrations/202605090001_user_credits.sql

This foundational migration creates the profiles, credit_transactions, and generation_reservations tables. It establishes the core RLS policies that secure user data and implements the reserve_generation_usage PostgreSQL function for atomic credit deduction during image generation.

2. Membership Billing and Stripe Integration

File: supabase/migrations/20260509090000_membership_billing.sql

Adds the plans, credit_packs, and stripe_orders tables required for the Stripe checkout flow. This migration references the profiles table to link purchases to users, which is why it must run after the user credits migration established the identity schema.

3. Alipay Web Payment Support

File: supabase/migrations/20260721090000_alipay_webpay.sql

Creates tables and RPC functions for handling Alipay-based credit purchases. This extends the billing system initialized in step 2 to support alternative payment methods for the credit marketplace.

4. Paid Community Access Control

File: supabase/migrations/20260722090000_paid_community.sql

Implements the paid_community flag and related policies for QR-code gated access. This migration assumes the existence of the profiles table and credit infrastructure from step 1 to verify payment status before granting community access.

5. Google Account Center Extensions

File: supabase/migrations/20260512090000_google_account_center.sql

Provides dashboards and forced-credit charging capabilities for super-admin users. It extends the credit model established in the first migration to support administrative usage summaries and manual credit adjustments.

6. Admin Pricing Metrics

File: supabase/migrations/20260512143000_pricing_admin_metrics.sql

Updates the catalog pricing (e.g., the $5 / 300 credits tier) and adds admin-dashboard metrics views. This depends on the credit tables and the Google account center schema to display accurate revenue statistics.

7. Case Favorites Feature

File: supabase/migrations/20260515090000_case_favorites.sql

Creates the favorites table that allows users to bookmark cases. As a user-specific feature that references the profiles table with foreign-key constraints, it runs last in the sequence.

Why the Supabase Migration Order Matters

Executing the Supabase migration sequence out of order causes PostgreSQL to throw foreign-key constraint violations because later scripts reference tables that do not yet exist.

• Foreign-key dependencies: The membership_billing and alipay_webpay migrations both reference the profiles table primary key established in user_credits.sql.
• RLS policy inheritance: Security policies defined in the first migration establish the ownership pattern that subsequent billing migrations extend for Stripe and Alipay records.
• Function availability: The reserve_generation_usage PL/pgSQL function created in the first migration is called by application code and later schema updates to atomically reserve generation credits.

According to the freestylefly/awesome-gpt-image-2 source code, the paid community feature specifically checks for the existence of credit infrastructure before enabling QR-code access controls.

Frontend Integration with Supabase Client

After applying the migrations, the frontend connects via src/supabaseClient.js. This wrapper reads Vite environment variables and initializes the client only when both VITE_SUPABASE_URL and VITE_SUPABASE_ANON_KEY are present.

import { createClient } from '@supabase/supabase-js';

const supabaseUrl = import.meta.env.VITE_SUPABASE_URL;
const supabaseAnonKey = import.meta.env.VITE_SUPABASE_ANON_KEY;

export const isSupabaseConfigured = Boolean(supabaseUrl && supabaseAnonKey);

export const supabase = isSupabaseConfigured
  ? createClient(supabaseUrl, supabaseAnonKey, {
      auth: {
        autoRefreshToken: true,
        detectSessionInUrl: true,
        persistSession: true,
      },
    })
  : null;

The isSupabaseConfigured boolean allows the application to degrade gracefully when environment variables are missing, preventing runtime crashes during local development or preview deployments.

Applying Migrations via the Supabase CLI

To execute the Supabase migration sequence in a production environment, use the Supabase CLI to push files individually in the required order:

# Authenticate with your project

supabase login
export SUPABASE_PROJECT_REF=your-project-ref

# Execute migrations sequentially

supabase db push --file supabase/migrations/202605090001_user_credits.sql
supabase db push --file supabase/migrations/20260509090000_membership_billing.sql
supabase db push --file supabase/migrations/20260721090000_alipay_webpay.sql
supabase db push --file supabase/migrations/20260722090000_paid_community.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/20260515090000_case_favorites.sql

Alternatively, if using supabase db push without the --file flag, ensure your local migration directory contains only these files in the correct order.

Querying the Database After Migration

Once deployed, use the following patterns to interact with the schema. To fetch a user's credit balance from the profiles table:

import { supabase, isSupabaseConfigured } from './supabaseClient';

async function loadUserCredits() {
  if (!isSupabaseConfigured) {
    console.error('Supabase not configured');
    return;
  }

  const { data: profile, error } = await supabase
    .from('profiles')
    .select('credit_balance')
    .eq('id', supabase.auth.user().id)
    .single();

  if (error) {
    console.error('Failed to fetch credits:', error);
  } else {
    console.log('Current credit balance:', profile.credit_balance);
  }
}

To reserve a generation slot using the RPC defined in the first migration:

async function reserveGeneration(caseId, prompt) {
  const userId = supabase.auth.user().id;
  const { data, error } = await supabase.rpc('reserve_generation_usage', {
    p_user_id: userId,
    p_case_id: caseId,
    p_prompt: prompt,
  });

  if (error) {
    console.error('Reservation failed:', error);
  } else {
    console.log('Reservation info:', data);
  }
}

Summary

• The Supabase migration sequence for GPT-Image-2 requires seven specific SQL files executed in the order: user credits, membership billing, Alipay support, paid community, Google account center, admin metrics, and case favorites.
• The 202605090001_user_credits.sql migration is foundational, creating the profiles table and reserve_generation_usage function that all subsequent features reference.
• Row-level security policies established in early migrations protect user data accessed by later billing and community features.
• The frontend relies on src/supabaseClient.js to manage Supabase connectivity using Vite environment variables, with automatic failover when credentials are absent.

Frequently Asked Questions

What happens if I run the Supabase migrations out of order?

Running migrations out of order causes PostgreSQL to throw foreign-key constraint errors because later scripts reference tables like profiles and credit_transactions that do not yet exist. Functions such as reserve_generation_usage will also be missing, causing the application to fail when attempting to deduct credits for image generation.

Can I skip the Alipay migration if I only use Stripe?

While you can technically skip 20260721090000_alipay_webpay.sql if you disable Alipay in your payment configuration, the paid_community migration that follows assumes the full billing schema is present. It is safer to apply all migrations and disable features via environment flags rather than omitting schema files, ensuring referential integrity remains intact.

How does the frontend handle missing Supabase configuration?

The supabaseClient.js file exports an isSupabaseConfigured boolean that checks for the presence of VITE_SUPABASE_URL and VITE_SUPABASE_ANON_KEY. When these are undefined, the client returns null, allowing the application to display fallback UI or local development mocks instead of throwing connection errors.

Which tables are created in the first migration?

The 202605090001_user_credits.sql migration creates three core tables: profiles (user account data and current balance), credit_transactions (audit log of all credit changes), and generation_reservations (temporary holds on credits during active image generation). It also defines the RLS policies and the reserve_generation_usage PL/pgSQL function for atomic credit management.

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