feat(tables): gate reference columns

Author: j15z

apps/sim/.env.example

@@ -203,6 +203,7 @@ CRON_SECRET=your_cron_secret # Use `openssl rand -hex 32` to generate. Authentic
 # FORKING_ENABLED=                                                # Workspace forks
 # CREDENTIAL_GROUPS=                                              # Enterprise managed OAuth collections
 # TABLE_ROW_TTL=                                                  # Table TTL columns and expired-row cleanup
+# 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

@@ -55,6 +55,13 @@ vi.mock('@/lib/table/wire', () => ({
 vi.mock('@/app/api/table/utils', () => ({
   accessError: () => new Response('denied', { status: 403 }),
   checkAccess: mockCheckAccess,
+  orchestrationErrorResponse: (error: unknown) =>
+    error instanceof OrchestrationError
+      ? NextResponse.json(
+          { error: error.message },
+          { status: statusForOrchestrationError(error.code) }
+        )
+      : null,
   orchestrationOutcomeErrorResponse: (
     outcome: { error?: string; errorCode?: OrchestrationErrorCode },
     fallback: string
@@ -73,7 +80,7 @@ import {
   type OrchestrationErrorCode,
   statusForOrchestrationError,
 } from '@/lib/core/orchestration/types'
-import { PATCH } from '@/app/api/table/[tableId]/columns/route'
+import { PATCH, POST } from '@/app/api/table/[tableId]/columns/route'
 
 const WORKSPACE_ID = '11111111-1111-4111-8111-111111111111'
 
@@ -88,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

@@ -17,6 +17,7 @@ import { normalizeColumn } from '@/lib/table/wire'
 import {
   accessError,
   checkAccess,
+  orchestrationErrorResponse,
   orchestrationOutcomeErrorResponse,
   rootErrorMessage,
   tableLockErrorResponse,
@@ -69,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

@@ -55,6 +55,7 @@ interface ColumnConfigSidebarProps {
   existingColumn: ColumnDefinition | null
   allColumns: readonly ColumnDefinition[]
   tableRowTtlEnabled: boolean
+  referenceColumnsEnabled: boolean
   workspaceId: string
   tableId: string
   /** Notify parent of a rename so it can rewrite local `columnOrder` /
@@ -107,6 +108,7 @@ function ColumnConfigBody({
   existingColumn,
   allColumns,
   tableRowTtlEnabled,
+  referenceColumnsEnabled,
   workspaceId,
   tableId,
   onColumnRename,
@@ -142,14 +144,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() }))
@@ -304,12 +312,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'])}
@@ -372,6 +388,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

@@ -33,6 +33,7 @@ describe('ColumnDropdown', () => {
           tableRowTtlEnabled
           trigger='header'
           disabled={false}
+          referenceColumnsEnabled
           onPickType={vi.fn()}
           onPickWorkflow={vi.fn()}
           onPickEnrichment={onPickEnrichment}
@@ -57,4 +58,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

@@ -27,6 +27,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
@@ -84,6 +85,7 @@ export function ColumnDropdown({
   tableRowTtlEnabled,
   trigger,
   disabled,
+  referenceColumnsEnabled,
   onPickType,
   onPickWorkflow,
   onPickEnrichment,
@@ -126,13 +128,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

@@ -172,6 +172,7 @@ export interface SelectionSnapshot {
 interface TableGridProps {
   workspaceId?: string
   tableId?: string
+  referenceColumnsEnabled: boolean
   embedded?: boolean
   tableRowTtlEnabled: boolean
   /** Remote collaborators' cell selections, rendered as presence overlays. */
@@ -436,6 +437,7 @@ async function chunkBatchUpdates(
 export function TableGrid({
   workspaceId: propWorkspaceId,
   tableId: propTableId,
+  referenceColumnsEnabled,
   embedded,
   tableRowTtlEnabled,
   remoteSelections,
@@ -4904,7 +4906,9 @@ export function TableGrid({
                             workflowGroups={tableWorkflowGroups}
                             sourceInfo={columnSourceInfo.get(column.key)}
                             onOpenConfig={handleConfigureColumn}
-                            onGoToReferenceTable={handleGoToReferenceTable}
+                            onGoToReferenceTable={
+                              referenceColumnsEnabled ? handleGoToReferenceTable : undefined
+                            }
                             onViewWorkflow={handleViewWorkflow}
                             onSortColumn={onSortColumn}
                             onClearSort={onClearSort}
@@ -4924,6 +4928,7 @@ export function TableGrid({
                           tableRowTtlEnabled={tableRowTtlEnabled}
                           trigger='inline-header'
                           disabled={addColumnMutation.isPending}
+                          referenceColumnsEnabled={referenceColumnsEnabled}
                           blocked={!canMutateSchema}
                           onBlocked={() => onBlockedAction('add-column')}
                           onPickType={handleAddColumnOfType}