# Configuring Database Tables in Supamode

> Configure table display names, formats, visibility, and search settings. Learn how to sync your PostgreSQL schema and optimize the Data Explorer experience.

*Canonical: https://makerkit.dev/docs/supamode/configuration/tables*

---

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:

```sql
-- 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');
```

{% alert type="default" title="Sync auth.users" %}
We recommend syncing `auth.users` since it's frequently referenced by foreign keys. This enables Supamode to display user names instead of raw UUIDs in reference fields and dropdowns.
{% /alert %}

### 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:**
| Table Name | Default | Recommended |
|------------|---------|-------------|
| `usr_profiles` | Usr Profiles | User Profiles |
| `tx_history` | Tx History | Transaction History |
| `prod_cat` | Prod Cat | Product Categories |

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

| Table | Display Format | Result |
|-------|----------------|--------|
| `users` | `{name}` | "John Smith" |
| `orders` | `Order #{id} - {status}` | "Order #1234 - pending" |
| `products` | `{name} (${price})` | "Widget ($29.99)" |
| `posts` | `{title \|\| 'Untitled'}` | "My Blog Post" or "Untitled" |

### 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:
      ```sql
      select * from supamode.table_metadata
      where table_name = 'your_table';
      ```
2. Check the user has [data permissions](./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

{% faq
   title="Frequently Asked Questions"
   items=[
     {"question": "Do I need to sync tables every time I deploy?", "answer": "No. Table metadata is stored in the database and persists across deployments. Only re-sync when your schema changes (new tables, new columns, type changes)."},
     {"question": "Will syncing affect my production data?", "answer": "No. The sync function only reads your schema metadata and writes to supamode.table_metadata. It never modifies your application tables or data."},
     {"question": "How do I handle tables with the same name in different schemas?", "answer": "Supamode tracks tables by schema and name combination. Configure each separately in Settings. In the sidebar, tables are grouped by schema if you have multiple schemas synced."},
     {"question": "What happens if I rename a column after syncing?", "answer": "The old column metadata remains until you re-sync. Re-run sync_managed_tables for the affected table to update column information. Display formats referencing the old column name will show the placeholder literally until updated."},
     {"question": "Can I configure column-level visibility per role?", "answer": "Column visibility in table settings is global. For role-based column access, use data permissions to control which roles can read specific columns."},
     {"question": "How do I exclude system columns from the UI?", "answer": "In column configuration, set visibility to hidden for columns like created_at, updated_at, or internal IDs. Users won't see these in the Data Explorer but they're still accessible via the API if permissions allow."}
   ]
/%}