feat(database): add opt-in live document updates in the data explorer

package.json

@@ -9,6 +9,7 @@
     "start": "next start -p 8080",
     "lint": "eslint .",
     "test:semantic-colors": "node --experimental-strip-types --test src/lib/semantic-colors.test.ts src/lib/reactflow-edge-colors.test.ts",
+    "test:realtime": "node --experimental-strip-types --test src/lib/realtime/adminSocketUrl.test.ts src/lib/realtime/change-events.test.ts src/lib/realtime/connection-snippets.test.ts",
     "test:schema-fields": "node --experimental-strip-types --test src/lib/database/schema-field-definition.test.ts src/lib/database/system-schema-fields.test.ts",
     "build:docker": "docker build --platform linux/amd64 -t ghcr.io/conduitplatform/conduit-ui:latest .",
     "prepare": "husky",
@@ -80,6 +81,7 @@
     "recharts": "^3.8.1",
     "rehype-prism-plus": "^2.0.2",
     "server-only": "^0.0.1",
+    "socket.io-client": "^4.8.3",
     "tailwind-merge": "^3.4.0",
     "tailwindcss": "^4.2.2",
     "tailwindcss-animate": "^1.0.7",

src/app/(dashboard)/(modules)/database/settings/page.tsx

@@ -1,14 +1,19 @@
 import { Settings } from '@/components/database/settings/settings';
-import { getDatabaseSettings, getDatabaseType } from '@/lib/api/database';
+import {
+  getDatabaseRealtimeStatus,
+  getDatabaseSettings,
+  getDatabaseType,
+} from '@/lib/api/database';
 
 export default async function DatabaseSettingsPage() {
-  const [settingsResult, typeResult] = await Promise.allSettled([
-    getDatabaseSettings(),
-    getDatabaseType(),
-  ]);
+  const [settingsResult, typeResult, realtimeResult] = await Promise.allSettled(
+    [getDatabaseSettings(), getDatabaseType(), getDatabaseRealtimeStatus()]
+  );
 
   const databaseType =
     typeResult.status === 'fulfilled' ? typeResult.value.result : 'Unknown';
+  const realtimeStatus =
+    realtimeResult.status === 'fulfilled' ? realtimeResult.value : null;
 
   if (settingsResult.status === 'rejected') {
     return (
@@ -25,6 +30,10 @@ export default async function DatabaseSettingsPage() {
   }
 
   return (
-    <Settings data={settingsResult.value.config} databaseType={databaseType} />
+    <Settings
+      data={settingsResult.value.config}
+      databaseType={databaseType}
+      realtimeStatus={realtimeStatus}
+    />
   );
 }

src/components/database/models/data-explorer/index.tsx

@@ -31,6 +31,8 @@ import {
 import { Badge } from '@/components/ui/badge';
 import { toast } from '@/lib/hooks/use-toast';
 import { deleteSchemaDocument } from '@/lib/api/database';
+import { useDatabaseLiveUpdates } from '@/lib/hooks/use-database-live-updates';
+import { LiveUpdatesStatus } from './live-updates-status';
 import {
   analyzeModelDataPermissions,
   getExtensionFieldNames,
@@ -74,6 +76,11 @@ export function DataExplorer({ schema, documents }: DataExplorerProps) {
     () => analyzeModelDataPermissions(schema),
     [schema]
   );
+  const liveEnabled = schema.modelOptions?.conduit?.realtime?.enabled === true;
+  const liveUpdates = useDatabaseLiveUpdates({
+    schemaName: schema.name,
+    enabled: liveEnabled,
+  });
 
   // Get schema fields for column definitions
   const schemaFields = React.useMemo(() => {
@@ -160,6 +167,7 @@ export function DataExplorer({ schema, documents }: DataExplorerProps) {
   };
 
   const handleRefresh = () => {
+    liveUpdates.consumePendingUpdates();
     router.refresh();
     toast({ title: 'Data refreshed' });
   };
@@ -185,6 +193,7 @@ export function DataExplorer({ schema, documents }: DataExplorerProps) {
   const handleDocumentSaved = () => {
     setSelectedDocument(null);
     setIsCreatingNew(false);
+    liveUpdates.consumePendingUpdates();
     router.refresh();
   };
 
@@ -372,9 +381,22 @@ export function DataExplorer({ schema, documents }: DataExplorerProps) {
               </TabsList>
             </Tabs>
 
+            <LiveUpdatesStatus
+              connectionState={liveUpdates.connectionState}
+              pendingUpdates={liveUpdates.pendingUpdates}
+              errorMessage={liveUpdates.errorMessage}
+              onApplyUpdates={handleRefresh}
+            />
+
             {/* Refresh */}
-            <Button variant="outline" size="sm" onClick={handleRefresh}>
+            <Button
+              variant="outline"
+              size="sm"
+              onClick={handleRefresh}
+              className="min-h-8"
+            >
               <RefreshCw className="w-4 h-4" />
+              <span className="sr-only">Refresh</span>
             </Button>
 
             {/* Create New */}

src/components/database/models/data-explorer/live-updates-status.tsx

@@ -0,0 +1,93 @@
+'use client';
+
+import * as React from 'react';
+import { Button } from '@/components/ui/button';
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipProvider,
+  TooltipTrigger,
+} from '@/components/ui/tooltip';
+import { cn } from '@/lib/utils';
+import type { LiveConnectionState } from '@/lib/hooks/use-database-live-updates';
+
+type LiveUpdatesStatusProps = {
+  connectionState: LiveConnectionState;
+  pendingUpdates: number;
+  errorMessage?: string | null;
+  onApplyUpdates: () => void;
+};
+
+const STATE_LABEL: Record<Exclude<LiveConnectionState, 'idle'>, string> = {
+  connecting: 'Connecting',
+  live: 'Live',
+  reconnecting: 'Reconnecting',
+  error: 'Unavailable',
+};
+
+export function LiveUpdatesStatus({
+  connectionState,
+  pendingUpdates,
+  errorMessage,
+  onApplyUpdates,
+}: LiveUpdatesStatusProps) {
+  if (connectionState === 'idle') return null;
+
+  let statusHint = 'Connecting to live updates.';
+  if (connectionState === 'error') {
+    statusHint = errorMessage || 'Live updates are unavailable';
+  } else if (connectionState === 'live') {
+    statusHint =
+      'Listening for document changes. The table does not refresh until you apply updates.';
+  }
+
+  return (
+    <TooltipProvider>
+      <div className="flex items-center gap-2">
+        <Tooltip>
+          <TooltipTrigger asChild>
+            <span
+              className="inline-flex min-h-8 items-center gap-2 px-2 text-xs font-medium text-muted-foreground"
+              aria-live="polite"
+            >
+              <span
+                className={cn(
+                  'size-2 rounded-full',
+                  connectionState === 'live' && 'bg-status-healthy',
+                  connectionState === 'connecting' && 'bg-status-info',
+                  connectionState === 'reconnecting' && 'bg-status-warning',
+                  connectionState === 'error' && 'bg-status-critical'
+                )}
+              />
+              {STATE_LABEL[connectionState]}
+            </span>
+          </TooltipTrigger>
+          <TooltipContent>{statusHint}</TooltipContent>
+        </Tooltip>
+
+        {pendingUpdates > 0 && (
+          <Tooltip>
+            <TooltipTrigger asChild>
+              <Button
+                type="button"
+                variant="secondary"
+                size="sm"
+                className="min-h-8 gap-2 tabular-nums"
+                onClick={onApplyUpdates}
+              >
+                {pendingUpdates}{' '}
+                {pendingUpdates === 1
+                  ? 'update available'
+                  : 'updates available'}
+              </Button>
+            </TooltipTrigger>
+            <TooltipContent>
+              Refresh the current filtered page. Open documents stay as they
+              are.
+            </TooltipContent>
+          </Tooltip>
+        )}
+      </div>
+    </TooltipProvider>
+  );
+}