Skip to main content

Schema Explorer

Location: Sidebar → Schema Explorer

The Schema Explorer provides a live, read-only view of everything in your Supabase project: tables, RPC functions, storage buckets, and edge functions. It is the starting point for understanding your project or generating template test coverage.

Browsing Tables​

Expand any table to see:

  • Every column with its data type, nullable flag and default value.
  • A Load Sample Data button that fetches the first 50 rows.

Browsing RPC Functions​

Expand any function to see its parameter names, types, and the return type. If you would like to see the RPC function SQL code in the Supatester interface you can run the provided SQL in your database to pull this information. If a helper function is installed in your database, you can also view the full SQL source code.

Browsing Storage Buckets​

Expand any bucket to see its configuration (public/private, allowed MIME types, file size limit). Click into the bucket to browse its contents exactly as you would in the Bucket Tester.

Browsing Edge Functions​

Expand any edge function to see its deployment status, version, whether JWT verification is enabled, and its entry point. You can view the deployed source code directly in the explorer.

Generating Test Plan Template​

Every item in the Schema Explorer has a Generate Test Plan Template button. Clicking it automatically creates:

  • A collection containing template requests for every relevant operation (SELECT, INSERT, UPDATE, DELETE, RPC calls, storage operations, etc.).
  • A test plan with a test case for each operation under the selected authentication context.

You can choose which Auth Contexts to include in the tests generated (Secret, Publishable, Email User, Anonymous User, Custom JWT), and you can either create a new test plan or add tests to an existing one.

Sample data in INSERT payloads is generated automatically based on column names and types — columns named email receive test@example.com, status receives active, UUID columns receive a generated UUID, and so on.

The generated Collections and Test Plans can serve as a strong starting point or simply help you understand how Collections and Test Plans work.

Foreign Key Schema Enablement​

The foreign key schema enablement is an opt-in feature that unlocks foreign key, primary key, unique constraint, and CHECK constraint awareness across the Schema Explorer and test generation. It requires deploying a single, read-only SQL function to your Supabase instance.

Why Enable It​

Without foreign key metadata, generated INSERT tests produce placeholder values for foreign key columns (e.g. a random UUID). These values almost certainly don't exist in the referenced table, so the INSERT fails with a constraint violation.

With foreign key metadata enabled:

  • Generated test plans automatically create parent rows first and chain their IDs into child INSERTs using {{variable}} references — so every INSERT succeeds out of the box.
  • The Schema Explorer shows richer column details — accurate nullable/default values, a Constraints column (PK, FK, UQ icons), and a dedicated Foreign Key tab.
  • CASCADE and RESTRICT delete behaviours are tested automatically as part of generated test plans.
  • Unique constraint columns receive randomised values to prevent duplicate-key violations on repeated test runs.
  • CHECK constraints are respected — columns with enumerated allowed values use a valid value instead of a generic sample.
  • Cleanup DELETEs are appended at the end of each test plan to remove all generated test data.

How to Deploy the RPC Function​

  1. Open the Schema Explorer and click the ⚙ Settings button in the header (next to the Refresh button).
  2. The settings page shows the current status — Not deployed or Deployed.
  3. Click Copy SQL to copy the supatester_get_constraints function to your clipboard.
  4. Open the SQL Editor in your Supabase Dashboard.
  5. Paste the SQL and click Run.
  6. Return to Supatester and click Refresh in the Schema Explorer. The status will update to Deployed automatically.

The function is:

  • Read-only — it only queries PostgreSQL system catalogues (pg_constraint, pg_attribute, etc.) and cannot modify your database.
  • Restricted — only the service_role key can call it (enforced by a JWT role check inside the function).
  • Non-invasive — no tables, triggers, or background processes are created. It is a single SQL function.

How to Remove It​

If you no longer want the feature, run this in your SQL Editor:

DROP FUNCTION IF EXISTS supatester_get_constraints;

The app reverts to standard mode on the next schema refresh. No data is lost.

What Changes in the Schema Explorer​

When Foreign Key metadata is deployed, the table detail pane gains a tabbed layout:

TabContents
Table DataThe same columns table and sample data as before, but with accurate nullable/default values and a new Constraints column showing PK (🔑), FK (🔗), and UQ (✦) icons.
Foreign KeyDedicated cards for Primary Key, Foreign Keys (with ON DELETE / ON UPDATE actions), Unique Constraints, and Relationships (REST API embedded resource syntax).

When Foreign Key metadata is not deployed, the Schema Explorer doesn't include any of these additional pieces of data. You can still use foreign key relationships in your Advanced Query Builder functions, you just need to understand these relationship yourself.

Foreign Key Tab Details​

  • Primary Key card — shows the constraint name, column(s), type, and whether the PK is auto-generated (e.g. gen_random_uuid()).
  • Foreign Keys card — lists every Foreign Key with its local column, referenced table and column, and the ON UPDATE / ON DELETE actions. Clicking the referenced table name navigates to that table in the Schema Explorer.
  • Unique Constraints card — lists every unique constraint and its column(s), including composite uniques.
  • Relationships card — shows outgoing (many-to-one) and incoming (one-to-many) relationships with ready-made Supabase select syntax (e.g. select=*,users(*)). Each example has a Try in Query Builder button that opens the Advanced Query Builder pre-populated with a working chain for that relationship.

What Changes in Generated Test Plans​

When you click Generate Test Plan on a table with Foreign Key metadata enabled, the generated plan is significantly more intelligent:

Dependency-Ordered INSERT Chain​

For a table like orders that references users and products, the generator produces:

  1. INSERT users [FK dep] — creates a parent user row, extracts its id into {{fk_users_id}}.
  2. INSERT products [FK dep] — creates a parent product row, extracts its id into {{fk_products_id}}.
  3. INSERT orders [sample] — uses {{fk_users_id}} and {{fk_products_id}} as the FK column values.
  4. SELECT, UPDATE, UPSERT, DELETE tests for orders.
  5. DELETE orders [sample cleanup] — removes the sample row.
  6. DELETE products [FK cleanup] / DELETE users [FK cleanup] — removes the parent rows in reverse dependency order.

For deeply nested Foreign Key chains (e.g. order_items → orders → users), the generator walks the full dependency tree and emits INSERTs in the correct topological order. Circular references are detected and handled gracefully.

Foreign Key dependency INSERTs and cleanup DELETEs always run under the Secret (service_role) context to bypass RLS and guarantee success. The actual table tests still run across all configured auth contexts.

CASCADE and RESTRICT Delete Tests​

If a table has foreign keys with CASCADE or RESTRICT delete actions, the generator adds targeted tests:

  • CASCADE test — inserts a parent row and a child row, deletes the parent, then verifies the child was also deleted (expects empty result).
  • RESTRICT test — inserts a parent row and a child row, attempts to delete the parent, and verifies the delete fails (expects error). After the test, both rows are cleaned up.

Unique Constraint Handling​

Columns with unique constraints receive randomised values (using a {{$randomString}} built-in variable resolved at execution time) so that test plans can be re-run without duplicate-key collisions.

UPSERT operations target the correct conflict columns — preferring a unique constraint whose columns are all present in the upsert data over the primary key.

CHECK Constraint Handling​

If a column has a CHECK constraint that restricts it to a set of allowed values (e.g. status IN ('active', 'pending', 'closed')), the generator uses one of those allowed values instead of a generic sample.

Relationship SELECT​

A SELECT with relationships request is included that uses PostgREST embedded resource syntax (e.g. select=*,users(*),order_items(*)) to test join queries derived from the Foreign Key metadata.

Variables and Extraction Rules​

The Foreign Key aware test plan uses the same Request Chaining / Variables system available throughout Supatester. Each dependency INSERT has an extraction rule that captures the returned primary key into a named variable (e.g. fk_users_id). Subsequent requests reference these variables using {{fk_users_id}} syntax.

Because these are standard extraction rules, you can inspect and edit them in the test plan editor just like any other variable — rename them, change the JSON path expression, or add additional extractions.