improvement(db): add opt-in read-replica client and harden migration runner

waleedlatif1 · waleedlatif1 · commit e71386ef73a1 · 2026-06-10T16:39:57.000-07:00
diff --git a/apps/sim/.env.example b/apps/sim/.env.example
@@ -1,5 +1,9 @@
 # Database (Required)
 DATABASE_URL="postgresql://postgres:your_password@localhost:5432/simstudio"
+# Optional read-replica connection string for offloading heavy read paths
+# (logs listing, audit logs, dashboard aggregations). Reads fall back to
+# DATABASE_URL when unset.
+# DATABASE_REPLICA_URL=""
 
 # Authentication (Required unless DISABLE_AUTH=true)
 BETTER_AUTH_SECRET=your_secret_key  # Use `openssl rand -hex 32` to generate, or visit https://www.better-auth.com/docs/installation
diff --git a/apps/sim/app/api/logs/export/route.ts b/apps/sim/app/api/logs/export/route.ts
@@ -1,4 +1,4 @@
-import { db } from '@sim/db'
+import { dbReplica } from '@sim/db'
 import { permissions, workflow, workflowExecutionLogs } from '@sim/db/schema'
 import { createLogger } from '@sim/logger'
 import { and, desc, eq, sql } from 'drizzle-orm'
@@ -80,7 +80,7 @@ export const GET = withRouteHandler(async (request: NextRequest) => {
         let offset = 0
         try {
           while (true) {
-            const rows = await db
+            const rows = await dbReplica
               .select(selectColumns)
               .from(workflowExecutionLogs)
               .leftJoin(workflow, eq(workflowExecutionLogs.workflowId, workflow.id))
diff --git a/apps/sim/app/api/logs/stats/route.ts b/apps/sim/app/api/logs/stats/route.ts
@@ -1,4 +1,4 @@
-import { db } from '@sim/db'
+import { dbReplica } from '@sim/db'
 import { permissions, workflow, workflowExecutionLogs } from '@sim/db/schema'
 import { createLogger } from '@sim/logger'
 import { and, eq, sql } from 'drizzle-orm'
@@ -48,7 +48,7 @@ export const GET = withRouteHandler(async (request: NextRequest) => {
       const commonFilters = buildFilterConditions(params, { useSimpleLevelFilter: true })
       const whereCondition = commonFilters ? and(workspaceFilter, commonFilters) : workspaceFilter
 
-      const boundsQuery = await db
+      const boundsQuery = await dbReplica
         .select({
           minTime: sql<string>`MIN(${workflowExecutionLogs.startedAt})`,
           maxTime: sql<string>`MAX(${workflowExecutionLogs.startedAt})`,
@@ -83,7 +83,7 @@ export const GET = withRouteHandler(async (request: NextRequest) => {
       const segmentMs = Math.max(60000, Math.floor(totalMs / params.segmentCount))
       const startTimeIso = startTime.toISOString()
 
-      const statsQuery = await db
+      const statsQuery = await dbReplica
         .select({
           workflowId: sql<string>`COALESCE(${workflowExecutionLogs.workflowId}, 'deleted')`,
           workflowName: sql<string>`COALESCE(${workflow.name}, 'Deleted Workflow')`,
diff --git a/apps/sim/app/api/v1/audit-logs/query.ts b/apps/sim/app/api/v1/audit-logs/query.ts
@@ -1,5 +1,5 @@
 import { AuditResourceType } from '@sim/audit'
-import { db } from '@sim/db'
+import { dbReplica } from '@sim/db'
 import { auditLog, workspace } from '@sim/db/schema'
 import type { InferSelectModel } from 'drizzle-orm'
 import { and, desc, eq, gte, ilike, inArray, isNull, lt, lte, or, type SQL, sql } from 'drizzle-orm'
@@ -73,7 +73,7 @@ export function buildFilterConditions(params: AuditLogFilterParams): SQL<unknown
  * Returns the IDs of all workspaces attached to the organization.
  */
 export async function getOrgWorkspaceIds(organizationId: string): Promise<string[]> {
-  const rows = await db
+  const rows = await dbReplica
     .select({ id: workspace.id })
     .from(workspace)
     .where(eq(workspace.organizationId, organizationId))
@@ -156,7 +156,7 @@ export async function queryAuditLogs(
     if (cursorCondition) allConditions.push(cursorCondition)
   }
 
-  const rows = await db
+  const rows = await dbReplica
     .select()
     .from(auditLog)
     .where(allConditions.length > 0 ? and(...allConditions) : undefined)
diff --git a/apps/sim/hooks/use-inline-rename.ts b/apps/sim/hooks/use-inline-rename.ts
@@ -9,7 +9,7 @@ interface UseInlineRenameProps {
    * `mutateAsync(...)`) — NOT a fire-and-forget `mutate(...)` — so `isSaving`
    * spans the in-flight request and a rejection can revive the edit session.
    */
-  onSave: (id: string, newName: string) => void | Promise<unknown>
+  onSave: (id: string, newName: string) => undefined | Promise<unknown>
 }
 
 /**
diff --git a/apps/sim/lib/billing/core/usage-log.test.ts b/apps/sim/lib/billing/core/usage-log.test.ts
@@ -28,6 +28,10 @@ vi.mock('@sim/db', () => ({
     insert: mockInsert,
     transaction: mockTransaction,
   },
+  dbReplica: {
+    insert: mockInsert,
+    transaction: mockTransaction,
+  },
 }))
 
 vi.mock('@sim/db/schema', () => ({
diff --git a/apps/sim/lib/billing/core/usage-log.ts b/apps/sim/lib/billing/core/usage-log.ts
@@ -1,5 +1,5 @@
 import { createHash } from 'node:crypto'
-import { db } from '@sim/db'
+import { db, dbReplica } from '@sim/db'
 import { usageLog, workspace } from '@sim/db/schema'
 import { createLogger } from '@sim/logger'
 import { toError } from '@sim/utils/errors'
@@ -579,7 +579,7 @@ export async function getUserUsageLogs(
     }
 
     if (cursor) {
-      const cursorLog = await db
+      const cursorLog = await dbReplica
         .select({ createdAt: usageLog.createdAt })
         .from(usageLog)
         .where(eq(usageLog.id, cursor))
@@ -592,7 +592,7 @@ export async function getUserUsageLogs(
       }
     }
 
-    const logs = await db
+    const logs = await dbReplica
       .select()
       .from(usageLog)
       .where(and(...conditions))
@@ -621,7 +621,7 @@ export async function getUserUsageLogs(
     if (startDate) summaryConditions.push(gte(usageLog.createdAt, startDate))
     if (endDate) summaryConditions.push(lte(usageLog.createdAt, endDate))
 
-    const summaryResult = await db
+    const summaryResult = await dbReplica
       .select({
         source: usageLog.source,
         totalCost: sql<string>`SUM(${usageLog.cost})`,
diff --git a/apps/sim/lib/core/config/env.ts b/apps/sim/lib/core/config/env.ts
@@ -19,6 +19,7 @@ export const env = createEnv({
   server: {
     // Core Database & Authentication
     DATABASE_URL:                          z.string().url(),                       // Primary database connection string
+    DATABASE_REPLICA_URL:                  z.string().url().optional(),            // Read-replica connection string; opt-in reads fall back to the primary when unset
     BETTER_AUTH_URL:                       z.string().url(),                       // Base URL for Better Auth service
     BETTER_AUTH_SECRET:                    z.string().min(32),                     // Secret key for Better Auth JWT signing
     DISABLE_REGISTRATION:                  z.boolean().optional(),                 // Flag to disable new user registration
diff --git a/apps/sim/lib/data-drains/sources/audit-logs.ts b/apps/sim/lib/data-drains/sources/audit-logs.ts
@@ -1,4 +1,4 @@
-import { db } from '@sim/db'
+import { dbReplica } from '@sim/db'
 import { auditLog } from '@sim/db/schema'
 import { and, inArray, isNull, or, sql } from 'drizzle-orm'
 import {
@@ -35,7 +35,7 @@ async function* pages(input: SourcePageInput): AsyncIterable<AuditLogRow[]> {
   while (!input.signal.aborted) {
     const cursorClause = timeCursorPredicate(auditLog.createdAt, auditLog.id, cursor)
 
-    const rows = await db
+    const rows = await dbReplica
       .select()
       .from(auditLog)
       .where(and(scopeClause, cursorClause))
diff --git a/apps/sim/lib/data-drains/sources/copilot-chats.ts b/apps/sim/lib/data-drains/sources/copilot-chats.ts
@@ -1,4 +1,4 @@
-import { db } from '@sim/db'
+import { dbReplica } from '@sim/db'
 import { copilotChats, copilotMessages } from '@sim/db/schema'
 import { and, asc, inArray, isNull, sql } from 'drizzle-orm'
 import {
@@ -55,7 +55,7 @@ async function* pages(input: SourcePageInput): AsyncIterable<CopilotChatRow[]> {
   while (!input.signal.aborted) {
     const cursorClause = timeCursorPredicate(copilotChats.createdAt, copilotChats.id, cursor)
 
-    const metaRows = await db
+    const metaRows = await dbReplica
       .select(chatColumns)
       .from(copilotChats)
       .where(and(inArray(copilotChats.workspaceId, workspaceIds), cursorClause))
@@ -65,7 +65,7 @@ async function* pages(input: SourcePageInput): AsyncIterable<CopilotChatRow[]> {
     if (metaRows.length === 0) return
 
     const chatIds = metaRows.map((r) => r.id)
-    const messageRows = await db
+    const messageRows = await dbReplica
       .select({ chatId: copilotMessages.chatId, content: copilotMessages.content })
       .from(copilotMessages)
       .where(and(inArray(copilotMessages.chatId, chatIds), isNull(copilotMessages.deletedAt)))
diff --git a/apps/sim/lib/data-drains/sources/copilot-runs.ts b/apps/sim/lib/data-drains/sources/copilot-runs.ts
@@ -1,4 +1,4 @@
-import { db } from '@sim/db'
+import { dbReplica } from '@sim/db'
 import { copilotRuns } from '@sim/db/schema'
 import { and, inArray, isNotNull } from 'drizzle-orm'
 import {
@@ -24,7 +24,7 @@ async function* pages(input: SourcePageInput): AsyncIterable<CopilotRunRow[]> {
   while (!input.signal.aborted) {
     const cursorClause = timeCursorPredicate(copilotRuns.completedAt, copilotRuns.id, cursor)
 
-    const rows = await db
+    const rows = await dbReplica
       .select()
       .from(copilotRuns)
       .where(
diff --git a/apps/sim/lib/data-drains/sources/helpers.ts b/apps/sim/lib/data-drains/sources/helpers.ts
@@ -1,4 +1,4 @@
-import { db } from '@sim/db'
+import { dbReplica } from '@sim/db'
 import { workspace } from '@sim/db/schema'
 import { eq } from 'drizzle-orm'
 
@@ -7,7 +7,7 @@ import { eq } from 'drizzle-orm'
  * sources whose underlying tables are workspace-scoped rather than org-scoped.
  */
 export async function getOrganizationWorkspaceIds(organizationId: string): Promise<string[]> {
-  const rows = await db
+  const rows = await dbReplica
     .select({ id: workspace.id })
     .from(workspace)
     .where(eq(workspace.organizationId, organizationId))
diff --git a/apps/sim/lib/data-drains/sources/job-logs.ts b/apps/sim/lib/data-drains/sources/job-logs.ts
@@ -1,4 +1,4 @@
-import { db } from '@sim/db'
+import { dbReplica } from '@sim/db'
 import { jobExecutionLogs } from '@sim/db/schema'
 import { and, inArray, isNotNull } from 'drizzle-orm'
 import {
@@ -24,7 +24,7 @@ async function* pages(input: SourcePageInput): AsyncIterable<JobLogRow[]> {
   while (!input.signal.aborted) {
     const cursorClause = timeCursorPredicate(jobExecutionLogs.endedAt, jobExecutionLogs.id, cursor)
 
-    const rows = await db
+    const rows = await dbReplica
       .select()
       .from(jobExecutionLogs)
       .where(
diff --git a/apps/sim/lib/data-drains/sources/workflow-logs.ts b/apps/sim/lib/data-drains/sources/workflow-logs.ts
@@ -1,4 +1,4 @@
-import { db } from '@sim/db'
+import { dbReplica } from '@sim/db'
 import { workflowExecutionLogs } from '@sim/db/schema'
 import { and, inArray, isNotNull } from 'drizzle-orm'
 import { MATERIALIZE_CONCURRENCY, mapWithConcurrency } from '@/lib/core/utils/concurrency'
@@ -33,7 +33,7 @@ async function* pages(input: SourcePageInput): AsyncIterable<WorkflowLogRow[]> {
       cursor
     )
 
-    const rows = await db
+    const rows = await dbReplica
       .select()
       .from(workflowExecutionLogs)
       .where(
diff --git a/apps/sim/lib/logs/list-logs.test.ts b/apps/sim/lib/logs/list-logs.test.ts
@@ -10,6 +10,9 @@ vi.mock('@sim/db', () => ({
   db: {
     select: selectMock,
   },
+  dbReplica: {
+    select: selectMock,
+  },
 }))
 
 // Local drizzle-orm mock: the global mock's `sql` lacks `.as()` and the chain
diff --git a/apps/sim/lib/logs/list-logs.ts b/apps/sim/lib/logs/list-logs.ts
@@ -1,4 +1,4 @@
-import { db } from '@sim/db'
+import { dbReplica } from '@sim/db'
 import {
   jobExecutionLogs,
   pausedExecutions,
@@ -186,7 +186,7 @@ export async function listLogs(params: ListLogsParams, userId: string): Promise<
     levelList.length > 0 && !levelList.some((l) => l === 'error' || l === 'info')
   const includeJobLogs = !hasWorkflowSpecificFilters && !triggersExcludeJobs && !levelExcludesJobs
 
-  const workflowQuery = db
+  const workflowQuery = dbReplica
     .select({
       id: workflowExecutionLogs.id,
       workflowId: workflowExecutionLogs.workflowId,
@@ -313,7 +313,7 @@ export async function listLogs(params: ListLogsParams, userId: string): Promise<
   }
 
   const jobQuery = includeJobLogs
-    ? db
+    ? dbReplica
         .select({
           id: jobExecutionLogs.id,
           executionId: jobExecutionLogs.executionId,
diff --git a/packages/db/.env.example b/packages/db/.env.example
@@ -1,5 +1,6 @@
 # Database connection used by @sim/db scripts (drizzle-kit generate,
 # db:migrate, register-sso-provider, etc.). Must match DATABASE_URL in
-# apps/sim/.env and apps/realtime/.env.
+# apps/sim/.env and apps/realtime/.env. Migrations always run against the
+# primary — never set a replica URL here.
 
 DATABASE_URL="postgresql://postgres:postgres@localhost:5432/simstudio"
diff --git a/packages/db/db.ts b/packages/db/db.ts
@@ -7,12 +7,31 @@ if (!connectionString) {
   throw new Error('Missing DATABASE_URL environment variable')
 }
 
-const postgresClient = postgres(connectionString, {
+const poolOptions = {
   prepare: false,
   idle_timeout: 20,
   connect_timeout: 30,
-  max: 15,
   onnotice: () => {},
-})
+} as const
+
+const postgresClient = postgres(connectionString, { ...poolOptions, max: 15 })
 
 export const db = drizzle(postgresClient, { schema })
+
+/**
+ * Read-replica client — EXPLICIT OPT-IN.
+ *
+ * Import `dbReplica` only for reads that tolerate bounded staleness and have no
+ * read-your-writes dependency: logs listing/search, audit logs, dashboard
+ * aggregations, bulk exports. Never use it for auth/session lookups, workflow
+ * state, billing-limit enforcement, or any read inside a write-reconciling
+ * flow.
+ *
+ * Falls back to the primary client when `DATABASE_REPLICA_URL` is unset (dev,
+ * self-hosted, realtime), so call sites never need to branch.
+ */
+const replicaUrl = process.env.DATABASE_REPLICA_URL
+
+export const dbReplica: typeof db = replicaUrl
+  ? drizzle(postgres(replicaUrl, { ...poolOptions, max: 10 }), { schema })
+  : db
diff --git a/packages/db/scripts/migrate.ts b/packages/db/scripts/migrate.ts
diff --git a/packages/testing/src/mocks/database.mock.ts b/packages/testing/src/mocks/database.mock.ts

Original file line number	Diff line number	Diff line change
`@@ -9,7 +9,7 @@ interface UseInlineRenameProps {`
`9`	`9`	* `mutateAsync(...)`) — NOT a fire-and-forget `mutate(...)` — so `isSaving`
`10`	`10`	`* spans the in-flight request and a rejection can revive the edit session.`
`11`	`11`	`*/`
`12`		`- onSave: (id: string, newName: string) => void \| Promise<unknown>`
	`12`	`+ onSave: (id: string, newName: string) => undefined \| Promise<unknown>`
`13`	`13`	`}`
`14`	`14`
`15`	`15`	`/**`