Database Setup

Overview

Supasheet includes pre-built migrations in /supabase/migrations/ that create all necessary schemas, tables, and functions. You just need to apply them.

Cloud Setup (Production)

Create Supabase Project

Go to supabase.com/dashboard
Click "New Project"
Choose organization and region
Set database password
Wait for project creation (~2 minutes)

Link Project

npx supabase link --project-ref your-project-ref

Get project-ref from dashboard URL: https://supabase.com/dashboard/project/[project-ref]

Push Migrations

npx supabase db push

Applies all local migrations to cloud database.

What Gets Created

The migrations in supabase/migrations/ build the complete platform layer:

Schemas: supasheet (Supasheet's meta + RBAC + audit/notifications/comments), plus public (yours to use)
Meta layer: supasheet.tables, columns, views, materialized_views — materialized views refreshed manually via select supasheet.refresh_metadata(); after DDL changes (see Database Schema)
Users: supasheet.users with triggers to mirror auth.users
RBAC: supasheet.user_roles, role_permissions, plus app_role and app_permission enums and helpers has_role() / has_permission()
Audit log: supasheet.audit_logs and audit_trigger_function()
Notifications: supasheet.notifications + user_notifications + create_notification() / resolver helpers
Comments: supasheet.comments and get_comments()
Templates: get_templates() and apply_template()
Custom types: FILE_OBJECT, FILE, EMAIL, TEL, RATING, PERCENTAGE, URL, DURATION, COLOR, AVATAR, RICH_TEXT
Storage buckets: public, personal, uploads (also used for account avatars, under uploads/auth/{uid}/...) with RLS policies
Discovery functions: get_schemas(), get_tables(), get_views(), get_columns(), get_charts(), get_widgets(), get_reports(), get_templates()

Schema Exposure (Required)

After applying migrations, you must expose the supasheet schema via the PostgREST API. The public schema is already exposed by default.

Edit Supabase Configuration

Add the supasheet schema to /supabase/config.toml:

[api]
schemas = ["public", "supasheet"]

This exposes:

public - Your application tables (exposed by default)
supasheet - All Supasheet internal tables including accounts, roles, permissions, dashboards, charts, and reports

Restart Supabase (Local)

For local development, restart Supabase to apply the configuration:

npx supabase stop
npx supabase start

Update Cloud Configuration (Production)

For cloud/production, update via the Supabase Dashboard:

Go to Project Settings → Data API
Find Exposed schemas section
Add supasheet to the list
Save changes

Important: Without exposing the supasheet schema, Supasheet won't be able to access authentication, authorization, configuration, dashboards, charts, and reports. The application will not function correctly.

Adding Your Own Tables

Create new migrations for your application tables:

npx supabase migration new add_products_table

Each migration that adds tables typically does six things — add permissions to the app_permission enum, create the table, enable RLS + policies, grant the new permissions to roles, (optionally) attach the audit trigger, and refresh the meta layer:

BEGIN;
ALTER TYPE supasheet.app_permission ADD VALUE IF NOT EXISTS 'store.products:select';
ALTER TYPE supasheet.app_permission ADD VALUE IF NOT EXISTS 'store.products:insert';
ALTER TYPE supasheet.app_permission ADD VALUE IF NOT EXISTS 'store.products:update';
ALTER TYPE supasheet.app_permission ADD VALUE IF NOT EXISTS 'store.products:delete';
COMMIT;

CREATE TABLE store.products (...);
ALTER TABLE store.products ENABLE ROW LEVEL SECURITY;
-- ... policies, grants, role assignments, audit trigger ...

-- Required last step: supasheet.tables/columns/views are materialized
-- views and won't pick up your new table until you refresh them.
select supasheet.refresh_metadata();

There are no event triggers watching for schema changes — select supasheet.refresh_metadata(); is the only thing that syncs the meta layer. Forgetting it is the most common reason a new table doesn't show up in the UI.

After running migrations, regenerate types:

npx supabase gen types typescript --local \
  --schema public --schema supasheet --schema store \
  > src/lib/database.types.ts

See Quickstart and Complete Example for full templates, and Examples in the repo for 12 reference domains.

Next Steps

Environment Variables — Configure the SPA
Deployment — Build & deploy
Production Checklist — Pre-launch sanity checks