@everystack/server 0.3.7 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/server",
-  "version": "0.3.7",
+  "version": "0.4.0",
   "description": "Server runtime primitives for Lambda — event adapters, routing, SSR, image processing",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",

package/src/db.ts

@@ -262,3 +262,75 @@ export function getAdminSql(): ReturnType<typeof postgres> {
   if (adminSqlClient) return adminSqlClient;
   return getSql();
 }
+
+/**
+ * Resolve the read-replica database URL, if configured.
+ *
+ * The third credential slot: DATABASE_URL (api), ADMIN_DATABASE_URL (operator),
+ * READ_DATABASE_URL (replica). Point it at a physical read replica's endpoint
+ * with the SAME least-privilege role as DATABASE_URL — same credential,
+ * different host. Returns null when no replica is configured.
+ */
+export function getReadDatabaseUrl(): string | null {
+  // SST Secret — PascalCase (Resource.ReadDatabaseUrl.value)
+  const pascal = tryResource(() => (Resource as any).ReadDatabaseUrl?.value as string);
+  if (pascal) return pascal;
+  // SST Secret — raw env name (Resource.READ_DATABASE_URL.value)
+  const raw = tryResource(() => (Resource as any).READ_DATABASE_URL?.value as string);
+  if (raw) return raw;
+  // process.env fallback
+  if (process.env.READ_DATABASE_URL) return process.env.READ_DATABASE_URL;
+  return null;
+}
+
+// Lazy singleton read-replica connection (separate from the API connection)
+let readDbInstance: ReturnType<typeof drizzle> | null = null;
+let readSqlClient: ReturnType<typeof postgres> | null = null;
+
+/**
+ * Read-replica database connection for anonymous read traffic.
+ *
+ * Connects with READ_DATABASE_URL when configured. When it isn't, returns the
+ * primary connection (createDb) with NO warning — unlike the admin split this
+ * is a scaling knob, not a security boundary: absent is normal, not a
+ * misconfiguration. Apps without a replica keep working with zero config.
+ *
+ * `withRole` works unchanged against a hot standby: SET LOCAL ROLE and
+ * set_config(…, true) are permitted in read-only transactions, and physical
+ * replication carries roles, GRANTs, and RLS policies with the catalog. A
+ * write through this connection fails loudly on a real replica ("cannot
+ * execute … in a read-only transaction") — a routing bug can never silently
+ * diverge. See docs/plans/read-replica-routing.md.
+ */
+export function createReadDb<T extends Record<string, unknown>>(
+  schema: T,
+  options?: { maxConnections?: number }
+): {
+  db: ReturnType<typeof drizzle>;
+  schema: T;
+} {
+  if (readDbInstance) return { db: readDbInstance, schema };
+
+  const url = getReadDatabaseUrl();
+  if (!url) return createDb(schema, options);
+
+  readSqlClient = postgres(url, {
+    max: options?.maxConnections ?? 1,
+    idle_timeout: 60,
+    connect_timeout: 5,
+    max_lifetime: 60 * 5,
+    ssl: 'require',
+  });
+  readDbInstance = drizzle(readSqlClient, { schema });
+  return { db: readDbInstance, schema };
+}
+
+/**
+ * Raw postgres.js client for the read-replica connection.
+ * Must be called after createReadDb(). Falls back to the API client when no
+ * replica is configured (same fallback as createReadDb).
+ */
+export function getReadSql(): ReturnType<typeof postgres> {
+  if (readSqlClient) return readSqlClient;
+  return getSql();
+}