Configuring Database Tables in Supamode

Table configuration controls how your database appears in Supamode's Data Explorer. Good configuration transforms cryptic table names like usr_prf into a clear "User Profiles" interface that anyone on your team can use.

What you can configure:

• Display names: Human-readable labels (usr_prf to "User Profiles")
• Display format: How records show in dropdowns ({first_name} {last_name})
• Visibility: Which tables appear in the sidebar
• Searchability: Which tables are included in global search

Syncing Tables

Before configuring tables, sync your database schema into Supamode's metadata system. This populates supamode.table_metadata with your table and column information.

Sync Commands

Run these SQL commands in Supabase Studio's SQL Editor or include them in a migration:

-- Sync all tables in the public schema
select supamode.sync_managed_tables('public');
-- Sync specific tables (useful for selective syncing)
select supamode.sync_managed_tables('public', 'users');
select supamode.sync_managed_tables('public', 'orders');
select supamode.sync_managed_tables('public', 'products');
-- Sync tables from custom schemas
select supamode.sync_managed_tables('billing', 'invoices');
select supamode.sync_managed_tables('analytics', 'events');
-- Sync Supabase auth.users table (recommended)
select supamode.sync_managed_tables('auth', 'users');

When to Re-sync

Re-run the sync function when you:

• Add new tables to your schema
• Add, rename, or remove columns
• Change column types or constraints
• Run database migrations

Syncing is idempotent. Running it multiple times is safe and updates existing metadata.

Configuring Tables in the UI

After syncing, configure tables at Settings > Tables (/settings/tables).

Display Name

The display name appears in the sidebar, page headers, and throughout the UI. Supamode infers names from table names (user_accounts becomes "User Accounts"), but you should customize them for clarity.

Examples:

Display Format

The display format controls how records appear when referenced from other tables. Instead of showing a UUID like 550e8400-e29b-41d4-a716-446655440000, display something meaningful.

Syntax: Use {column_name} placeholders:

{first_name} {last_name}

With static text:

{title} (#{id})

Multiple columns:

{name} - {email}

Handling null values:

Use || for fallbacks when a column might be null:

{name || email}

This shows name if present, otherwise falls back to email.

With default text:

{name || 'Unknown User'}

Real-world examples:

Visibility

Control which tables appear in the Data Explorer sidebar. Tables can be:

• Visible: Appears in sidebar and is accessible
• Hidden: Not shown in sidebar but accessible via direct URL (if user has permissions)

When to hide tables:

• Tables not relevant to the users (ex. storage.objects)
• Internal system tables (audit_logs, migrations)
• Join tables for many-to-many relationships (post_tags, user_roles)
• Tables with no user-facing data

Hiding tables keeps the UI clean for non-technical users.

Searchability

Global search (Cmd+K) queries all searchable tables. For performance with large databases, disable search on:

• Tables with millions of rows
• Tables with mostly non-text data (numbers, booleans)
• Audit or logging tables
• Tables users rarely need to search

Supamode excludes certain column types from search automatically (binary, JSON, etc.).

Ordering

Drag and drop tables in the Settings UI to reorder them in the sidebar. Put frequently-accessed tables at the top.

Column Configuration

Each table's columns can also be configured for optimal display:

• Display name: Override column names (created_at → "Created")
• Visibility: Hide columns users don't need to see
• Data type hints: Override inferred types for better form fields

Access column settings by clicking on a table in the Tables settings page.

Best Practices

Start with Core Tables

Focus configuration on tables your team uses daily:

1. Identify the 5-10 most-accessed tables
2. Configure meaningful display formats
3. Hide internal/system tables
4. Test with non-technical users

Use Consistent Naming

Establish conventions across your schema:

• Singular vs. plural: Pick one ("Order" or "Orders")
• Abbreviation policy: Expand or keep consistent
• Status values: Use human-readable labels

Optimize for Search

• Enable search only on tables users query frequently
• Ensure searchable columns have appropriate indexes in PostgreSQL
• Consider creating views for complex search scenarios

Troubleshooting

Table Not Appearing

If a synced table doesn't appear in the Data Explorer:

1. Verify the sync ran successfully
   • Run the following query:
     select * from supamode.table_metadata
     where table_name = 'your_table';

2. Check the user has data permissions for the table
3. Verify the table isn't hidden in visibility settings

Display Format Not Working

If placeholders show literally (e.g., {name} instead of "John"):

• Verify the column name exists exactly as typed
• Check for typos (column names are case-sensitive)
• Ensure the column isn't null (use fallback syntax)

Sync Not Updating

If schema changes don't appear after syncing:

• Run the sync again for the specific table
• Clear Supamode's cache by restarting the API server
• Check for database connection issues