@rebasepro/server-postgresql 0.4.0 → 0.6.0

package/src/services/RelationService.ts

@@ -13,6 +13,29 @@ import {
 } from "./entity-helpers";
 import { parseDataFromServer } from "../data-transformer";
 import { PostgresCollectionRegistry } from "../collections/PostgresCollectionRegistry";
+import { logger } from "@rebasepro/server-core";
+
+/**
+ * Typed wrapper for Drizzle dynamic query innerJoin.
+ * Drizzle's `$dynamic()` queries lose the `innerJoin` method from
+ * their static type, but it exists at runtime. This helper bridges
+ * the gap with a single confined cast.
+ */
+function applyDynamicJoin<T>(query: T, joinTable: PgTable, condition: SQL): T {
+    return (query as unknown as { innerJoin(t: PgTable, c: SQL): T }).innerJoin(joinTable, condition) as T;
+}
+
+/**
+ * Typed wrapper for DrizzleConditionBuilder.buildRelationQuery on dynamic queries.
+ * The method returns a widened generic that doesn't reassign cleanly;
+ * this helper confines the cast.
+ */
+function applyDynamicRelationQuery<T>(
+    query: T,
+    ...args: Parameters<typeof DrizzleConditionBuilder.buildRelationQuery>
+): T {
+    return DrizzleConditionBuilder.buildRelationQuery(...args) as unknown as T;
+}
 
 /**
  * Service for handling all relation-related operations.
@@ -108,8 +131,7 @@ export class RelationService {
                     throw new Error(`Join columns not found: ${fromColumn} -> ${toColumn}`);
                 }
 
-                // @ts-expect-error Drizzle mutates base query generic on innerJoin
-                query = query.innerJoin(joinTable, eq(fromCol, toCol));
+                query = applyDynamicJoin(query, joinTable, eq(fromCol, toCol));
                 currentTable = joinTable;
             }
 
@@ -167,8 +189,8 @@ export class RelationService {
         }
 
         // Use unified relation query builder
-        // @ts-expect-error buildRelationQuery uses dynamic queries
-        query = DrizzleConditionBuilder.buildRelationQuery(
+        query = applyDynamicRelationQuery(
+            query,
             query,
             relation,
             parsedParentId,
@@ -316,8 +338,7 @@ export class RelationService {
                     throw new Error(`Join columns not found: ${fromColumn} -> ${toColumn}`);
                 }
 
-                // @ts-expect-error Drizzle mutates base query generic on innerJoin
-                query = query.innerJoin(joinTable, eq(fromCol, toCol));
+                query = applyDynamicJoin(query, joinTable, eq(fromCol, toCol));
                 currentTable = joinTable;
             }
 
@@ -419,8 +440,8 @@ export class RelationService {
         let query = this.db.select().from(targetTable).$dynamic();
 
         // Build the relation query with ALL parent IDs
-        // @ts-expect-error buildRelationQuery uses dynamic queries
-        query = DrizzleConditionBuilder.buildRelationQuery(
+        query = applyDynamicRelationQuery(
+            query,
             query,
             relation,
             parsedParentIds, // Pass array instead of single ID
@@ -513,8 +534,7 @@ export class RelationService {
                 const toCol = joinTable[toColName as keyof typeof joinTable] as AnyPgColumn;
                 if (!fromCol || !toCol) throw new Error(`Join columns not found: ${fromColumn} -> ${toColumn}`);
 
-                // @ts-expect-error Drizzle mutates base query generic on innerJoin
-                query = query.innerJoin(joinTable, eq(fromCol, toCol));
+                query = applyDynamicJoin(query, joinTable, eq(fromCol, toCol));
                 currentTable = joinTable;
             }
 
@@ -549,7 +569,7 @@ export class RelationService {
         if (relation.through && relation.cardinality === "many" && relation.direction === "owning") {
             const junctionTable = this.registry.getTable(relation.through.table);
             if (!junctionTable) {
-                console.warn(`[batchFetchRelatedEntitiesMany] Junction table '${relation.through.table}' not found`);
+                logger.warn(`[batchFetchRelatedEntitiesMany] Junction table '${relation.through.table}' not found`);
                 return new Map();
             }
 
@@ -557,7 +577,7 @@ export class RelationService {
             const targetJunctionCol = junctionTable[relation.through.targetColumn as keyof typeof junctionTable] as AnyPgColumn;
 
             if (!sourceJunctionCol || !targetJunctionCol) {
-                console.warn(`[batchFetchRelatedEntitiesMany] Junction columns not found in '${relation.through.table}'`);
+                logger.warn(`[batchFetchRelatedEntitiesMany] Junction columns not found in '${relation.through.table}'`);
                 return new Map();
             }
 
@@ -597,8 +617,8 @@ export class RelationService {
         // Handle FK-based relations (one-to-many inverse)
         let query = this.db.select().from(targetTable).$dynamic();
 
-        // @ts-expect-error buildRelationQuery uses dynamic queries
-        query = DrizzleConditionBuilder.buildRelationQuery(
+        query = applyDynamicRelationQuery(
+            query,
             query,
             relation,
             parsedParentIds,
@@ -710,7 +730,7 @@ export class RelationService {
                 }
 
                 if (!junctionTable || !sourceJunctionColumn || !targetJunctionColumn) {
-                    console.warn(`Could not determine junction table for relation '${key}' in collection '${collection.slug}'`);
+                    logger.warn(`Could not determine junction table for relation '${key}' in collection '${collection.slug}'`);
                     continue;
                 }
 
@@ -740,7 +760,7 @@ export class RelationService {
                 // Handle many-to-many relations with junction table using 'through' property
                 const junctionTable = this.registry.getTable(relation.through.table);
                 if (!junctionTable) {
-                    console.warn(`Junction table '${relation.through.table}' not found for relation '${key}' in collection '${collection.slug}'`);
+                    logger.warn(`Junction table '${relation.through.table}' not found for relation '${key}' in collection '${collection.slug}'`);
                     continue;
                 }
 
@@ -748,7 +768,7 @@ export class RelationService {
                 const targetJunctionColumn = junctionTable[relation.through.targetColumn as keyof typeof junctionTable] as AnyPgColumn;
 
                 if (!sourceJunctionColumn || !targetJunctionColumn) {
-                    console.warn(`Junction columns not found for relation '${key}'`);
+                    logger.warn(`Junction columns not found for relation '${key}'`);
                     continue;
                 }
 
@@ -777,7 +797,7 @@ export class RelationService {
             } else if (relation.through && relation.cardinality === "many" && relation.direction === "inverse") {
                 // Inverse M2M relations should be saved from the owning side.
                 // The owning collection manages the junction table rows.
-                console.warn(`[updateRelationsUsingJoins] Inverse M2M relation '${key}' in collection '${collection.slug}' should be saved from the owning side. Skipping.`);
+                logger.warn(`[updateRelationsUsingJoins] Inverse M2M relation '${key}' in collection '${collection.slug}' should be saved from the owning side. Skipping.`);
             } else if (relation.cardinality === "many" && relation.direction === "inverse" && relation.foreignKeyOnTarget) {
                 // Handle one-to-many (inverse) by updating target FK to point to parent
                 const targetTable = getTableForCollection(targetCollection, this.registry);
@@ -787,7 +807,7 @@ export class RelationService {
                 const fkCol = targetTable[relation.foreignKeyOnTarget as keyof typeof targetTable] as AnyPgColumn;
 
                 if (!fkCol || !targetIdCol) {
-                    console.warn(`Invalid inverse-many config for relation '${key}' in collection '${collection.slug}'`);
+                    logger.warn(`Invalid inverse-many config for relation '${key}' in collection '${collection.slug}'`);
                     continue;
                 }
 
@@ -817,7 +837,7 @@ export class RelationService {
                         .where(eq(fkCol, parsedParentId));
                 }
             } else {
-                console.warn(`Many relation '${key}' in collection '${collection.slug}' lacks write configuration and will be skipped during save.`);
+                logger.warn(`Many relation '${key}' in collection '${collection.slug}' lacks write configuration and will be skipped during save.`);
             }
         }
     }
@@ -895,13 +915,13 @@ export class RelationService {
 
                 // Handle simple inverse relations
                 if (!relation.foreignKeyOnTarget) {
-                    console.warn(`Inverse relation '${relation.relationName}' is missing foreignKeyOnTarget property. Skipping.`);
+                    logger.warn(`Inverse relation '${relation.relationName}' is missing foreignKeyOnTarget property. Skipping.`);
                     continue;
                 }
 
                 const foreignKeyColumn = targetTable[relation.foreignKeyOnTarget! as keyof typeof targetTable] as AnyPgColumn;
                 if (!foreignKeyColumn) {
-                    console.warn(`Foreign key column '${relation.foreignKeyOnTarget}' not found in target table for relation '${relation.relationName}'`);
+                    logger.warn(`Foreign key column '${relation.foreignKeyOnTarget}' not found in target table for relation '${relation.relationName}'`);
                     continue;
                 }
 
@@ -931,7 +951,7 @@ export class RelationService {
                         .where(eq(targetIdField, parsedNewTargetId));
                 }
             } catch (e) {
-                console.warn(`Failed to update inverse relation '${relation.relationName}':`, e);
+                logger.warn(`Failed to update inverse relation '${relation.relationName}'`, { error: e });
             }
         }
     }
@@ -949,7 +969,7 @@ export class RelationService {
     ) {
         try {
             if (!relation.joinPath || relation.joinPath.length === 0) {
-                console.warn(`Inverse relation '${relation.relationName}' missing joinPath`);
+                logger.warn(`Inverse relation '${relation.relationName}' missing joinPath`);
                 return;
             }
 
@@ -967,7 +987,7 @@ export class RelationService {
                 const junctionTable = this.registry.getTable(junctionTableName);
 
                 if (!junctionTable) {
-                    console.warn(`Junction table '${junctionTableName}' not found for inverse joinPath relation '${relation.relationName}'`);
+                    logger.warn(`Junction table '${junctionTableName}' not found for inverse joinPath relation '${relation.relationName}'`);
                     return;
                 }
 
@@ -996,7 +1016,7 @@ export class RelationService {
                 }
 
                 if (!sourceJunctionColumn || !targetJunctionColumn) {
-                    console.warn(`Could not determine junction columns for inverse joinPath relation '${relation.relationName}'`);
+                    logger.warn(`Could not determine junction columns for inverse joinPath relation '${relation.relationName}'`);
                     return;
                 }
 
@@ -1041,7 +1061,7 @@ export class RelationService {
                 }
             }
         } catch (error) {
-            console.error(`Failed to update inverse joinPath relation '${relation.relationName}':`, error);
+            logger.error(`Failed to update inverse joinPath relation '${relation.relationName}'`, { error: error });
             throw error;
         }
     }
@@ -1061,7 +1081,7 @@ export class RelationService {
         try {
             const junctionTable = this.registry.getTable(junctionInfo.table);
             if (!junctionTable) {
-                console.warn(`Junction table '${junctionInfo.table}' not found for many-to-many inverse relation '${relation.relationName}'`);
+                logger.warn(`Junction table '${junctionInfo.table}' not found for many-to-many inverse relation '${relation.relationName}'`);
                 return;
             }
 
@@ -1069,7 +1089,7 @@ export class RelationService {
             const targetJunctionColumn = junctionTable[junctionInfo.targetColumn as keyof typeof junctionTable] as AnyPgColumn;
 
             if (!sourceJunctionColumn || !targetJunctionColumn) {
-                console.warn(`Junction columns not found for relation '${relation.relationName}'`);
+                logger.warn(`Junction columns not found for relation '${relation.relationName}'`);
                 return;
             }
 
@@ -1098,7 +1118,7 @@ export class RelationService {
                 }
             }
         } catch (error) {
-            console.error(`Failed to update many-to-many inverse relation '${relation.relationName}':`, error);
+            logger.error(`Failed to update many-to-many inverse relation '${relation.relationName}'`, { error: error });
             throw error;
         }
     }
@@ -1137,11 +1157,11 @@ export class RelationService {
             const targetFKCol = targetTable[targetFKColName as keyof typeof targetTable] as AnyPgColumn;
 
             if (!parentSourceCol) {
-                console.warn(`Parent source column '${parentSourceColName}' not found for joinPath relation '${relation.relationName}'`);
+                logger.warn(`Parent source column '${parentSourceColName}' not found for joinPath relation '${relation.relationName}'`);
                 continue;
             }
             if (!targetFKCol) {
-                console.warn(`Target FK column '${targetFKColName}' not found for joinPath relation '${relation.relationName}'`);
+                logger.warn(`Target FK column '${targetFKColName}' not found for joinPath relation '${relation.relationName}'`);
                 continue;
             }
 
@@ -1174,7 +1194,7 @@ export class RelationService {
                     .set({ [targetFKColName]: null })
                     .where(eq(targetFKCol, String(parentFKValue)));
             } else {
-                console.warn(`Cannot set joinPath relation '${relation.relationName}' because parent FK value is null/undefined`);
+                logger.warn(`Cannot set joinPath relation '${relation.relationName}' because parent FK value is null/undefined`);
                 continue;
             }
 
@@ -1239,7 +1259,7 @@ parentSourceColName };
         try {
             const junctionTable = this.registry.getTable(relation.through!.table);
             if (!junctionTable) {
-                console.warn(`Junction table '${relation.through!.table}' not found for relation '${relationKey}'`);
+                logger.warn(`Junction table '${relation.through!.table}' not found for relation '${relationKey}'`);
                 return;
             }
 
@@ -1247,7 +1267,7 @@ parentSourceColName };
             const targetJunctionColumn = junctionTable[relation.through!.targetColumn as keyof typeof junctionTable] as AnyPgColumn;
 
             if (!sourceJunctionColumn || !targetJunctionColumn) {
-                console.warn(`Junction columns not found for relation '${relationKey}'`);
+                logger.warn(`Junction columns not found for relation '${relationKey}'`);
                 return;
             }
 
@@ -1265,9 +1285,9 @@ parentSourceColName };
 
             await tx.insert(junctionTable).values(junctionData);
 
-            console.log(`Created junction table entry for many-to-many relation '${relationKey}': ${JSON.stringify(junctionData)}`);
+            logger.info(`Created junction table entry for many-to-many relation '${relationKey}': ${JSON.stringify(junctionData)}`);
         } catch (error) {
-            console.error(`Failed to create junction table entry for relation '${relationKey}':`, error);
+            logger.error(`Failed to create junction table entry for relation '${relationKey}'`, { error: error });
             throw error;
         }
     }

package/src/services/entity-helpers.ts

@@ -75,7 +75,9 @@ export function getPrimaryKeys(collection: EntityCollection, registry: PostgresC
             const meta = getColumnMeta(col);
             const type = col.dataType === "number" || meta.columnType === "PgSerial" || meta.columnType === "PgInteger" ? "number" : "string";
             const isUUID = meta.columnType === "PgUUID";
-            keys.push({ fieldName: key, type, isUUID });
+            keys.push({ fieldName: key,
+type,
+isUUID });
         }
     }
 
@@ -86,7 +88,9 @@ export function getPrimaryKeys(collection: EntityCollection, registry: PostgresC
         const idMeta = getColumnMeta(idCol);
         const type = idCol.dataType === "number" || idMeta.columnType === "PgSerial" || idMeta.columnType === "PgInteger" ? "number" : "string";
         const isUUID = idMeta.columnType === "PgUUID";
-        keys.push({ fieldName: "id", type, isUUID });
+        keys.push({ fieldName: "id",
+type,
+isUUID });
     }
 
     return keys;

package/src/services/realtimeService.ts

@@ -10,6 +10,8 @@ import { sql as drizzleSql } from "drizzle-orm";
 import { RealtimeProvider, CollectionSubscriptionConfig, EntitySubscriptionConfig } from "../interfaces";
 import { PostgresCollectionRegistry } from "../collections/PostgresCollectionRegistry";
 import { buildPropertyCallbacks } from "@rebasepro/common";
+import { logger } from "@rebasepro/server-core";
+import { sanitizeErrorForClient } from "../utils/pg-error-utils";
 
 /** Channel name used for Postgres LISTEN/NOTIFY cross-instance realtime. */
 const PG_NOTIFY_CHANNEL = "rebase_entity_changes";
@@ -218,7 +220,7 @@ export class RealtimeService extends EventEmitter implements RealtimeProvider {
         });
 
         ws.on("error", (error) => {
-            console.error("WebSocket error for client", clientId, error);
+            logger.error("WebSocket error for client", { detail: clientId, error });
             this.removeClient(clientId);
         });
     }
@@ -321,7 +323,7 @@ export class RealtimeService extends EventEmitter implements RealtimeProvider {
             if (!collection) {
                 const registered = this.registry.getCollections().map(c => c.slug).join(", ");
                 const msg = `Collection not found: '${request.path}'. Registered: [${registered}]`;
-                console.error(`[RealtimeService] ${msg}`);
+                logger.error(`[RealtimeService] ${msg}`);
                 this.sendError(clientId, msg, subscriptionId);
                 return;
             }
@@ -360,7 +362,8 @@ export class RealtimeService extends EventEmitter implements RealtimeProvider {
             this.sendCollectionUpdate(clientId, subscriptionId, entities);
 
         } catch (error) {
-            this.sendError(clientId, `Failed to subscribe to collection: ${error}`, subscriptionId);
+            const sanitized = sanitizeErrorForClient(error, request.path);
+            this.sendError(clientId, sanitized.message, subscriptionId, sanitized.code);
         }
     }
 
@@ -373,7 +376,7 @@ export class RealtimeService extends EventEmitter implements RealtimeProvider {
             if (!collection) {
                 const registered = this.registry.getCollections().map(c => c.slug).join(", ");
                 const msg = `Collection not found: '${request.path}'. Registered: [${registered}]`;
-                console.error(`[RealtimeService] ${msg}`);
+                logger.error(`[RealtimeService] ${msg}`);
                 this.sendError(clientId, msg, subscriptionId);
                 return;
             }
@@ -397,7 +400,8 @@ export class RealtimeService extends EventEmitter implements RealtimeProvider {
             this.sendEntityUpdate(clientId, subscriptionId, entity || null);
 
         } catch (error) {
-            this.sendError(clientId, `Failed to subscribe to entity: ${request.path} ${request.entityId} ${error}`, subscriptionId);
+            const sanitized = sanitizeErrorForClient(error, request.path);
+            this.sendError(clientId, sanitized.message, subscriptionId, sanitized.code);
         }
     }
 
@@ -441,7 +445,7 @@ export class RealtimeService extends EventEmitter implements RealtimeProvider {
             try {
                 await this.broadcastChange(path, entityId, databaseId);
             } catch (err) {
-                console.error("❌ [RealtimeService] Failed to broadcast change via pg_notify:", err);
+                logger.error("❌ [RealtimeService] Failed to broadcast change via pg_notify", { error: err });
             }
         }
 
@@ -502,8 +506,8 @@ export class RealtimeService extends EventEmitter implements RealtimeProvider {
                     this.debouncedCollectionRefetch(subscriptionId, notifyPath, subscription);
                 }
             } catch (error) {
-                console.error(`❌ [RealtimeService] Error processing WebSocket subscription ${subscriptionId}:`, error);
-                this.sendError(subscription.clientId, `Failed to process update for subscription ${subscriptionId}`, subscriptionId);
+                const sanitized = sanitizeErrorForClient(error, notifyPath);
+                this.sendError(subscription.clientId, sanitized.message, subscriptionId, sanitized.code);
             }
         }
 
@@ -525,7 +529,7 @@ export class RealtimeService extends EventEmitter implements RealtimeProvider {
                     this.debouncedDriverRefetch(subscriptionId, notifyPath, subscription, callback);
                 }
             } catch (error) {
-                console.error(`❌ [RealtimeService] Error processing DataDriver subscription ${subscriptionId}:`, error);
+                logger.error(`❌ [RealtimeService] Error processing DataDriver subscription ${subscriptionId}`, { error: error });
             }
         }
     }
@@ -551,8 +555,8 @@ export class RealtimeService extends EventEmitter implements RealtimeProvider {
                 const entities = await this.fetchCollectionWithAuth(notifyPath, subscription.collectionRequest!, subscription.authContext);
                 this.sendCollectionUpdate(subscription.clientId, subscriptionId, entities);
             } catch (error) {
-                console.error(`❌ [RealtimeService] Error in debounced refetch for ${subscriptionId}:`, error);
-                this.sendError(subscription.clientId, `Failed to process update for subscription ${subscriptionId}`, subscriptionId);
+                const sanitized = sanitizeErrorForClient(error, notifyPath);
+                this.sendError(subscription.clientId, sanitized.message, subscriptionId, sanitized.code);
             }
         }, RealtimeService.REFETCH_DEBOUNCE_MS));
     }
@@ -577,7 +581,7 @@ export class RealtimeService extends EventEmitter implements RealtimeProvider {
                 const entities = await this.fetchCollectionWithAuth(notifyPath, subscription.collectionRequest!, subscription.authContext);
                 callback(entities);
             } catch (error) {
-                console.error(`❌ [RealtimeService] Error in debounced driver refetch for ${subscriptionId}:`, error);
+                logger.error(`❌ [RealtimeService] Error in debounced driver refetch for ${subscriptionId}`, { error: error });
             }
         }, RealtimeService.REFETCH_DEBOUNCE_MS));
     }
@@ -607,11 +611,13 @@ export class RealtimeService extends EventEmitter implements RealtimeProvider {
             });
 
             // Always wrap in a transaction with session vars, defaulting to anonymous context if missing
-            const activeAuth = authContext || { userId: "anon", roles: ["anon"] };
+            const activeAuth = authContext || { userId: "anon",
+roles: ["anon"] };
             return await this.db.transaction(async (tx) => {
                 await tx.execute(drizzleSql`SELECT set_config('app.user_id', ${activeAuth.userId}, true)`);
                 await tx.execute(drizzleSql`SELECT set_config('app.user_roles', ${activeAuth.roles.join(",")}, true)`);
-                await tx.execute(drizzleSql`SELECT set_config('app.jwt', ${JSON.stringify({ sub: activeAuth.userId, roles: activeAuth.roles })}, true)`);
+                await tx.execute(drizzleSql`SELECT set_config('app.jwt', ${JSON.stringify({ sub: activeAuth.userId,
+roles: activeAuth.roles })}, true)`);
                 const txEntityService = new EntityService(tx, this.registry);
                 let fetchedEntities;
                 if (collectionRequest.searchString) {
@@ -649,7 +655,8 @@ export class RealtimeService extends EventEmitter implements RealtimeProvider {
 
                 if (callbacks?.afterRead || propertyCallbacks?.afterRead) {
                     const contextForCallback = {
-                        user: { uid: activeAuth.userId, roles: activeAuth.roles },
+                        user: { uid: activeAuth.userId,
+roles: activeAuth.roles },
                         driver: this.driver,
                         data: (this.driver && "data" in this.driver) ? (this.driver as DataDriverWithData).data : undefined
                     } as unknown as RebaseCallContext;
@@ -725,8 +732,8 @@ export class RealtimeService extends EventEmitter implements RealtimeProvider {
                 const entity = await this.fetchEntityWithAuth(notifyPath, entityId, subscription.authContext);
                 this.sendEntityUpdate(subscription.clientId, subscriptionId, entity || null);
             } catch (error) {
-                console.error(`❌ [RealtimeService] Error in debounced entity refetch for ${subscriptionId}:`, error);
-                this.sendError(subscription.clientId, `Failed to process entity update for subscription ${subscriptionId}`, subscriptionId);
+                const sanitized = sanitizeErrorForClient(error, notifyPath);
+                this.sendError(subscription.clientId, sanitized.message, subscriptionId, sanitized.code);
             }
         }, RealtimeService.REFETCH_DEBOUNCE_MS));
     }
@@ -752,7 +759,7 @@ export class RealtimeService extends EventEmitter implements RealtimeProvider {
                 const entity = await this.fetchEntityWithAuth(notifyPath, entityId, subscription.authContext);
                 callback(entity || null);
             } catch (error) {
-                console.error(`❌ [RealtimeService] Error in debounced entity driver refetch for ${subscriptionId}:`, error);
+                logger.error(`❌ [RealtimeService] Error in debounced entity driver refetch for ${subscriptionId}`, { error: error });
             }
         }, RealtimeService.REFETCH_DEBOUNCE_MS));
     }
@@ -774,11 +781,13 @@ export class RealtimeService extends EventEmitter implements RealtimeProvider {
             });
 
             // Always wrap in a transaction with session vars, defaulting to anonymous context if missing
-            const activeAuth = authContext || { userId: "anon", roles: ["anon"] };
+            const activeAuth = authContext || { userId: "anon",
+roles: ["anon"] };
             return await this.db.transaction(async (tx) => {
                 await tx.execute(drizzleSql`SELECT set_config('app.user_id', ${activeAuth.userId}, true)`);
                 await tx.execute(drizzleSql`SELECT set_config('app.user_roles', ${activeAuth.roles.join(",")}, true)`);
-                await tx.execute(drizzleSql`SELECT set_config('app.jwt', ${JSON.stringify({ sub: activeAuth.userId, roles: activeAuth.roles })}, true)`);
+                await tx.execute(drizzleSql`SELECT set_config('app.jwt', ${JSON.stringify({ sub: activeAuth.userId,
+roles: activeAuth.roles })}, true)`);
                 const txEntityService = new EntityService(tx, this.registry);
                 let processedEntity = await txEntityService.fetchEntity(notifyPath, entityId, collection?.databaseId);
 
@@ -792,7 +801,8 @@ export class RealtimeService extends EventEmitter implements RealtimeProvider {
 
                     if (callbacks?.afterRead || propertyCallbacks?.afterRead) {
                         const contextForCallback = {
-                            user: { uid: activeAuth.userId, roles: activeAuth.roles },
+                            user: { uid: activeAuth.userId,
+roles: activeAuth.roles },
                             driver: this.driver,
                             data: (this.driver && "data" in this.driver) ? (this.driver as DataDriverWithData).data : undefined
                         } as unknown as RebaseCallContext;
@@ -855,17 +865,19 @@ export class RealtimeService extends EventEmitter implements RealtimeProvider {
         this.sendMessage(clientId, message);
     }
 
-    private sendError(clientId: string, error: string, subscriptionId?: string) {
-        console.error("Error handling collection subscription:", error);
+    private sendError(clientId: string, error: string, subscriptionId?: string, code?: string) {
         const message = {
             type: "error" as const,
             subscriptionId,
+            payload: {
+                error: code ? { message: error, code } : error
+            },
             error
         };
         this.sendMessage(clientId, message);
     }
 
-    private sendMessage(clientId: string, message: CollectionUpdateMessage | EntityUpdateMessage | CollectionEntityPatchMessage | { type: string; subscriptionId?: string; error?: string }) {
+    private sendMessage(clientId: string, message: CollectionUpdateMessage | EntityUpdateMessage | CollectionEntityPatchMessage | { type: string; subscriptionId?: string; error?: string; payload?: unknown }) {
         const client = this.clients.get(clientId);
         if (client && client.readyState === WebSocket.OPEN) {
             client.send(JSON.stringify(message));
@@ -953,7 +965,8 @@ export class RealtimeService extends EventEmitter implements RealtimeProvider {
         }
 
         const channelPresence = this.presence.get(channel)!;
-        channelPresence.set(clientId, { state, lastSeen: Date.now() });
+        channelPresence.set(clientId, { state,
+lastSeen: Date.now() });
 
         // Broadcast join / state update to channel
         this.broadcastPresenceDiff(channel, { [clientId]: state }, {});
@@ -1102,7 +1115,7 @@ export class RealtimeService extends EventEmitter implements RealtimeProvider {
      */
     async startListening(connectionString: string): Promise<void> {
         if (this.broadcasting) {
-            console.warn("⚠️ [RealtimeService] startListening called but already listening. Ignoring.");
+            logger.warn("⚠️ [RealtimeService] startListening called but already listening. Ignoring.");
             return;
         }
 
@@ -1111,7 +1124,7 @@ export class RealtimeService extends EventEmitter implements RealtimeProvider {
         // works correctly if the initial connection attempt fails.
         this.broadcasting = true;
         await this.connectListenClient();
-        console.log(`📡 [RealtimeService] Cross-instance realtime enabled (instanceId: ${this.instanceId})`);
+        logger.info(`📡 [RealtimeService] Cross-instance realtime enabled (instanceId: ${this.instanceId})`);
     }
 
     /**
@@ -1129,7 +1142,7 @@ export class RealtimeService extends EventEmitter implements RealtimeProvider {
             } catch { /* ignore close errors */ }
             this.listenClient = undefined;
         }
-        console.log("📡 [RealtimeService] Cross-instance realtime disabled.");
+        logger.info("📡 [RealtimeService] Cross-instance realtime disabled.");
     }
 
     /**
@@ -1156,13 +1169,13 @@ export class RealtimeService extends EventEmitter implements RealtimeProvider {
             const client = new PgClient({ connectionString: this.listenConnectionString });
 
             client.on("error", (err) => {
-                console.error("❌ [RealtimeService] LISTEN client error:", err.message);
+                logger.error("❌ [RealtimeService] LISTEN client error", { detail: err.message });
                 this.scheduleReconnect();
             });
 
             client.on("end", () => {
                 if (this.broadcasting) {
-                    console.warn("⚠️ [RealtimeService] LISTEN client disconnected unexpectedly.");
+                    logger.warn("⚠️ [RealtimeService] LISTEN client disconnected unexpectedly.");
                     this.scheduleReconnect();
                 }
             });
@@ -1209,7 +1222,7 @@ export class RealtimeService extends EventEmitter implements RealtimeProvider {
                     // Trigger local fan-out with broadcast=false to avoid re-broadcasting
                     await this.notifyEntityUpdate(p, eid, entity, db ?? undefined, false);
                 } catch (err) {
-                    console.error("❌ [RealtimeService] Error processing cross-instance notification:", err);
+                    logger.error("❌ [RealtimeService] Error processing cross-instance notification", { error: err });
                 }
             });
 
@@ -1219,7 +1232,7 @@ export class RealtimeService extends EventEmitter implements RealtimeProvider {
 
             this.debugLog(`📡 [RealtimeService] LISTEN client connected on channel "${PG_NOTIFY_CHANNEL}"`);
         } catch (err) {
-            console.error("❌ [RealtimeService] Failed to connect LISTEN client:", err);
+            logger.error("❌ [RealtimeService] Failed to connect LISTEN client", { error: err });
             this.scheduleReconnect();
         }
     }

package/src/types.ts

@@ -0,0 +1,4 @@
+import type { PgTable, AnyPgColumn } from "drizzle-orm/pg-core";
+
+/** Drizzle PgTable with column access by name. Runtime Drizzle tables satisfy this shape. */
+export type RebasePgTable = PgTable & Record<string, AnyPgColumn>;