@rebasepro/server-postgresql 0.4.0 → 0.6.0

package/README.md

@@ -1,106 +1,86 @@
-# @rebasepro/postgresql
+# @rebasepro/server-postgresql
 
-PostgreSQL data source client for Rebase with real-time WebSocket connectivity.
-
-This package provides a complete client-side implementation for connecting Rebase applications to PostgreSQL backends, featuring real-time synchronization via WebSockets.
+PostgreSQL database driver for Rebase, built on Drizzle ORM.
 
 ## Installation
 
 ```bash
-npm install @rebasepro/postgresql @rebasepro/core
+pnpm add @rebasepro/server-postgresql
 ```
 
-## Usage
+## What This Package Does
 
-### Basic Setup with React Hook
+Implements the Rebase `DatabaseAdapter` / `BackendBootstrapper` interfaces for PostgreSQL. It provides connection pooling, a Drizzle-based data driver, Postgres LISTEN/NOTIFY realtime, auth table management, entity history, schema generation, branching, read replicas, and WebSocket support. Plug it into `@rebasepro/server-core` via `createPostgresAdapter()` or `createPostgresBootstrapper()`.
 
-```typescript
-import { usePostgresDataSource } from "@rebasepro/postgresql";
-import { Rebase } from "@rebasepro/core";
-
-function App() {
-    const dataSource = usePostgresDataSource({
-        baseUrl: "http://localhost:3001",
-        websocketUrl: "ws://localhost:3001", // Optional, will be inferred from baseUrl
-        headers: { // Optional
-            "Authorization": "Bearer your-token"
-        }
-    });
-
-    return (
-        <Rebase
-            dataSource={dataSource}
-            collections={collections}
-            // ... other props
-        />
-    );
-}
-```
+## Key Exports
 
-### Creating Data Source Directly
+| Export | Description |
+|--------|-------------|
+| `createPostgresAdapter(config)` | Creates a `DatabaseAdapter` for use with `initializeRebaseBackend({ database: ... })`. Recommended API. |
+| `createPostgresBootstrapper(config)` | Lower-level `BackendBootstrapper` factory. Used internally by the adapter. |
+| `createPostgresDatabaseConnection(url, schema?, poolConfig?)` | Creates a production-grade pooled Drizzle connection. Returns `{ db, pool, connectionString }`. |
+| `createDirectDatabaseConnection(url, schema?, poolConfig?)` | Non-pooled connection for LISTEN/NOTIFY and advisory locks (bypasses PgBouncer). |
+| `createReadReplicaConnection(url, schema?, poolConfig?)` | Read-only connection for routing reads to replicas. |
+| `PostgresBackendDriver` | The `DataDriver` implementation — CRUD, filtering, RLS, subcollections, admin SQL. |
+| `RealtimeService` | Postgres LISTEN/NOTIFY-based `RealtimeProvider`. |
+| `DatabasePoolManager` | Per-branch/per-tenant dynamic pool management (used with `ADMIN_CONNECTION_STRING`). |
+| `PostgresCollectionRegistry` | Collection → Drizzle table registry with enum and relation tracking. |
+| `BranchService` | Database branching (schema-level isolation). |
+| `generateDrizzleSchema(collections)` | Generates Drizzle schema code from collection definitions. |
+| `createAuthSchema(schemaName?)` | Generates Drizzle tables for the auth system (`users`, `roles`, `user_roles`). |
 
-```typescript
-import { createPostgresDataSource } from "@rebasepro/postgresql";
+## Quick Start
 
-const dataSource = createPostgresDataSource({
-    baseUrl: "http://localhost:3001",
-    websocketUrl: "ws://localhost:3001"
+```typescript
+import { createPostgresDatabaseConnection } from "@rebasepro/server-postgresql";
+import { createPostgresAdapter } from "@rebasepro/server-postgresql";
+import { initializeRebaseBackend } from "@rebasepro/server-core";
+import * as schema from "./generated/schema";
+
+// Create connection
+const { db, pool } = createPostgresDatabaseConnection(
+  process.env.DATABASE_URL,
+  schema
+);
+
+// Create adapter and pass to server-core
+const database = createPostgresAdapter({
+  connection: db,
+  connectionString: process.env.DATABASE_URL,
+  schema: { tables: schema },
 });
-```
 
-## Features
-
-- **Real-time Synchronization**: WebSocket-based real-time updates for collections and entities
-- **Automatic Reconnection**: Built-in reconnection logic with exponential backoff
-- **Type Safety**: Full TypeScript support with Rebase core types
-- **Error Handling**: Comprehensive error handling with custom error types
-- **Connection Management**: Connection status monitoring and queue management
-
-## API
-
-### Configuration
+const backend = await initializeRebaseBackend({
+  app,
+  server,
+  database,
+  collections,
+  auth: { /* ... */ },
+});
 
-```typescript
-interface PostgresDataSourceConfig {
-    baseUrl: string;           // Backend server URL
-    websocketUrl?: string;     // WebSocket URL (optional)
-    headers?: Record<string, string>; // Custom headers (optional)
-}
+// Graceful shutdown
+process.on("SIGTERM", async () => {
+  await backend.shutdown();
+  await pool.end();
+});
 ```
 
-### Methods
-
-The PostgreSQL data source implements all Rebase `DataSource` methods:
-
-- `fetchCollection<M>(props): Promise<Entity<M>[]>`
-- `fetchEntity<M>(props): Promise<Entity<M> | undefined>`
-- `saveEntity<M>(props): Promise<Entity<M>>`
-- `deleteEntity<M>(props): Promise<void>`
-- `checkUniqueField(...): Promise<boolean>`
-- `generateEntityId(...): string`
-- `countEntities<M>(props): Promise<number>`
-- `listenCollection<M>(props): () => void`
-- `listenEntity<M>(props): () => void`
-
-## Backend Requirements
-
-This client expects a WebSocket-enabled backend that handles the following message types:
-
-- `FETCH_COLLECTION`
-- `FETCH_ENTITY`
-- `SAVE_ENTITY`
-- `DELETE_ENTITY`
-- `CHECK_UNIQUE_FIELD`
-- `GENERATE_ENTITY_ID`
-- `COUNT_ENTITIES`
-- `subscribe_collection`
-- `subscribe_entity`
-- `unsubscribe`
-
-## Development
-
-This package is part of the Rebase monorepo. For development instructions, see the main repository README.
-
-## License
-
-MIT
+## Connection Pool Defaults
+
+| Option | Default |
+|--------|---------|
+| `max` | 20 |
+| `idleTimeoutMillis` | 30,000 |
+| `connectionTimeoutMillis` | 10,000 |
+| `queryTimeout` | 30,000 |
+| `statementTimeout` | 30,000 |
+| `keepAlive` | true |
+
+## Related Packages
+
+| Package | Role |
+|---------|------|
+| `@rebasepro/server-core` | Backend orchestrator that consumes this adapter |
+| `@rebasepro/types` | Shared interfaces (`DatabaseAdapter`, `BackendBootstrapper`, `DataDriver`) |
+| `@rebasepro/sdk-generator` | Generates typed SDKs from collections |
+| `@rebasepro/common` | Default collections and shared utilities |

package/dist/{server-postgresql/src/PostgresAdapter.d.ts → PostgresAdapter.d.ts}

@@ -1,5 +1,5 @@
 import { DatabaseAdapter } from "@rebasepro/types";
-import type { PostgresDriverConfig } from "@rebasepro/server-core";
+import type { PostgresDriverConfig } from "./PostgresBootstrapper";
 /**
  * Creates a Postgres database adapter for Rebase.
  */

package/dist/{server-postgresql/src/PostgresBackendDriver.d.ts → PostgresBackendDriver.d.ts}

@@ -3,9 +3,8 @@ import { BranchService } from "./services/BranchService";
 import { RealtimeService } from "./services/realtimeService";
 import { DatabasePoolManager } from "./databasePoolManager";
 import { DrizzleClient } from "./interfaces";
-import { User, RebaseClient } from "@rebasepro/types";
+import { DatabaseAdmin, DataDriver, DeleteEntityProps, Entity, EntityCollection, FetchCollectionProps, FetchEntityProps, ListenCollectionProps, ListenEntityProps, RebaseClient, RebaseData, RestFetchService, SaveEntityProps, TableMetadata, User } from "@rebasepro/types";
 import { PostgresCollectionRegistry } from "./collections/PostgresCollectionRegistry";
-import { DataDriver, DeleteEntityProps, Entity, EntityCollection, FetchCollectionProps, FetchEntityProps, ListenCollectionProps, ListenEntityProps, SaveEntityProps, RebaseData, TableMetadata, DatabaseAdmin, RestFetchService } from "@rebasepro/types";
 import { HistoryService } from "./history/HistoryService";
 export declare class PostgresBackendDriver implements DataDriver {
     db: DrizzleClient;
@@ -44,6 +43,7 @@ export declare class PostgresBackendDriver implements DataDriver {
      * implements the matching method signatures.
      */
     get restFetchService(): import("./services").EntityFetchService;
+    private buildCallContext;
     private resolveCollectionCallbacks;
     fetchCollection<M extends Record<string, unknown>>({ path, collection, filter, limit, offset, startAfter, orderBy, searchString, order, vectorSearch }: FetchCollectionProps<M>): Promise<Entity<M>[]>;
     listenCollection<M extends Record<string, unknown>>({ path, collection, filter, limit, offset, startAfter, orderBy, searchString, order, onUpdate, onError }: ListenCollectionProps<M>): () => void;

package/dist/{server-postgresql/src/PostgresBootstrapper.d.ts → PostgresBootstrapper.d.ts}

@@ -9,7 +9,17 @@ import { PostgresBackendDriver } from "./PostgresBackendDriver";
 import { RealtimeService } from "./services/realtimeService";
 import { DatabasePoolManager } from "./databasePoolManager";
 import { PostgresCollectionRegistry } from "./collections/PostgresCollectionRegistry";
-import type { PostgresDriverConfig } from "@rebasepro/server-core";
+export interface PostgresDriverConfig {
+    connectionString?: string;
+    adminConnectionString?: string;
+    readConnectionString?: string;
+    connection?: unknown;
+    schema?: {
+        tables?: Record<string, unknown>;
+        enums?: Record<string, unknown>;
+        relations?: Record<string, unknown>;
+    };
+}
 /**
  * Opaque internals bag that PostgresBootstrapper stores during `initializeDriver()`
  * and re-uses in subsequent lifecycle hooks.

package/dist/{server-postgresql/src/auth → auth}/services.d.ts

@@ -1,13 +1,13 @@
 import { NodePgDatabase } from "drizzle-orm/node-postgres";
-import { PgTable, AnyPgColumn } from "drizzle-orm/pg-core";
+import type { RebasePgTable } from "../types";
 import { UserRepository, TokenRepository, MfaRepository, AuthRepository, UserData, CreateUserData, RoleData, CreateRoleData, RefreshTokenInfo, PasswordResetTokenInfo, UserIdentityData, ListUsersOptions, PaginatedUsersResult, MfaFactor, MfaChallengeInfo, RoleData as Role } from "@rebasepro/server-core";
 export type { Role };
 export interface AuthSchemaTables {
-    users: PgTable & Record<string, AnyPgColumn>;
-    refreshTokens: PgTable & Record<string, AnyPgColumn>;
-    passwordResetTokens: PgTable & Record<string, AnyPgColumn>;
-    appConfig: PgTable & Record<string, AnyPgColumn>;
-    userIdentities: PgTable & Record<string, AnyPgColumn>;
+    users: RebasePgTable;
+    refreshTokens: RebasePgTable;
+    passwordResetTokens: RebasePgTable;
+    appConfig: RebasePgTable;
+    userIdentities: RebasePgTable;
 }
 /**
  * PostgreSQL implementation of UserRepository.
@@ -17,7 +17,7 @@ export declare class UserService implements UserRepository {
     private db;
     private usersTable;
     private userIdentitiesTable;
-    constructor(db: NodePgDatabase, tableOrTables?: (PgTable & Record<string, AnyPgColumn>) | Partial<AuthSchemaTables>);
+    constructor(db: NodePgDatabase, tableOrTables?: RebasePgTable | Partial<AuthSchemaTables>);
     private getQualifiedUsersTableName;
     private mapRowToUser;
     private mapPayload;
@@ -74,7 +74,7 @@ export declare class UserService implements UserRepository {
 export declare class RefreshTokenService {
     private db;
     private refreshTokensTable;
-    constructor(db: NodePgDatabase, tableOrTables?: (PgTable & Record<string, AnyPgColumn>) | Partial<AuthSchemaTables>);
+    constructor(db: NodePgDatabase, tableOrTables?: RebasePgTable | Partial<AuthSchemaTables>);
     private getQualifiedRefreshTokensTableName;
     createToken(userId: string, tokenHash: string, expiresAt: Date, userAgent?: string, ipAddress?: string): Promise<void>;
     findByHash(tokenHash: string): Promise<RefreshTokenInfo | null>;
@@ -89,7 +89,7 @@ export declare class RefreshTokenService {
 export declare class PasswordResetTokenService {
     private db;
     private passwordResetTokensTable;
-    constructor(db: NodePgDatabase, tableOrTables?: (PgTable & Record<string, AnyPgColumn>) | Partial<AuthSchemaTables>);
+    constructor(db: NodePgDatabase, tableOrTables?: RebasePgTable | Partial<AuthSchemaTables>);
     private getQualifiedPasswordResetTokensTableName;
     /**
      * Create a password reset token
@@ -123,7 +123,7 @@ export declare class PostgresTokenRepository implements TokenRepository {
     private db;
     private refreshTokenService;
     private passwordResetTokenService;
-    constructor(db: NodePgDatabase, tableOrTables?: (PgTable & Record<string, AnyPgColumn>) | Partial<AuthSchemaTables>);
+    constructor(db: NodePgDatabase, tableOrTables?: RebasePgTable | Partial<AuthSchemaTables>);
     createRefreshToken(userId: string, tokenHash: string, expiresAt: Date, userAgent?: string, ipAddress?: string): Promise<void>;
     findRefreshTokenByHash(tokenHash: string): Promise<RefreshTokenInfo | null>;
     deleteRefreshToken(tokenHash: string): Promise<void>;
@@ -145,7 +145,7 @@ export declare class PostgresAuthRepository implements AuthRepository {
     private db;
     private userService;
     private tokenRepository;
-    constructor(db: NodePgDatabase, tableOrTables?: (PgTable & Record<string, AnyPgColumn>) | Partial<AuthSchemaTables>);
+    constructor(db: NodePgDatabase, tableOrTables?: RebasePgTable | Partial<AuthSchemaTables>);
     createUser(data: CreateUserData): Promise<UserData>;
     getUserById(id: string): Promise<UserData | null>;
     getUserByEmail(email: string): Promise<UserData | null>;

package/dist/{server-postgresql/src/collections → collections}/PostgresCollectionRegistry.d.ts

@@ -19,6 +19,10 @@ export declare class PostgresCollectionRegistry extends CollectionRegistry imple
      * Checks if a specific collection has a registered table
      */
     hasTableForCollection(tableName: string): boolean;
+    /**
+     * Returns all registered table names.
+     */
+    getTableNames(): string[];
     /**
      * Finds collections assigned to a specific driver that do not have a registered table.
      */

package/dist/{server-postgresql/src/data-transformer.d.ts → data-transformer.d.ts}

@@ -42,9 +42,6 @@ export declare function serializePropertyToServer(value: unknown, property: Prop
  * Transform IDs back to relation objects for frontend
  */
 export declare function parseDataFromServer<M extends Record<string, unknown>>(data: M, collection: EntityCollection, db?: NodePgDatabase<Record<string, unknown>>, registry?: PostgresCollectionRegistry): Promise<M>;
-/**
- * Parse a single property value from database format to frontend format
- */
 export declare function parsePropertyFromServer(value: unknown, property: Property, collection: EntityCollection, propertyKey?: string): unknown;
 /**
  * Lightweight value normalization for db.query results.

package/dist/{server-postgresql/src/databasePoolManager.d.ts → databasePoolManager.d.ts}

@@ -6,7 +6,7 @@ export declare class DatabasePoolManager {
     readonly defaultDatabaseName: string;
     private readonly rootConnectionString;
     constructor(adminConnectionString: string);
-    getDrizzle(databaseName: string): NodePgDatabase<any>;
+    getDrizzle(databaseName: string): NodePgDatabase<Record<string, never>>;
     getPool(databaseName: string): Pool;
     /**
      * Disconnect and remove the pool for a specific database.