Add foreign key references support to schema fields

Allow schema fields to reference the primary key of another schema via a
new `references` attribute. The schema dialog shows a popover button to
select the referenced schema, consistent with existing field attribute
buttons.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: bchapuis

apps/api/src/routes/schemas.ts

@@ -27,6 +27,10 @@ const fieldSchema = z.object({
   type: z.enum(["string", "integer", "number", "boolean", "datetime", "json"]),
   required: z.boolean().optional(),
   primaryKey: z.boolean().optional(),
+  label: z.string().optional(),
+  defaultValue: z.string().optional(),
+  unique: z.boolean().optional(),
+  references: z.string().optional(),
 });
 
 const uniqueFields = (fields: z.infer<typeof fieldSchema>[]) => {

apps/app/src/components/schema-dialog.tsx

@@ -2,6 +2,7 @@ import type { Field, FieldType, SchemaEntity } from "@dafthunk/types";
 import Asterisk from "lucide-react/icons/asterisk";
 import Hash from "lucide-react/icons/hash";
 import KeyRound from "lucide-react/icons/key-round";
+import Link from "lucide-react/icons/link";
 import PlusCircle from "lucide-react/icons/plus-circle";
 import Trash2 from "lucide-react/icons/trash-2";
 import { useEffect, useState } from "react";
@@ -16,6 +17,11 @@ import {
 } from "@/components/ui/dialog";
 import { Input } from "@/components/ui/input";
 import { Label } from "@/components/ui/label";
+import {
+  Popover,
+  PopoverContent,
+  PopoverTrigger,
+} from "@/components/ui/popover";
 import {
   Select,
   SelectContent,
@@ -45,9 +51,10 @@ const FIELD_TYPES: FieldType[] = [
 interface FieldEditorProps {
   fields: Field[];
   onChange: (fields: Field[]) => void;
+  schemas?: SchemaEntity[];
 }
 
-function FieldEditor({ fields, onChange }: FieldEditorProps) {
+function FieldEditor({ fields, onChange, schemas }: FieldEditorProps) {
   const addField = () => {
     onChange([...fields, { name: "", type: "string" }]);
   };
@@ -91,9 +98,7 @@ function FieldEditor({ fields, onChange }: FieldEditorProps) {
             <Input
               placeholder="Name"
               value={field.name}
-              onChange={(e) =>
-                updateField(index, { name: e.target.value })
-              }
+              onChange={(e) => updateField(index, { name: e.target.value })}
               className={cn(
                 "flex-1 min-w-0",
                 isDuplicate && "border-destructive"
@@ -151,8 +156,7 @@ function FieldEditor({ fields, onChange }: FieldEditorProps) {
                         onChange(
                           fields.map((f, i) => ({
                             ...f,
-                            primaryKey:
-                              i === index ? true : undefined,
+                            primaryKey: i === index ? true : undefined,
                           }))
                         );
                       }
@@ -201,9 +205,7 @@ function FieldEditor({ fields, onChange }: FieldEditorProps) {
                   </Button>
                 </TooltipTrigger>
                 <TooltipContent>
-                  {field.unique
-                    ? "Remove unique constraint"
-                    : "Set as unique"}
+                  {field.unique ? "Remove unique constraint" : "Set as unique"}
                 </TooltipContent>
               </Tooltip>
             </TooltipProvider>
@@ -232,12 +234,73 @@ function FieldEditor({ fields, onChange }: FieldEditorProps) {
                   </Button>
                 </TooltipTrigger>
                 <TooltipContent>
-                  {field.required
-                    ? "Set as optional"
-                    : "Set as required"}
+                  {field.required ? "Set as optional" : "Set as required"}
                 </TooltipContent>
               </Tooltip>
             </TooltipProvider>
+            {schemas && schemas.length > 0 && (
+              <Popover>
+                <TooltipProvider>
+                  <Tooltip>
+                    <TooltipTrigger asChild>
+                      <PopoverTrigger asChild>
+                        <Button
+                          type="button"
+                          variant={field.references ? "secondary" : "ghost"}
+                          size="icon"
+                          className="h-8 w-8 shrink-0"
+                        >
+                          <Link
+                            className={cn(
+                              "h-4 w-4",
+                              field.references
+                                ? "text-foreground"
+                                : "text-muted-foreground"
+                            )}
+                          />
+                        </Button>
+                      </PopoverTrigger>
+                    </TooltipTrigger>
+                    <TooltipContent>
+                      {field.references
+                        ? `References ${field.references}`
+                        : "Set foreign key reference"}
+                    </TooltipContent>
+                  </Tooltip>
+                </TooltipProvider>
+                <PopoverContent className="w-40 p-1" align="start">
+                  <button
+                    type="button"
+                    className={cn(
+                      "w-full rounded-sm px-2 py-1.5 text-sm text-left hover:bg-accent",
+                      !field.references && "font-medium"
+                    )}
+                    onClick={() =>
+                      updateField(index, { references: undefined })
+                    }
+                  >
+                    None
+                  </button>
+                  {schemas
+                    .filter((s) => s.fields.some((f) => f.primaryKey))
+                    .map((s) => (
+                      <button
+                        key={s.id}
+                        type="button"
+                        className={cn(
+                          "w-full rounded-sm px-2 py-1.5 text-sm text-left hover:bg-accent",
+                          field.references === s.name && "font-medium"
+                        )}
+                        onClick={() =>
+                          updateField(index, { references: s.name })
+                        }
+                      >
+                        {s.name}
+                      </button>
+                    ))}
+                </PopoverContent>
+              </Popover>
+            )}
             <Button
               type="button"
               variant="ghost"
@@ -258,6 +321,7 @@ export interface SchemaDialogProps {
   open: boolean;
   onOpenChange: (open: boolean) => void;
   schema?: SchemaEntity | null;
+  schemas?: SchemaEntity[];
   onSubmit: (data: {
     name: string;
     description: string;
@@ -271,6 +335,7 @@ export function SchemaDialog({
   open,
   onOpenChange,
   schema,
+  schemas,
   onSubmit,
   title,
   submitLabel,
@@ -336,7 +401,7 @@ export function SchemaDialog({
               rows={2}
             />
           </div>
-          <FieldEditor fields={fields} onChange={setFields} />
+          <FieldEditor fields={fields} onChange={setFields} schemas={schemas} />
           <DialogFooter>
             <Button
               variant="outline"

apps/app/src/pages/database-explorer-page.tsx

@@ -24,10 +24,7 @@ import { useParams } from "react-router";
 import { InsetError } from "@/components/inset-error";
 import { InsetLoading } from "@/components/inset-loading";
 import { usePageBreadcrumbs } from "@/hooks/use-page";
-import {
-  useDatabase,
-  useDatabaseSchema,
-} from "@/services/database-service";
+import { useDatabase, useDatabaseSchema } from "@/services/database-service";
 import { cn } from "@/utils/utils";
 
 // --- Schema Table Node ---
@@ -59,8 +56,16 @@ function SchemaTableNode({ data }: NodeProps<Node<SchemaTableNodeData>>) {
               className="!w-[9px] !h-[9px] !bg-muted !border-[1.5px] !border-border"
               isConnectable={false}
             />
-            <span className={col.primaryKey ? "font-semibold" : "text-foreground/80"}>{col.name}</span>
-            <span className="text-muted-foreground/60 font-light uppercase">{col.type || "TEXT"}</span>
+            <span
+              className={
+                col.primaryKey ? "font-semibold" : "text-foreground/80"
+              }
+            >
+              {col.name}
+            </span>
+            <span className="text-muted-foreground/60 font-light uppercase">
+              {col.type || "TEXT"}
+            </span>
             <Handle
               type="source"
               position={Position.Right}
@@ -177,7 +182,7 @@ function SchemaFlowCanvas({ tables }: SchemaFlowCanvasProps) {
       nodesConnectable={false}
       elementsSelectable={false}
       fitView
-      fitViewOptions={{ padding: 0}}
+      fitViewOptions={{ padding: 0 }}
       minZoom={0.1}
       maxZoom={4}
     >
@@ -235,9 +240,7 @@ export function DatabaseExplorerPage() {
   return (
     <div className="flex flex-col h-full">
       <div className="border-b bg-background px-6 py-4 flex items-center">
-        <h1 className="text-xl font-semibold">
-          {database.name} - Explorer
-        </h1>
+        <h1 className="text-xl font-semibold">{database.name} - Explorer</h1>
       </div>
       <div className="flex-1 min-h-0">
         <ReactFlowProvider>

apps/app/src/pages/schemas-page.tsx

@@ -227,6 +227,7 @@ export function SchemasPage() {
         <SchemaDialog
           open={isCreateDialogOpen}
           onOpenChange={setIsCreateDialogOpen}
+          schemas={schemas}
           onSubmit={handleCreate}
           title="Create New Schema"
           submitLabel="Create Schema"
@@ -237,6 +238,7 @@ export function SchemasPage() {
             if (!open) setEditSchema(null);
           }}
           schema={editSchema}
+          schemas={schemas}
           onSubmit={handleEdit}
           title="Edit Schema"
           submitLabel="Save Changes"

packages/runtime/src/nodes/database/database-describe-table-node.ts

@@ -89,9 +89,7 @@ export class DatabaseDescribeTableNode extends ExecutableNode {
       // Collect unique columns from single-column unique indexes
       const uniqueColumns = new Set<string>();
       try {
-        const indexList = await connection.query(
-          `PRAGMA index_list(${table})`
-        );
+        const indexList = await connection.query(`PRAGMA index_list(${table})`);
         if (indexList.results) {
           for (const idx of indexList.results as unknown as Array<{
             name: string;
@@ -101,10 +99,7 @@ export class DatabaseDescribeTableNode extends ExecutableNode {
             const indexInfo = await connection.query(
               `PRAGMA index_info(${idx.name})`
             );
-            if (
-              indexInfo.results &&
-              indexInfo.results.length === 1
-            ) {
+            if (indexInfo.results && indexInfo.results.length === 1) {
               const col = indexInfo.results[0] as unknown as {
                 name: string;
               };
@@ -120,9 +115,7 @@ export class DatabaseDescribeTableNode extends ExecutableNode {
         name: col.name,
         type: mapSqliteToType(col.type || "TEXT"),
         ...(col.pk ? { primaryKey: true } : {}),
-        ...(!col.pk && uniqueColumns.has(col.name)
-          ? { unique: true }
-          : {}),
+        ...(!col.pk && uniqueColumns.has(col.name) ? { unique: true } : {}),
       }));
 
       const schema: Schema = {

packages/runtime/src/nodes/database/database-put-row-node.ts

@@ -10,7 +10,8 @@ export class DatabasePutRowNode extends ExecutableNode {
     id: "database-put-row",
     name: "Database Put Row",
     type: "database-put-row",
-    description: "Inserts a row, or replaces it if a matching primary key exists.",
+    description:
+      "Inserts a row, or replaces it if a matching primary key exists.",
     tags: ["Database", "Put", "Row"],
     icon: "database",
     documentation:

packages/types/src/types.ts

@@ -29,6 +29,7 @@ export interface Field {
   label?: string;
   defaultValue?: string;
   unique?: boolean;
+  references?: string;
 }
 
 /**