feat(tables): gate reference columns

Author: j15z

apps/sim/.env.example

@@ -215,6 +215,7 @@ CRON_SECRET=your_cron_secret # Use `openssl rand -hex 32` to generate. Authentic
 # CREDENTIAL_GROUPS=                                              # Enterprise managed OAuth collections
 # TABLE_ROW_TTL=                                                  # Table TTL columns and expired-row cleanup
 # PERMISSION_ACCESS_REQUESTS_ENABLED=                             # Global access-request rollout; organizations may opt out
+# TABLE_REFERENCE_COLUMNS=                                        # Table Reference columns
 # KNOWLEDGE_MEMBER_ACCESS=                                        # Per-member knowledge connectors and hybrid-by-default retrieval
 # ORGANIZATIONS_ENABLED= / NEXT_PUBLIC_ORGANIZATIONS_ENABLED=     # Organizations only
 

apps/sim/app/api/table/[tableId]/columns/route.test.ts

@@ -95,6 +95,49 @@ function patch(updates: Record<string, unknown>) {
   )
 }
 
+function post(column: Record<string, unknown>) {
+  return POST(
+    new NextRequest('http://localhost/api/table/t1/columns', {
+      method: 'POST',
+      body: JSON.stringify({ workspaceId: WORKSPACE_ID, column }),
+      headers: { 'content-type': 'application/json' },
+    }),
+    { params: Promise.resolve({ tableId: 't1' }) }
+  )
+}
+
+describe('POST /api/table/[tableId]/columns — Reference feature gate', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    hybridAuthMockFns.mockCheckSessionOrInternalAuth.mockResolvedValue({
+      success: true,
+      userId: 'user-1',
+      authType: 'session',
+    })
+    mockCheckAccess.mockResolvedValue({
+      ok: true,
+      table: { workspaceId: WORKSPACE_ID, schema: { columns: [] } },
+    })
+  })
+
+  it('returns 403 when Reference columns are disabled', async () => {
+    mockAddTableColumn.mockRejectedValue(
+      new OrchestrationError('forbidden', 'Reference columns are not enabled for this deployment')
+    )
+
+    const response = await post({
+      name: 'Account',
+      type: 'reference',
+      referenceTableId: 'tbl_accounts',
+    })
+
+    expect(response.status).toBe(403)
+    expect(await response.json()).toEqual({
+      error: 'Reference columns are not enabled for this deployment',
+    })
+  })
+})
+
 describe('PATCH /api/table/[tableId]/columns — pre-flight guards', () => {
   beforeEach(() => {
     vi.clearAllMocks()

apps/sim/app/api/table/[tableId]/columns/route.ts

@@ -70,6 +70,9 @@ export const POST = withRouteHandler(async (request: NextRequest, context: Colum
       return validationErrorResponse(error, 'Invalid request data')
     }
 
+    const classified = orchestrationErrorResponse(error)
+    if (classified) return classified
+
     const msg = rootErrorMessage(error)
     if (
       msg.includes('already exists') ||

apps/sim/app/workspace/[workspaceId]/tables/[tableId]/components/column-config-sidebar/column-config-sidebar.test.tsx

@@ -8,6 +8,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 interface ComboboxOption {
   label: string
   value: string
+  disabled?: boolean
 }
 
 interface ComboboxProps {
@@ -16,6 +17,7 @@ interface ComboboxProps {
   placeholder?: string
   searchable?: boolean
   searchPlaceholder?: string
+  disabled?: boolean
   onChange?: (value: string) => void
 }
 
@@ -143,6 +145,7 @@ describe('ColumnConfigSidebar', () => {
           existingColumn={null}
           workspaceId='workspace-1'
           tableId='table-current'
+          referenceColumnsEnabled
         />
       )
     })
@@ -179,6 +182,7 @@ describe('ColumnConfigSidebar', () => {
           existingColumn={null}
           workspaceId='workspace-1'
           tableId='table-current'
+          referenceColumnsEnabled
         />
       )
     })
@@ -206,6 +210,7 @@ describe('ColumnConfigSidebar', () => {
           workspaceId='workspace-1'
           tableId='table-current'
           onColumnRename={onColumnRename}
+          referenceColumnsEnabled
         />
       )
     })
@@ -227,6 +232,32 @@ describe('ColumnConfigSidebar', () => {
     expect(onColumnRename).toHaveBeenCalledWith('col-reference', 'Renamed relation')
   })
 
+  it('keeps an existing Reference column visible but not retargetable when disabled', async () => {
+    await act(async () => {
+      root.render(
+        <ColumnConfigSidebar
+          config={{ mode: 'edit', columnName: 'col-reference' }}
+          onClose={vi.fn()}
+          existingColumn={{
+            id: 'col-reference',
+            name: 'Related row',
+            type: 'reference',
+            referenceTableId: 'table-current',
+          }}
+          workspaceId='workspace-1'
+          tableId='table-current'
+          referenceColumnsEnabled={false}
+        />
+      )
+    })
+
+    expect(mockUseTablesList).toHaveBeenCalledWith('workspace-1', 'active', { enabled: false })
+    expect(findCombobox('Select table')?.disabled).toBe(true)
+    expect(findCombobox('Select type')?.options).toContainEqual(
+      expect.objectContaining({ value: 'reference', disabled: true })
+    )
+  })
+
   it('keeps Select options in the edit sidebar', async () => {
     await act(async () => {
       root.render(
@@ -241,6 +272,7 @@ describe('ColumnConfigSidebar', () => {
           }}
           workspaceId='workspace-1'
           tableId='table-current'
+          referenceColumnsEnabled
         />
       )
     })

apps/sim/app/workspace/[workspaceId]/tables/[tableId]/components/column-config-sidebar/column-config-sidebar.tsx

@@ -65,6 +65,7 @@ interface ColumnConfigSidebarProps {
   existingColumn: ColumnDefinition | null
   allColumns: readonly ColumnDefinition[]
   tableRowTtlEnabled: boolean
+  referenceColumnsEnabled: boolean
   workspaceId: string
   tableId: string
   /**
@@ -126,6 +127,7 @@ function ColumnConfigBody({
   existingColumn,
   allColumns,
   tableRowTtlEnabled,
+  referenceColumnsEnabled,
   workspaceId,
   tableId,
   readOnly,
@@ -163,14 +165,20 @@ function ColumnConfigBody({
   const [optionsError, setOptionsError] = useState<string | null>(null)
   const [referenceTableError, setReferenceTableError] = useState<string | null>(null)
 
-  const saveDisabled = updateColumn.isPending || addColumn.isPending
   const trimmedName = nameInput.trim()
   const wantsOptions = isSelectType(typeInput)
   const wantsCurrency = typeInput === 'currency'
   const wantsReference = typeInput === 'reference'
+  const referenceMutationBlocked =
+    !referenceColumnsEnabled &&
+    wantsReference &&
+    (config.mode === 'create' ||
+      existingColumn?.type !== 'reference' ||
+      existingColumn.referenceTableId !== referenceTableInput)
+  const saveDisabled = updateColumn.isPending || addColumn.isPending || referenceMutationBlocked
   const supportsUnique = columnTypeById(typeInput).supportsUnique
   const { data: workspaceTables = [] } = useTablesList(workspaceId, 'active', {
-    enabled: wantsReference,
+    enabled: wantsReference && referenceColumnsEnabled,
   })
   const tableOptions = workspaceTables.map((table) => ({ value: table.id, label: table.name }))
   const trimmedOptions = optionsInput.map((o) => ({ ...o, name: o.name.trim() }))
@@ -331,12 +339,20 @@ function ColumnConfigBody({
                   options={columnTypeOptionsForTable(allColumns, existingColumn, {
                     tableRowTtlEnabled,
                   })
-                    .filter((option) => option.type !== 'workflow')
+                    .filter(
+                      (option) =>
+                        option.type !== 'workflow' &&
+                        (referenceColumnsEnabled ||
+                          option.type !== 'reference' ||
+                          existingColumn?.type === 'reference')
+                    )
                     .map((option) => ({
                       label: option.label,
                       value: option.type,
                       icon: option.icon,
-                      disabled: option.disabledReason !== undefined,
+                      disabled:
+                        option.disabledReason !== undefined ||
+                        (!referenceColumnsEnabled && option.type === 'reference'),
                     }))}
                   value={typeInput}
                   onChange={(v) => setTypeInput(v as ColumnDefinition['type'])}
@@ -399,6 +415,7 @@ function ColumnConfigBody({
                 <ChipCombobox
                   options={tableOptions}
                   value={referenceTableInput}
+                  disabled={!referenceColumnsEnabled}
                   onChange={(value) => {
                     setReferenceTableInput(value)
                     if (referenceTableError) setReferenceTableError(null)

apps/sim/app/workspace/[workspaceId]/tables/[tableId]/components/column-dropdown/column-dropdown.test.tsx

@@ -63,6 +63,7 @@ describe('ColumnDropdown', () => {
           tableRowTtlEnabled
           trigger='header'
           disabled={false}
+          referenceColumnsEnabled
           onPickType={vi.fn()}
           onPickWorkflow={vi.fn()}
           onPickEnrichment={onPickEnrichment}
@@ -86,4 +87,33 @@ describe('ColumnDropdown', () => {
     act(() => items.at(-1)?.click())
     expect(onPickEnrichment).toHaveBeenCalledOnce()
   })
+
+  it('omits Reference when the feature is disabled', () => {
+    act(() => {
+      root.render(
+        <ColumnDropdown
+          columns={[]}
+          tableRowTtlEnabled
+          trigger='header'
+          disabled={false}
+          referenceColumnsEnabled={false}
+          onPickType={vi.fn()}
+          onPickWorkflow={vi.fn()}
+          onPickEnrichment={vi.fn()}
+          blocked={false}
+          onBlocked={vi.fn()}
+        />
+      )
+    })
+    act(() => {
+      container
+        .querySelector<HTMLButtonElement>('button')
+        ?.dispatchEvent(new MouseEvent('pointerdown', { bubbles: true, button: 0 }))
+    })
+
+    const labels = [...document.body.querySelectorAll<HTMLElement>('[role="menuitem"]')].map(
+      (item) => item.textContent
+    )
+    expect(labels).not.toContain('Reference')
+  })
 })

apps/sim/app/workspace/[workspaceId]/tables/[tableId]/components/column-dropdown/column-dropdown.tsx

@@ -30,6 +30,7 @@ interface ColumnDropdownProps {
    *  the in-table column-header `<th>` trigger. Same dropdown content either way. */
   trigger: 'header' | 'inline-header'
   disabled: boolean
+  referenceColumnsEnabled: boolean
   onPickType: (type: ColumnDefinition['type']) => void
   onPickWorkflow: () => void
   onPickEnrichment: () => void
@@ -81,6 +82,7 @@ export function ColumnDropdown({
   tableRowTtlEnabled,
   trigger,
   disabled,
+  referenceColumnsEnabled,
   onPickType,
   onPickWorkflow,
   onPickEnrichment,
@@ -132,13 +134,15 @@ export function ColumnDropdown({
     <DropdownMenu>
       <DropdownMenuTrigger asChild>{triggerButton}</DropdownMenuTrigger>
       <DropdownMenuContent align='start' side='bottom' sideOffset={4}>
-        {columnTypeOptionsForTable(columns, undefined, { tableRowTtlEnabled }).map((option) => {
-          const onSelect =
-            option.type === 'workflow'
-              ? onPickWorkflow
-              : () => onPickType(option.type as ColumnDefinition['type'])
-          return <ColumnTypeMenuItem key={option.type} option={option} onSelect={onSelect} />
-        })}
+        {columnTypeOptionsForTable(columns, undefined, { tableRowTtlEnabled })
+          .filter((option) => referenceColumnsEnabled || option.type !== 'reference')
+          .map((option) => {
+            const onSelect =
+              option.type === 'workflow'
+                ? onPickWorkflow
+                : () => onPickType(option.type as ColumnDefinition['type'])
+            return <ColumnTypeMenuItem key={option.type} option={option} onSelect={onSelect} />
+          })}
         <DropdownMenuItem onSelect={onPickEnrichment}>
           <Sparkles className='size-[14px] text-[var(--text-icon)]' />
           Enrichments

apps/sim/app/workspace/[workspaceId]/tables/[tableId]/components/table-grid/table-grid.tsx

@@ -174,6 +174,7 @@ export interface SelectionSnapshot {
 interface TableGridProps {
   workspaceId?: string
   tableId?: string
+  referenceColumnsEnabled: boolean
   embedded?: boolean
   tableRowTtlEnabled: boolean
   /** Remote collaborators' cell selections, rendered as presence overlays. */
@@ -449,6 +450,7 @@ async function chunkBatchUpdates(
 export function TableGrid({
   workspaceId: propWorkspaceId,
   tableId: propTableId,
+  referenceColumnsEnabled,
   embedded,
   tableRowTtlEnabled,
   remoteSelections,
@@ -4970,7 +4972,9 @@ export function TableGrid({
                             deleteLockedReason={
                               locks?.deleteLocked ? LOCK_TOOLTIPS.delete : undefined
                             }
-                            onGoToReferenceTable={handleGoToReferenceTable}
+                            onGoToReferenceTable={
+                              referenceColumnsEnabled ? handleGoToReferenceTable : undefined
+                            }
                             onViewWorkflow={handleViewWorkflow}
                             onSortColumn={onSortColumn}
                             onClearSort={onClearSort}
@@ -4990,6 +4994,7 @@ export function TableGrid({
                           tableRowTtlEnabled={tableRowTtlEnabled}
                           trigger='inline-header'
                           disabled={addColumnMutation.isPending}
+                          referenceColumnsEnabled={referenceColumnsEnabled}
                           blocked={!canMutateSchema}
                           onPickType={handleAddColumnOfType}
                           onPickWorkflow={handleAddWorkflowColumn}

apps/sim/app/workspace/[workspaceId]/tables/[tableId]/table.tsx

@@ -40,6 +40,7 @@ import { PresenceAvatars } from '@/app/workspace/[workspaceId]/components/presen
 import { LogDetails } from '@/app/workspace/[workspaceId]/logs/components'
 import { useFeatureFlag } from '@/app/workspace/[workspaceId]/providers/feature-flags-provider'
 import { useRegisterGlobalCommands } from '@/app/workspace/[workspaceId]/providers/global-commands-provider'
+import { useOptionalWorkspaceHostContext } from '@/app/workspace/[workspaceId]/providers/workspace-host-provider'
 import { useUserPermissionsContext } from '@/app/workspace/[workspaceId]/providers/workspace-permissions-provider'
 import {
   getTableViewRevision,
@@ -201,6 +202,8 @@ export function Table({
   const router = useRouter()
   const workspaceId = propWorkspaceId || (params.workspaceId as string)
   const tableId = propTableId || (params.tableId as string)
+  const hostContext = useOptionalWorkspaceHostContext()
+  const referenceColumnsEnabled = hostContext?.features?.referenceColumns ?? false
 
   const posthog = usePostHog()
   const tableRowTtlEnabled = useFeatureFlag('table-row-ttl')
@@ -1440,6 +1443,7 @@ export function Table({
       tableRowTtlEnabled={tableRowTtlEnabled}
       trigger='header'
       disabled={false}
+      referenceColumnsEnabled={referenceColumnsEnabled}
       blocked={!canMutateSchema}
       onPickType={handleAddColumnOfType}
       onPickWorkflow={handleAddWorkflowColumn}
@@ -1602,6 +1606,7 @@ export function Table({
       <TableGrid
         workspaceId={workspaceId}
         tableId={tableId}
+        referenceColumnsEnabled={referenceColumnsEnabled}
         embedded={embedded}
         tableRowTtlEnabled={tableRowTtlEnabled}
         locks={tableData?.locks}
@@ -1711,6 +1716,7 @@ export function Table({
       <ColumnConfigSidebar
         config={columnConfig}
         tableRowTtlEnabled={tableRowTtlEnabled}
+        referenceColumnsEnabled={referenceColumnsEnabled}
         onClose={onCloseSlideout}
         allColumns={columns}
         existingColumn={