@risingwave/wavelet-server 0.1.3 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@risingwave/wavelet-server",
-  "version": "0.1.3",
+  "version": "0.2.1",
   "description": "Wavelet server - WebSocket fanout layer for RisingWave",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -13,7 +13,7 @@
     "pg": "^8.13.0",
     "ws": "^8.18.0",
     "jose": "^6.0.0",
-    "@risingwave/wavelet": "0.1.3"
+    "@risingwave/wavelet": "0.2.1"
   },
   "devDependencies": {
     "@types/pg": "^8.11.0",

package/src/__tests__/http-api.test.ts

@@ -36,15 +36,15 @@ function request(server: http.Server, method: string, path: string, body?: unkno
 }
 
 describe('HttpApi', () => {
-  const streams = {
-    events: { columns: { user_id: 'string' as const, value: 'int' as const } },
+  const events = {
+    game_events: { columns: { user_id: 'string' as const, value: 'int' as const } },
   }
-  const views = {
+  const queries = {
     leaderboard: { _tag: 'sql' as const, text: 'SELECT 1' },
   }
 
   it('returns health check', async () => {
-    const api = new HttpApi('postgres://dummy', streams, views)
+    const api = new HttpApi('postgres://dummy', events, queries)
     const server = await createTestServer(api)
     try {
       const res = await request(server, 'GET', '/v1/health')
@@ -55,32 +55,32 @@ describe('HttpApi', () => {
     }
   })
 
-  it('lists available views', async () => {
-    const api = new HttpApi('postgres://dummy', streams, views)
+  it('lists available queries', async () => {
+    const api = new HttpApi('postgres://dummy', events, queries)
     const server = await createTestServer(api)
     try {
-      const res = await request(server, 'GET', '/v1/views')
+      const res = await request(server, 'GET', '/v1/queries')
       expect(res.status).toBe(200)
-      expect(res.data).toEqual({ views: ['leaderboard'] })
+      expect(res.data).toEqual({ queries: ['leaderboard'] })
     } finally {
       server.close()
     }
   })
 
-  it('lists available streams', async () => {
-    const api = new HttpApi('postgres://dummy', streams, views)
+  it('lists available events', async () => {
+    const api = new HttpApi('postgres://dummy', events, queries)
     const server = await createTestServer(api)
     try {
-      const res = await request(server, 'GET', '/v1/streams')
+      const res = await request(server, 'GET', '/v1/events')
       expect(res.status).toBe(200)
-      expect(res.data).toEqual({ streams: ['events'] })
+      expect(res.data).toEqual({ events: ['game_events'] })
     } finally {
       server.close()
     }
   })
 
   it('returns 404 for unknown routes with helpful message', async () => {
-    const api = new HttpApi('postgres://dummy', streams, views)
+    const api = new HttpApi('postgres://dummy', events, queries)
     const server = await createTestServer(api)
     try {
       const res = await request(server, 'GET', '/v1/nonexistent')
@@ -94,35 +94,35 @@ describe('HttpApi', () => {
   })
 
   it('handles CORS preflight', async () => {
-    const api = new HttpApi('postgres://dummy', streams, views)
+    const api = new HttpApi('postgres://dummy', events, queries)
     const server = await createTestServer(api)
     try {
-      const res = await request(server, 'OPTIONS', '/v1/views')
+      const res = await request(server, 'OPTIONS', '/v1/queries')
       expect(res.status).toBe(204)
     } finally {
       server.close()
     }
   })
 
-  it('returns 404 for unknown stream', async () => {
-    const api = new HttpApi('postgres://dummy', streams, views)
+  it('returns 404 for unknown event', async () => {
+    const api = new HttpApi('postgres://dummy', events, queries)
     const server = await createTestServer(api)
     try {
-      const res = await request(server, 'POST', '/v1/streams/nonexistent', { x: 1 })
+      const res = await request(server, 'POST', '/v1/events/nonexistent', { x: 1 })
       expect(res.status).toBe(404)
-      expect(res.data.available_streams).toEqual(['events'])
+      expect(res.data.available_events).toEqual(['game_events'])
     } finally {
       server.close()
     }
   })
 
-  it('returns 404 for unknown view', async () => {
-    const api = new HttpApi('postgres://dummy', streams, views)
+  it('returns 404 for unknown query', async () => {
+    const api = new HttpApi('postgres://dummy', events, queries)
     const server = await createTestServer(api)
     try {
-      const res = await request(server, 'GET', '/v1/views/nonexistent')
+      const res = await request(server, 'GET', '/v1/queries/nonexistent')
       expect(res.status).toBe(404)
-      expect(res.data.available_views).toEqual(['leaderboard'])
+      expect(res.data.available_queries).toEqual(['leaderboard'])
     } finally {
       server.close()
     }

package/src/__tests__/integration.test.ts

@@ -36,7 +36,7 @@ const SUB_NAME = `wavelet_sub_${VIEW_NAME}`
 
 const testConfig: WaveletConfig = {
   database: DATABASE_URL,
-  streams: {
+  events: {
     [STREAM_NAME]: {
       columns: {
         user_id: 'string',
@@ -44,7 +44,7 @@ const testConfig: WaveletConfig = {
       },
     },
   },
-  views: {
+  queries: {
     [VIEW_NAME]: sql`
       SELECT user_id, SUM(value) AS total_value, COUNT(*) AS event_count
       FROM ${STREAM_NAME}
@@ -75,17 +75,17 @@ describe.runIf(process.env.WAVELET_INTEGRATION === '1')('Integration: DDL Manage
     await ddl.close()
   })
 
-  it('creates tables, views, and subscriptions', async () => {
+  it('creates tables, materialized views, and subscriptions', async () => {
     const actions = await ddl.sync(testConfig)
 
     const creates = actions.filter(a => a.type === 'create')
-    expect(creates.length).toBeGreaterThanOrEqual(3) // stream + view + subscription
+    expect(creates.length).toBeGreaterThanOrEqual(3) // event + query + subscription
 
-    const streamAction = creates.find(a => a.resource === 'stream' && a.name === STREAM_NAME)
-    expect(streamAction).toBeDefined()
+    const eventAction = creates.find(a => a.resource === 'event' && a.name === STREAM_NAME)
+    expect(eventAction).toBeDefined()
 
-    const viewAction = creates.find(a => a.resource === 'view' && a.name === VIEW_NAME)
-    expect(viewAction).toBeDefined()
+    const queryAction = creates.find(a => a.resource === 'query' && a.name === VIEW_NAME)
+    expect(queryAction).toBeDefined()
 
     const subAction = creates.find(a => a.resource === 'subscription' && a.name === SUB_NAME)
     expect(subAction).toBeDefined()
@@ -162,15 +162,15 @@ describe.runIf(process.env.WAVELET_INTEGRATION === '1')('Integration: Full Serve
     expect(data.status).toBe('ok')
   })
 
-  it('lists views', async () => {
-    const res = await fetch(`http://localhost:${port}/v1/views`)
+  it('lists queries', async () => {
+    const res = await fetch(`http://localhost:${port}/v1/queries`)
     const data = await res.json()
-    expect(data.views).toContain(VIEW_NAME)
+    expect(data.queries).toContain(VIEW_NAME)
   })
 
-  it('writes events via HTTP and reads view', async () => {
+  it('writes events via HTTP and reads query', async () => {
     // Write events
-    await fetch(`http://localhost:${port}/v1/streams/${STREAM_NAME}`, {
+    await fetch(`http://localhost:${port}/v1/events/${STREAM_NAME}`, {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
       body: JSON.stringify({ user_id: 'integration_test', value: 42 }),
@@ -179,8 +179,8 @@ describe.runIf(process.env.WAVELET_INTEGRATION === '1')('Integration: Full Serve
     // Wait for MV update
     await new Promise(r => setTimeout(r, 2000))
 
-    // Read view
-    const res = await fetch(`http://localhost:${port}/v1/views/${VIEW_NAME}`)
+    // Read query
+    const res = await fetch(`http://localhost:${port}/v1/queries/${VIEW_NAME}`)
     const data = await res.json()
     expect(data.rows.length).toBeGreaterThan(0)
   })
@@ -193,7 +193,7 @@ describe.runIf(process.env.WAVELET_INTEGRATION === '1')('Integration: Full Serve
         const msg = JSON.parse(data.toString())
         if (msg.type === 'connected') {
           // Write event to trigger diff
-          fetch(`http://localhost:${port}/v1/streams/${STREAM_NAME}`, {
+          fetch(`http://localhost:${port}/v1/events/${STREAM_NAME}`, {
             method: 'POST',
             headers: { 'Content-Type': 'application/json' },
             body: JSON.stringify({ user_id: 'ws_test_user', value: 7 }),

package/src/cursor-manager.ts

@@ -1,5 +1,5 @@
 import pg from 'pg'
-import type { SqlFragment, ViewDef } from '@risingwave/wavelet'
+import type { SqlFragment, QueryDef } from '@risingwave/wavelet'
 
 const { Client } = pg
 
@@ -16,12 +16,12 @@ export interface ViewDiff {
   deleted: Record<string, unknown>[]
 }
 
-type DiffCallback = (viewName: string, diff: ViewDiff) => void
+type DiffCallback = (queryName: string, diff: ViewDiff) => void
 
 /**
  * Manages persistent subscription cursors against RisingWave.
  *
- * Each view gets its own dedicated pg connection and a persistent cursor.
+ * Each query gets its own dedicated pg connection and a persistent cursor.
  * Uses blocking FETCH (WITH timeout) so there is no polling interval -
  * diffs are dispatched as soon as RisingWave produces them.
  */
@@ -29,15 +29,15 @@ export class CursorManager {
   // Shared connection for DDL (CREATE SUBSCRIPTION) and ad-hoc queries
   private client: InstanceType<typeof Client> | null = null
 
-  // Per-view dedicated connections for blocking FETCH
-  private viewConnections: Map<string, InstanceType<typeof Client>> = new Map()
+  // Per-query dedicated connections for blocking FETCH
+  private queryConnections: Map<string, InstanceType<typeof Client>> = new Map()
   private cursorNames: Map<string, string> = new Map()
   private subscriptions: Map<string, string> = new Map()
   private running = false
 
   constructor(
     private connectionString: string,
-    private views: Record<string, ViewDef | SqlFragment>
+    private queries: Record<string, QueryDef | SqlFragment>
   ) {}
 
   async initialize(): Promise<void> {
@@ -45,13 +45,13 @@ export class CursorManager {
     await this.client.connect()
     console.log('Connected to RisingWave')
 
-    for (const [viewName] of Object.entries(this.views)) {
-      const subName = `wavelet_sub_${viewName}`
+    for (const [queryName] of Object.entries(this.queries)) {
+      const subName = `wavelet_sub_${queryName}`
 
       // Create subscription if not exists (idempotent)
       try {
         await this.client.query(
-          `CREATE SUBSCRIPTION ${subName} FROM ${viewName} WITH (retention = '24h')`
+          `CREATE SUBSCRIPTION ${subName} FROM ${queryName} WITH (retention = '24h')`
         )
         console.log(`Created subscription: ${subName}`)
       } catch (err: any) {
@@ -62,31 +62,31 @@ export class CursorManager {
         }
       }
 
-      this.subscriptions.set(viewName, subName)
+      this.subscriptions.set(queryName, subName)
 
-      // Create dedicated connection and persistent cursor for this view
+      // Create dedicated connection and persistent cursor for this query
       const conn = new Client({ connectionString: this.connectionString })
       await conn.connect()
 
-      const cursorName = `wavelet_cur_${viewName}`
+      const cursorName = `wavelet_cur_${queryName}`
       await conn.query(`DECLARE ${cursorName} SUBSCRIPTION CURSOR FOR ${subName}`)
       console.log(`Opened persistent cursor: ${cursorName}`)
 
-      this.viewConnections.set(viewName, conn)
-      this.cursorNames.set(viewName, cursorName)
+      this.queryConnections.set(queryName, conn)
+      this.cursorNames.set(queryName, cursorName)
     }
   }
 
   /**
-   * Start listening for diffs on all views.
-   * Each view runs its own async loop with blocking FETCH.
+   * Start listening for diffs on all queries.
+   * Each query runs its own async loop with blocking FETCH.
    * No polling interval - FETCH blocks until data arrives or timeout.
    */
   startPolling(callback: DiffCallback): void {
     this.running = true
 
-    for (const [viewName] of this.subscriptions.entries()) {
-      this.listenLoop(viewName, callback)
+    for (const [queryName] of this.subscriptions.entries()) {
+      this.listenLoop(queryName, callback)
     }
   }
 
@@ -94,9 +94,9 @@ export class CursorManager {
     this.running = false
   }
 
-  private async listenLoop(viewName: string, callback: DiffCallback): Promise<void> {
-    const conn = this.viewConnections.get(viewName)
-    const cursorName = this.cursorNames.get(viewName)
+  private async listenLoop(queryName: string, callback: DiffCallback): Promise<void> {
+    const conn = this.queryConnections.get(queryName)
+    const cursorName = this.cursorNames.get(queryName)
     if (!conn || !cursorName) return
 
     while (this.running) {
@@ -108,12 +108,12 @@ export class CursorManager {
 
         if (result.rows.length === 0) continue
 
-        // Got at least one row. Drain any remaining rows without blocking.
+        // Got at least one row. Drain any remaining rows with timeout.
         const allRows = [...result.rows]
         let more = true
         while (more) {
           const batch = await conn.query(
-            `FETCH 100 FROM ${cursorName}`
+            `FETCH 100 FROM ${cursorName} WITH (timeout = '1s')`
           )
           if (batch.rows.length > 0) {
             allRows.push(...batch.rows)
@@ -125,11 +125,11 @@ export class CursorManager {
         const diff = this.parseDiffs(allRows)
 
         if (diff.inserted.length > 0 || diff.updated.length > 0 || diff.deleted.length > 0) {
-          callback(viewName, diff)
+          callback(queryName, diff)
         }
       } catch (err: any) {
         if (!this.running) return
-        console.error(`[cursor-manager] Error fetching ${viewName}:`, err.message)
+        console.error(`[cursor-manager] Error fetching ${queryName}:`, err.message)
         // Back off on error, then retry
         await new Promise(r => setTimeout(r, 1000))
       }
@@ -187,9 +187,9 @@ export class CursorManager {
   async close(): Promise<void> {
     this.running = false
 
-    // Close per-view connections
-    for (const [viewName, conn] of this.viewConnections) {
-      const cursorName = this.cursorNames.get(viewName)
+    // Close per-query connections
+    for (const [queryName, conn] of this.queryConnections) {
+      const cursorName = this.cursorNames.get(queryName)
       try {
         if (cursorName) await conn.query(`CLOSE ${cursorName}`)
       } catch {}
@@ -197,7 +197,7 @@ export class CursorManager {
         await conn.end()
       } catch {}
     }
-    this.viewConnections.clear()
+    this.queryConnections.clear()
     this.cursorNames.clear()
 
     // Close shared connection

package/src/ddl-manager.ts

@@ -1,11 +1,11 @@
 import pg from 'pg'
-import type { WaveletConfig, StreamDef, ViewDef, SqlFragment } from '@risingwave/wavelet'
+import type { WaveletConfig, EventDef, QueryDef, SqlFragment, PostgresCdcSource } from '@risingwave/wavelet'
 
 const { Client } = pg
 
 export interface DdlAction {
   type: 'create' | 'update' | 'delete' | 'unchanged'
-  resource: 'stream' | 'view' | 'subscription'
+  resource: 'event' | 'source' | 'query' | 'subscription'
   name: string
   detail?: string
 }
@@ -26,13 +26,13 @@ function normalizeSql(sql: string): string {
   return stripped.replace(/\s+/g, ' ').trim().toLowerCase()
 }
 
-function getViewQuery(viewDef: ViewDef | SqlFragment): string {
-  if ('_tag' in viewDef && viewDef._tag === 'sql') return viewDef.text
-  return (viewDef as ViewDef).query.text
+function getQuerySql(queryDef: QueryDef | SqlFragment): string {
+  if ('_tag' in queryDef && queryDef._tag === 'sql') return queryDef.text
+  return (queryDef as QueryDef).query.text
 }
 
-function buildCreateTableSql(name: string, streamDef: StreamDef): string {
-  const cols = Object.entries(streamDef.columns)
+function buildCreateTableSql(name: string, eventDef: EventDef): string {
+  const cols = Object.entries(eventDef.columns)
     .map(([colName, colType]) => {
       const sqlType = COLUMN_TYPE_MAP[colType]
       if (!sqlType) throw new Error(`Unknown column type "${colType}" for column "${colName}"`)
@@ -60,7 +60,7 @@ export class DdlManager {
   }
 
   /**
-   * Sync all streams, views, and subscriptions to match the config.
+   * Sync all events, queries, and subscriptions to match the config.
    * Returns a list of actions taken.
    * Idempotent - safe to call multiple times.
    */
@@ -71,61 +71,78 @@ export class DdlManager {
 
     // 1. Fetch existing state from RisingWave
     const existingTables = await this.getExistingTables()
-    const existingViews = await this.getExistingViews()
+    const existingMVs = await this.getExistingMaterializedViews()
     const existingSubscriptions = await this.getExistingSubscriptions()
 
-    const desiredStreams = config.streams ?? {}
-    const desiredViews = config.views ?? {}
+    const desiredEvents = config.events ?? config.streams ?? {}
+    const desiredSources = config.sources ?? {}
+    const desiredQueries = config.queries ?? config.views ?? {}
 
-    // 2. Determine which streams (tables) to create or remove
-    const desiredStreamNames = new Set(Object.keys(desiredStreams))
-    const desiredViewNames = new Set(Object.keys(desiredViews))
+    // 2. Determine which events (tables) to create or remove
+    const desiredEventNames = new Set(Object.keys(desiredEvents))
+    const desiredQueryNames = new Set(Object.keys(desiredQueries))
 
-    // 3. Sync streams - create missing tables
-    for (const [streamName, streamDef] of Object.entries(desiredStreams)) {
-      if (existingTables.has(streamName)) {
-        actions.push({ type: 'unchanged', resource: 'stream', name: streamName })
+    // 3. Sync events - create missing tables
+    for (const [eventName, eventDef] of Object.entries(desiredEvents)) {
+      if (existingTables.has(eventName)) {
+        actions.push({ type: 'unchanged', resource: 'event', name: eventName })
       } else {
-        await this.createTable(streamName, streamDef)
-        actions.push({ type: 'create', resource: 'stream', name: streamName })
+        await this.createTable(eventName, eventDef)
+        actions.push({ type: 'create', resource: 'event', name: eventName })
       }
     }
 
-    // 4. Sync views - create, update, or leave unchanged
-    for (const [viewName, viewDef] of Object.entries(desiredViews)) {
-      const subName = `wavelet_sub_${viewName}`
-      const desiredSql = getViewQuery(viewDef)
-      const existingSql = existingViews.get(viewName)
+    // 3b. Sync CDC sources - create Postgres CDC tables
+    const existingSources = await this.getExistingSources()
+    for (const [sourceName, sourceDef] of Object.entries(desiredSources)) {
+      if (sourceDef.type === 'postgres') {
+        for (const tableName of sourceDef.tables) {
+          const cdcTableName = `${sourceName}_${tableName}`
+          if (existingSources.has(cdcTableName) || existingTables.has(cdcTableName)) {
+            actions.push({ type: 'unchanged', resource: 'source', name: cdcTableName })
+          } else {
+            await this.createCdcSource(sourceName, tableName, sourceDef)
+            actions.push({ type: 'create', resource: 'source', name: cdcTableName })
+          }
+        }
+      }
+    }
+
+    // 4. Sync queries - create, update, or leave unchanged
+    for (const [queryName, queryDef] of Object.entries(desiredQueries)) {
+      const subName = `wavelet_sub_${queryName}`
+      const desiredSql = getQuerySql(queryDef)
+      const existingSql = existingMVs.get(queryName)
 
       if (existingSql === undefined) {
-        // View does not exist - create MV and subscription
-        await this.createMaterializedView(viewName, desiredSql)
-        actions.push({ type: 'create', resource: 'view', name: viewName })
+        // MV does not exist - create MV and subscription
+        await this.createMaterializedView(queryName, desiredSql)
+        actions.push({ type: 'create', resource: 'query', name: queryName })
 
-        await this.createSubscription(subName, viewName)
+        await this.createSubscription(subName, queryName)
         actions.push({ type: 'create', resource: 'subscription', name: subName })
       } else if (normalizeSql(existingSql) !== normalizeSql(desiredSql)) {
-        // View SQL changed - drop subscription, drop MV, recreate
+        // Query SQL changed - drop subscription, drop MV, recreate
         if (existingSubscriptions.has(subName)) {
           await this.dropSubscription(subName)
-          actions.push({ type: 'delete', resource: 'subscription', name: subName, detail: 'dropped for view update' })
+          actions.push({ type: 'delete', resource: 'subscription', name: subName, detail: 'dropped for query update' })
         }
 
-        await this.dropMaterializedView(viewName)
-        actions.push({ type: 'delete', resource: 'view', name: viewName, detail: 'dropped for update' })
+        await this.dropMaterializedView(queryName)
+        actions.push({ type: 'delete', resource: 'query', name: queryName, detail: 'dropped for update' })
 
-        await this.createMaterializedView(viewName, desiredSql)
-        actions.push({ type: 'create', resource: 'view', name: viewName, detail: 'recreated with updated SQL' })
+        await this.createMaterializedView(queryName, desiredSql)
+        actions.push({ type: 'create', resource: 'query', name: queryName, detail: 'recreated with updated SQL' })
 
-        await this.createSubscription(subName, viewName)
-        actions.push({ type: 'create', resource: 'subscription', name: subName, detail: 'recreated after view update' })
+        await this.createSubscription(subName, queryName)
+        actions.push({ type: 'create', resource: 'subscription', name: subName, detail: 'recreated after query update' })
       } else {
-        // View SQL unchanged
-        actions.push({ type: 'unchanged', resource: 'view', name: viewName })
+        // Query SQL unchanged
+        actions.push({ type: 'unchanged', resource: 'query', name: queryName })
 
-        // Ensure subscription exists even if the view is unchanged
+        // Ensure subscription exists even if the query is unchanged
         if (!existingSubscriptions.has(subName)) {
-          await this.createSubscription(subName, viewName)
+          await this.createSubscription(subName, queryName)
           actions.push({ type: 'create', resource: 'subscription', name: subName })
         } else {
           actions.push({ type: 'unchanged', resource: 'subscription', name: subName })
@@ -133,19 +150,19 @@ export class DdlManager {
       }
     }
 
-    // 5. Remove views that are no longer in the config
-    for (const [existingViewName] of existingViews) {
-      if (!desiredViewNames.has(existingViewName)) {
-        const subName = `wavelet_sub_${existingViewName}`
+    // 5. Remove queries that are no longer in the config
+    for (const [existingMVName] of existingMVs) {
+      if (!desiredQueryNames.has(existingMVName)) {
+        const subName = `wavelet_sub_${existingMVName}`
 
         // Drop subscription first
         if (existingSubscriptions.has(subName)) {
           await this.dropSubscription(subName)
-          actions.push({ type: 'delete', resource: 'subscription', name: subName, detail: 'view removed from config' })
+          actions.push({ type: 'delete', resource: 'subscription', name: subName, detail: 'query removed from config' })
         }
 
-        await this.dropMaterializedView(existingViewName)
-        actions.push({ type: 'delete', resource: 'view', name: existingViewName, detail: 'removed from config' })
+        await this.dropMaterializedView(existingMVName)
+        actions.push({ type: 'delete', resource: 'query', name: existingMVName, detail: 'removed from config' })
       }
     }
 
@@ -154,32 +171,32 @@ export class DdlManager {
       // Only manage wavelet-prefixed subscriptions
       if (!existingSubName.startsWith('wavelet_sub_')) continue
 
-      const viewName = existingSubName.slice('wavelet_sub_'.length)
-      if (!desiredViewNames.has(viewName)) {
-        // Already handled in step 5 if the view existed, but handle dangling subs too
-        if (!existingViews.has(viewName)) {
+      const queryName = existingSubName.slice('wavelet_sub_'.length)
+      if (!desiredQueryNames.has(queryName)) {
+        // Already handled in step 5 if the MV existed, but handle dangling subs too
+        if (!existingMVs.has(queryName)) {
           await this.dropSubscription(existingSubName)
           actions.push({ type: 'delete', resource: 'subscription', name: existingSubName, detail: 'orphaned subscription' })
         }
       }
     }
 
-    // 7. Remove streams (tables) that are no longer in the config
+    // 7. Remove events (tables) that are no longer in the config
     for (const existingTableName of existingTables) {
-      if (!desiredStreamNames.has(existingTableName)) {
+      if (!desiredEventNames.has(existingTableName)) {
         // Only drop if no MV depends on it
-        const hasDependents = await this.tableHasDependentViews(existingTableName)
+        const hasDependents = await this.tableHasDependentMVs(existingTableName)
         if (hasDependents) {
           console.log(`[ddl-manager] Skipping drop of table "${existingTableName}" - materialized views depend on it`)
           actions.push({
             type: 'unchanged',
-            resource: 'stream',
+            resource: 'event',
             name: existingTableName,
-            detail: 'kept because dependent views exist',
+            detail: 'kept because dependent materialized views exist',
           })
         } else {
           await this.dropTable(existingTableName)
-          actions.push({ type: 'delete', resource: 'stream', name: existingTableName, detail: 'removed from config' })
+          actions.push({ type: 'delete', resource: 'event', name: existingTableName, detail: 'removed from config' })
         }
       }
     }
@@ -196,7 +213,7 @@ export class DdlManager {
     return new Set(result.rows.map((r: any) => r.table_name))
   }
 
-  private async getExistingViews(): Promise<Map<string, string>> {
+  private async getExistingMaterializedViews(): Promise<Map<string, string>> {
     const result = await this.client!.query(
       `SELECT name, definition FROM rw_catalog.rw_materialized_views WHERE schema_id = (SELECT id FROM rw_catalog.rw_schemas WHERE name = 'public')`
     )
@@ -207,6 +224,18 @@ export class DdlManager {
     return views
   }
 
+  private async getExistingSources(): Promise<Set<string>> {
+    try {
+      const result = await this.client!.query(
+        `SELECT name FROM rw_catalog.rw_tables WHERE schema_id = (SELECT id FROM rw_catalog.rw_schemas WHERE name = 'public') AND is_index = false`
+      )
+      return new Set(result.rows.map((r: any) => r.name))
+    } catch {
+      // Fallback: if catalog query fails, return empty set
+      return new Set()
+    }
+  }
+
   private async getExistingSubscriptions(): Promise<Set<string>> {
     const result = await this.client!.query(
       `SELECT name FROM rw_catalog.rw_subscriptions WHERE schema_id = (SELECT id FROM rw_catalog.rw_schemas WHERE name = 'public')`
@@ -214,7 +243,7 @@ export class DdlManager {
     return new Set(result.rows.map((r: any) => r.name))
   }
 
-  private async tableHasDependentViews(tableName: string): Promise<boolean> {
+  private async tableHasDependentMVs(tableName: string): Promise<boolean> {
     const result = await this.client!.query(
       `SELECT name FROM rw_catalog.rw_materialized_views WHERE schema_id = (SELECT id FROM rw_catalog.rw_schemas WHERE name = 'public') AND definition ILIKE $1`,
       [`%${tableName}%`]
@@ -224,8 +253,8 @@ export class DdlManager {
 
   // ── DDL operations ────────────────────────────────────────────────────
 
-  private async createTable(name: string, streamDef: StreamDef): Promise<void> {
-    const sql = buildCreateTableSql(name, streamDef)
+  private async createTable(name: string, eventDef: EventDef): Promise<void> {
+    const sql = buildCreateTableSql(name, eventDef)
     try {
       await this.client!.query(sql)
       console.log(`[ddl-manager] Created table: ${name}`)
@@ -304,4 +333,76 @@ export class DdlManager {
       }
     }
   }
+
+  private async createCdcSource(
+    sourceName: string,
+    tableName: string,
+    source: PostgresCdcSource
+  ): Promise<void> {
+    const cdcTableName = `${sourceName}_${tableName}`
+    const slotName = source.slotName ?? `wavelet_${sourceName}`
+    const pubName = source.publicationName ?? `wavelet_${sourceName}_pub`
+
+    // RisingWave CDC source syntax:
+    // CREATE TABLE table_name ( ... ) WITH (
+    //   connector = 'postgres-cdc',
+    //   hostname = '...',
+    //   port = '...',
+    //   username = '...',
+    //   password = '...',
+    //   database.name = '...',
+    //   table.name = '...',
+    //   slot.name = '...',
+    //   publication.name = '...'
+    // )
+    // We parse the connection string to extract components.
+
+    const parsed = parsePostgresUrl(source.connection)
+
+    const esc = (s: string) => s.replace(/'/g, "''")
+    try {
+      await this.client!.query(`
+        CREATE TABLE IF NOT EXISTS ${cdcTableName} (*)
+        WITH (
+          connector = 'postgres-cdc',
+          hostname = '${esc(parsed.host)}',
+          port = '${esc(parsed.port)}',
+          username = '${esc(parsed.user)}',
+          password = '${esc(parsed.password)}',
+          database.name = '${esc(parsed.database)}',
+          schema.name = '${esc(parsed.schema)}',
+          table.name = '${esc(tableName)}',
+          slot.name = '${esc(slotName)}',
+          publication.name = '${esc(pubName)}'
+        )
+      `)
+      console.log(`[ddl-manager] Created CDC source: ${cdcTableName} (from ${parsed.host}/${parsed.database}.${tableName})`)
+    } catch (err: any) {
+      if (err.message?.includes('already exists')) {
+        console.log(`[ddl-manager] CDC source already exists: ${cdcTableName}`)
+      } else {
+        throw err
+      }
+    }
+  }
+}
+
+function parsePostgresUrl(url: string): {
+  host: string
+  port: string
+  user: string
+  password: string
+  database: string
+  schema: string
+} {
+  // Parse postgresql://user:password@host:port/database?schema=xxx
+  const u = new URL(url)
+  return {
+    host: u.hostname,
+    port: u.port || '5432',
+    user: decodeURIComponent(u.username),
+    password: decodeURIComponent(u.password),
+    database: u.pathname.replace(/^\//, '') || 'postgres',
+    schema: u.searchParams.get('schema') ?? 'public',
+  }
 }

package/src/http-api.ts

@@ -1,16 +1,20 @@
 import type { IncomingMessage, ServerResponse } from 'node:http'
 import pg from 'pg'
-import type { StreamDef, ViewDef, SqlFragment } from '@risingwave/wavelet'
+import type { EventDef, QueryDef, SqlFragment } from '@risingwave/wavelet'
+import type { JwtVerifier, JwtClaims } from './jwt.js'
 
-const { Client } = pg
+const { Pool } = pg
+
+const MAX_BODY_SIZE = 10 * 1024 * 1024 // 10MB
 
 export class HttpApi {
-  private client: InstanceType<typeof Client> | null = null
+  private pool: InstanceType<typeof Pool> | null = null
 
   constructor(
     private connectionString: string,
-    private streams: Record<string, StreamDef>,
-    private views: Record<string, ViewDef | SqlFragment>
+    private events: Record<string, EventDef>,
+    private queries: Record<string, QueryDef | SqlFragment>,
+    private jwt?: JwtVerifier
   ) {}
 
   async handle(req: IncomingMessage, res: ServerResponse): Promise<void> {
@@ -28,24 +32,24 @@ export class HttpApi {
     const url = new URL(req.url ?? '/', `http://${req.headers.host}`)
 
     try {
-      // POST /v1/streams/{name}
-      const streamMatch = url.pathname.match(/^\/v1\/streams\/([^/]+)$/)
-      if (streamMatch && req.method === 'POST') {
-        await this.handleWrite(streamMatch[1], req, res)
+      // POST /v1/events/{name}
+      const eventMatch = url.pathname.match(/^\/v1\/events\/([^/]+)$/)
+      if (eventMatch && req.method === 'POST') {
+        await this.handleWrite(eventMatch[1], req, res)
         return
       }
 
-      // POST /v1/streams/{name}/batch
-      const batchMatch = url.pathname.match(/^\/v1\/streams\/([^/]+)\/batch$/)
+      // POST /v1/events/{name}/batch
+      const batchMatch = url.pathname.match(/^\/v1\/events\/([^/]+)\/batch$/)
       if (batchMatch && req.method === 'POST') {
         await this.handleBatchWrite(batchMatch[1], req, res)
         return
       }
 
-      // GET /v1/views/{name}
-      const viewMatch = url.pathname.match(/^\/v1\/views\/([^/]+)$/)
-      if (viewMatch && req.method === 'GET') {
-        await this.handleRead(viewMatch[1], url, res)
+      // GET /v1/queries/{name}
+      const queryMatch = url.pathname.match(/^\/v1\/queries\/([^/]+)$/)
+      if (queryMatch && req.method === 'GET') {
+        await this.handleRead(queryMatch[1], url, req, res)
         return
       }
 
@@ -55,15 +59,15 @@ export class HttpApi {
         return
       }
 
-      // GET /v1/views - list available views
-      if (url.pathname === '/v1/views' && req.method === 'GET') {
-        this.json(res, 200, { views: Object.keys(this.views) })
+      // GET /v1/queries - list available queries
+      if (url.pathname === '/v1/queries' && req.method === 'GET') {
+        this.json(res, 200, { queries: Object.keys(this.queries) })
         return
       }
 
-      // GET /v1/streams - list available streams
-      if (url.pathname === '/v1/streams' && req.method === 'GET') {
-        this.json(res, 200, { streams: Object.keys(this.streams) })
+      // GET /v1/events - list available events
+      if (url.pathname === '/v1/events' && req.method === 'GET') {
+        this.json(res, 200, { events: Object.keys(this.events) })
         return
       }
 
@@ -72,11 +76,11 @@ export class HttpApi {
         message: `${req.method} ${url.pathname} does not match any route.`,
         routes: [
           'GET  /v1/health',
-          'GET  /v1/views',
-          'GET  /v1/views/{name}',
-          'GET  /v1/streams',
-          'POST /v1/streams/{name}',
-          'POST /v1/streams/{name}/batch',
+          'GET  /v1/queries',
+          'GET  /v1/queries/{name}',
+          'GET  /v1/events',
+          'POST /v1/events/{name}',
+          'POST /v1/events/{name}/batch',
         ],
       })
     } catch (err: any) {
@@ -85,21 +89,20 @@ export class HttpApi {
     }
   }
 
-  private async ensureClient(): Promise<InstanceType<typeof Client>> {
-    if (!this.client) {
-      this.client = new Client({ connectionString: this.connectionString })
-      await this.client.connect()
+  private ensurePool(): InstanceType<typeof Pool> {
+    if (!this.pool) {
+      this.pool = new Pool({ connectionString: this.connectionString, max: 10 })
     }
-    return this.client
+    return this.pool
   }
 
-  private async handleWrite(streamName: string, req: IncomingMessage, res: ServerResponse): Promise<void> {
-    const stream = this.streams[streamName]
-    if (!stream) {
-      const available = Object.keys(this.streams)
+  private async handleWrite(eventName: string, req: IncomingMessage, res: ServerResponse): Promise<void> {
+    const eventDef = this.events[eventName]
+    if (!eventDef) {
+      const available = Object.keys(this.events)
       this.json(res, 404, {
-        error: `Stream '${streamName}' not found.`,
-        available_streams: available,
+        error: `Event '${eventName}' not found.`,
+        available_events: available,
       })
       return
     }
@@ -107,80 +110,147 @@ export class HttpApi {
     const body = await this.readBody(req)
     const data = JSON.parse(body)
 
-    const client = await this.ensureClient()
-    const columns = Object.keys(stream.columns)
+    const pool = this.ensurePool()
+    const columns = Object.keys(eventDef.columns)
     const values = columns.map((col) => data[col])
     const placeholders = columns.map((_, i) => `$${i + 1}`)
 
-    await client.query(
-      `INSERT INTO ${streamName} (${columns.join(', ')}) VALUES (${placeholders.join(', ')})`,
+    await pool.query(
+      `INSERT INTO ${eventName} (${columns.join(', ')}) VALUES (${placeholders.join(', ')})`,
       values
     )
 
     this.json(res, 200, { ok: true })
   }
 
-  private async handleBatchWrite(streamName: string, req: IncomingMessage, res: ServerResponse): Promise<void> {
-    const stream = this.streams[streamName]
-    if (!stream) {
-      const available = Object.keys(this.streams)
+  private async handleBatchWrite(eventName: string, req: IncomingMessage, res: ServerResponse): Promise<void> {
+    const eventDef = this.events[eventName]
+    if (!eventDef) {
+      const available = Object.keys(this.events)
       this.json(res, 404, {
-        error: `Stream '${streamName}' not found.`,
-        available_streams: available,
+        error: `Event '${eventName}' not found.`,
+        available_events: available,
       })
       return
     }
 
     const body = await this.readBody(req)
-    const events: any[] = JSON.parse(body)
+    const items: any[] = JSON.parse(body)
 
-    if (!Array.isArray(events)) {
+    if (!Array.isArray(items)) {
       this.json(res, 400, { error: 'Batch endpoint expects a JSON array.' })
       return
     }
 
-    const client = await this.ensureClient()
-    const columns = Object.keys(stream.columns)
+    if (items.length === 0) {
+      this.json(res, 200, { ok: true, count: 0 })
+      return
+    }
+
+    const pool = this.ensurePool()
+    const columns = Object.keys(eventDef.columns)
 
-    for (const data of events) {
-      const values = columns.map((col) => data[col])
-      const placeholders = columns.map((_, i) => `$${i + 1}`)
-      await client.query(
-        `INSERT INTO ${streamName} (${columns.join(', ')}) VALUES (${placeholders.join(', ')})`,
-        values
-      )
+    // Build a single INSERT with multiple VALUE rows
+    const allValues: unknown[] = []
+    const rowPlaceholders: string[] = []
+
+    for (let i = 0; i < items.length; i++) {
+      const row = items[i]
+      const offset = i * columns.length
+      const ph = columns.map((_, j) => `$${offset + j + 1}`)
+      rowPlaceholders.push(`(${ph.join(', ')})`)
+      for (const col of columns) {
+        allValues.push(row[col])
+      }
     }
 
-    this.json(res, 200, { ok: true, count: events.length })
+    await pool.query(
+      `INSERT INTO ${eventName} (${columns.join(', ')}) VALUES ${rowPlaceholders.join(', ')}`,
+      allValues
+    )
+
+    this.json(res, 200, { ok: true, count: items.length })
   }
 
-  private async handleRead(viewName: string, url: URL, res: ServerResponse): Promise<void> {
-    if (!this.views[viewName]) {
-      const available = Object.keys(this.views)
+  private async handleRead(queryName: string, url: URL, req: IncomingMessage, res: ServerResponse): Promise<void> {
+    if (!this.queries[queryName]) {
+      const available = Object.keys(this.queries)
       this.json(res, 404, {
-        error: `View '${viewName}' not found.`,
-        available_views: available,
+        error: `Query '${queryName}' not found.`,
+        available_queries: available,
       })
       return
     }
 
-    const client = await this.ensureClient()
+    // JWT verification for queries with filterBy
+    const queryDef = this.queries[queryName]
+    const filterBy = this.getFilterBy(queryDef)
+
+    let claims: JwtClaims | null = null
+    if (filterBy && this.jwt?.isConfigured()) {
+      const token = url.searchParams.get('token')
+        ?? req.headers.authorization?.replace('Bearer ', '')
+
+      if (!token) {
+        this.json(res, 401, { error: 'Authentication required for filtered queries.' })
+        return
+      }
+
+      claims = await this.jwt.verify(token)
+    }
+
+    const pool = this.ensurePool()
 
-    // Build WHERE clause from query params
+    // Build WHERE clause: start with filterBy if applicable
     const params: string[] = []
     const values: unknown[] = []
+
+    if (filterBy && claims) {
+      const claimValue = claims[filterBy]
+      if (claimValue === undefined) {
+        // No matching claim -- return empty result, not all data
+        this.json(res, 200, { query: queryName, rows: [] })
+        return
+      }
+      values.push(String(claimValue))
+      params.push(`${filterBy} = $${values.length}`)
+    }
+
+    // Add query params as additional filters, validating column names
+    const knownColumns = this.getQueryColumns(queryDef)
     for (const [key, value] of url.searchParams.entries()) {
-      params.push(`${key} = $${params.length + 1}`)
+      if (key === 'token') continue // skip JWT token param
+      if (knownColumns && !knownColumns.includes(key)) {
+        this.json(res, 400, { error: `Unknown column '${key}'. Known columns: ${knownColumns.join(', ')}` })
+        return
+      }
+      if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(key)) {
+        this.json(res, 400, { error: `Invalid column name: '${key}'` })
+        return
+      }
       values.push(value)
+      params.push(`${key} = $${values.length}`)
     }
 
-    let sql = `SELECT * FROM ${viewName}`
+    let sql = `SELECT * FROM ${queryName}`
     if (params.length > 0) {
       sql += ` WHERE ${params.join(' AND ')}`
     }
 
-    const result = await client.query(sql, values)
-    this.json(res, 200, { view: viewName, rows: result.rows })
+    const result = await pool.query(sql, values)
+    this.json(res, 200, { query: queryName, rows: result.rows })
+  }
+
+  private getFilterBy(queryDef: QueryDef | SqlFragment): string | undefined {
+    if ('_tag' in queryDef && queryDef._tag === 'sql') return undefined
+    return (queryDef as QueryDef).filterBy
+  }
+
+  private getQueryColumns(queryDef: QueryDef | SqlFragment): string[] | null {
+    if ('_tag' in queryDef && queryDef._tag === 'sql') return null
+    const qd = queryDef as QueryDef
+    if (qd.columns) return Object.keys(qd.columns)
+    return null
   }
 
   private json(res: ServerResponse, status: number, data: unknown): void {
@@ -191,7 +261,16 @@ export class HttpApi {
   private readBody(req: IncomingMessage): Promise<string> {
     return new Promise((resolve, reject) => {
       let body = ''
-      req.on('data', (chunk) => { body += chunk })
+      let size = 0
+      req.on('data', (chunk) => {
+        size += chunk.length
+        if (size > MAX_BODY_SIZE) {
+          req.destroy()
+          reject(new Error(`Request body exceeds ${MAX_BODY_SIZE / 1024 / 1024}MB limit`))
+          return
+        }
+        body += chunk
+      })
       req.on('end', () => resolve(body))
       req.on('error', reject)
     })

package/src/server.ts

@@ -2,6 +2,7 @@ import { createServer, type IncomingMessage, type ServerResponse, type Server }
 import type { WaveletConfig } from '@risingwave/wavelet'
 import { CursorManager } from './cursor-manager.js'
 import { WebSocketFanout } from './ws-fanout.js'
+import { WebhookFanout } from './webhook.js'
 import { HttpApi } from './http-api.js'
 import { JwtVerifier } from './jwt.js'
 
@@ -9,14 +10,18 @@ export class WaveletServer {
   private httpServer: ReturnType<typeof createServer> | null = null
   private cursorManager: CursorManager
   private fanout: WebSocketFanout
+  private webhooks: WebhookFanout
   private httpApi: HttpApi
   private jwt: JwtVerifier
 
   constructor(private config: WaveletConfig) {
     this.jwt = new JwtVerifier(config.jwt)
-    this.cursorManager = new CursorManager(config.database, config.views ?? {})
-    this.fanout = new WebSocketFanout(this.cursorManager, this.jwt, config.views ?? {})
-    this.httpApi = new HttpApi(config.database, config.streams ?? {}, config.views ?? {})
+    const queries = config.queries ?? config.views ?? {}
+    const events = config.events ?? config.streams ?? {}
+    this.cursorManager = new CursorManager(config.database, queries)
+    this.fanout = new WebSocketFanout(this.cursorManager, this.jwt, queries)
+    this.webhooks = new WebhookFanout(queries, config.jwt?.secret)
+    this.httpApi = new HttpApi(config.database, events, queries, this.jwt)
   }
 
   async start(): Promise<void> {
@@ -27,14 +32,15 @@ export class WaveletServer {
     this.fanout.attach(this.httpServer)
 
     await this.cursorManager.initialize()
-    this.cursorManager.startPolling((viewName, diffs) => {
-      this.fanout.broadcast(viewName, diffs)
+    this.cursorManager.startPolling((queryName, diffs) => {
+      this.fanout.broadcast(queryName, diffs)
+      this.webhooks.broadcast(queryName, diffs)
     })
 
     await new Promise<void>((resolve) => {
       this.httpServer!.listen(port, host, () => {
         console.log(`Wavelet server listening on ${host}:${port}`)
-        console.log(`WebSocket: ws://${host}:${port}/subscribe/{view}`)
+        console.log(`WebSocket: ws://${host}:${port}/subscribe/{query}`)
         console.log(`HTTP API:  http://${host}:${port}/v1/`)
         resolve()
       })
@@ -53,8 +59,9 @@ export class WaveletServer {
     this.fanout.attach(server, prefix)
 
     await this.cursorManager.initialize()
-    this.cursorManager.startPolling((viewName, diffs) => {
-      this.fanout.broadcast(viewName, diffs)
+    this.cursorManager.startPolling((queryName, diffs) => {
+      this.fanout.broadcast(queryName, diffs)
+      this.webhooks.broadcast(queryName, diffs)
     })
 
     const handleHttp = (req: IncomingMessage, res: ServerResponse) => {

package/src/webhook.ts

@@ -0,0 +1,67 @@
+import { createHmac } from 'node:crypto'
+import type { QueryDef, SqlFragment } from '@risingwave/wavelet'
+import type { ViewDiff } from './cursor-manager.js'
+
+const TIMEOUT_MS = 10000
+
+export class WebhookFanout {
+  private webhooks: Map<string, string> = new Map() // queryName -> url
+
+  constructor(
+    queries: Record<string, QueryDef | SqlFragment>,
+    private signingSecret?: string
+  ) {
+    for (const [name, def] of Object.entries(queries)) {
+      if ('_tag' in def && def._tag === 'sql') continue
+      const qd = def as QueryDef
+      if (qd.webhook) {
+        this.webhooks.set(name, qd.webhook)
+      }
+    }
+  }
+
+  async broadcast(queryName: string, diff: ViewDiff): Promise<void> {
+    const url = this.webhooks.get(queryName)
+    if (!url) return
+
+    const body = JSON.stringify({
+      query: queryName,
+      cursor: diff.cursor,
+      inserted: diff.inserted,
+      updated: diff.updated,
+      deleted: diff.deleted,
+    })
+
+    const headers: Record<string, string> = {
+      'Content-Type': 'application/json',
+      'User-Agent': 'Wavelet-Webhook/1.0',
+    }
+
+    if (this.signingSecret) {
+      const signature = createHmac('sha256', this.signingSecret)
+        .update(body)
+        .digest('hex')
+      headers['X-Wavelet-Signature'] = `sha256=${signature}`
+    }
+
+    try {
+      const controller = new AbortController()
+      const timeout = setTimeout(() => controller.abort(), TIMEOUT_MS)
+
+      await fetch(url, {
+        method: 'POST',
+        headers,
+        body,
+        signal: controller.signal,
+      })
+
+      clearTimeout(timeout)
+    } catch (err: any) {
+      if (err.name === 'AbortError') {
+        console.error(`[webhook] Timeout sending to ${url} for query ${queryName}`)
+      } else {
+        console.error(`[webhook] Failed to send to ${url} for query ${queryName}:`, err.message)
+      }
+    }
+  }
+}

package/src/ws-fanout.ts

@@ -1,23 +1,23 @@
 import { WebSocketServer, WebSocket } from 'ws'
 import type { IncomingMessage, Server } from 'node:http'
-import type { ViewDef, SqlFragment } from '@risingwave/wavelet'
+import type { QueryDef, SqlFragment } from '@risingwave/wavelet'
 import type { CursorManager, ViewDiff } from './cursor-manager.js'
 import type { JwtVerifier, JwtClaims } from './jwt.js'
 
 interface Subscriber {
   ws: WebSocket
-  viewName: string
+  queryName: string
   claims: JwtClaims | null
 }
 
 export class WebSocketFanout {
   private wss: WebSocketServer | null = null
-  private subscribers: Map<string, Set<Subscriber>> = new Map() // viewName -> subscribers
+  private subscribers: Map<string, Set<Subscriber>> = new Map() // queryName -> subscribers
 
   constructor(
     private cursorManager: CursorManager,
     private jwt: JwtVerifier,
-    private views: Record<string, ViewDef | SqlFragment>
+    private queries: Record<string, QueryDef | SqlFragment>
   ) {}
 
   attach(server: Server, pathPrefix?: string): void {
@@ -54,17 +54,17 @@ export class WebSocketFanout {
 
     if (!match) {
       throw new Error(
-        `Invalid path: ${url.pathname}. Use /subscribe/{viewName}. ` +
-        `Available views: ${Object.keys(this.views).join(', ')}`
+        `Invalid path: ${url.pathname}. Use /subscribe/{queryName}. ` +
+        `Available queries: ${Object.keys(this.queries).join(', ')}`
       )
     }
 
-    const viewName = match[1]
+    const queryName = match[1]
 
-    if (!this.views[viewName]) {
-      const available = Object.keys(this.views)
+    if (!this.queries[queryName]) {
+      const available = Object.keys(this.queries)
       throw new Error(
-        `View '${viewName}' not found. Available views: ${available.join(', ')}`
+        `Query '${queryName}' not found. Available queries: ${available.join(', ')}`
       )
     }
 
@@ -80,26 +80,35 @@ export class WebSocketFanout {
       claims = await this.jwt.verify(token)
     }
 
-    const subscriber: Subscriber = { ws, viewName, claims }
+    const subscriber: Subscriber = { ws, queryName, claims }
 
-    if (!this.subscribers.has(viewName)) {
-      this.subscribers.set(viewName, new Set())
+    if (!this.subscribers.has(queryName)) {
+      this.subscribers.set(queryName, new Set())
     }
-    this.subscribers.get(viewName)!.add(subscriber)
+    this.subscribers.get(queryName)!.add(subscriber)
 
     ws.on('close', () => {
-      this.subscribers.get(viewName)?.delete(subscriber)
+      this.subscribers.get(queryName)?.delete(subscriber)
     })
 
-    ws.send(JSON.stringify({ type: 'connected', view: viewName }))
+    // Heartbeat: detect dead connections behind proxies/load balancers
+    const pingInterval = setInterval(() => {
+      if (ws.readyState === WebSocket.OPEN) {
+        ws.ping()
+      }
+    }, 30000)
+    ws.on('close', () => clearInterval(pingInterval))
+    ws.on('pong', () => { /* connection alive */ })
+
+    ws.send(JSON.stringify({ type: 'connected', query: queryName }))
   }
 
-  broadcast(viewName: string, diff: ViewDiff): void {
-    const subs = this.subscribers.get(viewName)
+  broadcast(queryName: string, diff: ViewDiff): void {
+    const subs = this.subscribers.get(queryName)
     if (!subs || subs.size === 0) return
 
-    const viewDef = this.views[viewName]
-    const filterBy = this.getFilterBy(viewDef)
+    const queryDef = this.queries[queryName]
+    const filterBy = this.getFilterBy(queryDef)
 
     for (const sub of subs) {
       if (sub.ws.readyState !== WebSocket.OPEN) continue
@@ -119,7 +128,7 @@ export class WebSocketFanout {
 
       sub.ws.send(JSON.stringify({
         type: 'diff',
-        view: viewName,
+        query: queryName,
         cursor: filteredDiff.cursor,
         inserted: filteredDiff.inserted,
         updated: filteredDiff.updated,
@@ -130,7 +139,10 @@ export class WebSocketFanout {
 
   private filterDiff(diff: ViewDiff, filterBy: string, claims: JwtClaims): ViewDiff {
     const claimValue = claims[filterBy]
-    if (claimValue === undefined) return diff
+    if (claimValue === undefined) {
+      // No matching claim -- return empty diff, not all data
+      return { cursor: diff.cursor, inserted: [], updated: [], deleted: [] }
+    }
 
     const filterFn = (row: Record<string, unknown>) =>
       String(row[filterBy]) === String(claimValue)
@@ -143,9 +155,9 @@ export class WebSocketFanout {
     }
   }
 
-  private getFilterBy(viewDef: ViewDef | SqlFragment): string | undefined {
-    if ('_tag' in viewDef && viewDef._tag === 'sql') return undefined
-    return (viewDef as ViewDef).filterBy
+  private getFilterBy(queryDef: QueryDef | SqlFragment): string | undefined {
+    if ('_tag' in queryDef && queryDef._tag === 'sql') return undefined
+    return (queryDef as QueryDef).filterBy
   }
 
   closeAll(): void {