@rebasepro/server-postgresql 0.3.0 → 0.5.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/common/src/collections/default-collections.d.ts

@@ -1,12 +1,9 @@
-import { PostgresCollection } from "@rebasepro/types";
+import type { PostgresCollection } from "@rebasepro/types";
 /**
- * Default users collection definition.
+ * Default users collection.
  *
- * Shared between the admin UI (for navigation/display) and the backend
- * (for schema generation). Both consumers prepend this to the developer's
- * collections array and rely on generic slug-based deduplication
- * (Map keyed by slug, last-write-wins) so that developer-defined
- * collections with the same slug override this default — no hardcoded
- * string checks required.
+ * Prepended to the developer's collections array by the admin and server.
+ * Slug-based dedup (Map keyed by slug, last-write-wins) lets developers
+ * override by defining their own collection with `slug: "users"`.
  */
 export declare const defaultUsersCollection: PostgresCollection;

package/dist/common/src/data/query_builder.d.ts

@@ -1,4 +1,7 @@
-import { FindResponse, CollectionAccessor, QueryBuilderInterface, FilterOperator } from "@rebasepro/types";
+import { FindResponse, CollectionAccessor, QueryBuilderInterface, FilterOperator, LogicalCondition, WhereValue, FilterCondition } from "@rebasepro/types";
+export declare function or(...conditions: (FilterCondition | LogicalCondition)[]): LogicalCondition;
+export declare function and(...conditions: (FilterCondition | LogicalCondition)[]): LogicalCondition;
+export declare function cond(column: string, operator: FilterOperator, value: unknown): FilterCondition;
 export declare class QueryBuilder<M extends Record<string, unknown> = Record<string, unknown>> implements QueryBuilderInterface<M> {
     private collection;
     private params;
@@ -8,7 +11,8 @@ export declare class QueryBuilder<M extends Record<string, unknown> = Record<str
      * @example
      * client.collection('users').where('age', '>=', 18).find()
      */
-    where(column: keyof M & string, operator: FilterOperator, value: unknown): this;
+    where<K extends keyof M & string>(column: K, operator: FilterOperator, value: WhereValue<M[K]>): this;
+    where(logicalCondition: LogicalCondition): this;
     /**
      * Order the results by a specific column.
      * @example

package/dist/common/src/util/permissions.d.ts

@@ -1,6 +1,14 @@
-import { AuthController, Entity, EntityCollection, User } from "@rebasepro/types";
-export declare function checkOperation<M extends Record<string, unknown>, USER extends User>(collection: EntityCollection<M>, authController: AuthController<USER>, entity: Entity<M> | null, targetOperation: "select" | "insert" | "update" | "delete"): boolean;
-export declare function canReadCollection<M extends Record<string, unknown>, USER extends User>(collection: EntityCollection<M>, authController: AuthController<USER>): boolean;
-export declare function canEditEntity<M extends Record<string, unknown>, USER extends User>(collection: EntityCollection<M>, authController: AuthController<USER>, path: string, entity: Entity<M> | null): boolean;
-export declare function canCreateEntity<M extends Record<string, unknown>, USER extends User>(collection: EntityCollection<M>, authController: AuthController<USER>, path: string, entity: Entity<M> | null): boolean;
-export declare function canDeleteEntity<M extends Record<string, unknown>, USER extends User>(collection: EntityCollection<M>, authController: AuthController<USER>, path: string, entity: Entity<M> | null): boolean;
+import { Entity, EntityCollection, User } from "@rebasepro/types";
+/**
+ * Minimal auth context for permission checking.
+ * Only requires the user object — avoids forcing callers to construct
+ * a full AuthController just to check permissions.
+ */
+export interface AuthContext<USER extends User = User> {
+    user: USER | null;
+}
+export declare function checkOperation<M extends Record<string, unknown>, USER extends User>(collection: EntityCollection<M>, authContext: AuthContext<USER>, entity: Entity<M> | null, targetOperation: "select" | "insert" | "update" | "delete"): boolean;
+export declare function canReadCollection<M extends Record<string, unknown>, USER extends User>(collection: EntityCollection<M>, authContext: AuthContext<USER>): boolean;
+export declare function canEditEntity<M extends Record<string, unknown>, USER extends User>(collection: EntityCollection<M>, authContext: AuthContext<USER>, path: string, entity: Entity<M> | null): boolean;
+export declare function canCreateEntity<M extends Record<string, unknown>, USER extends User>(collection: EntityCollection<M>, authContext: AuthContext<USER>, path: string, entity: Entity<M> | null): boolean;
+export declare function canDeleteEntity<M extends Record<string, unknown>, USER extends User>(collection: EntityCollection<M>, authContext: AuthContext<USER>, path: string, entity: Entity<M> | null): boolean;