@remix-run/data-table-postgres 0.4.0 → 0.5.0

package/README.md

@@ -1,13 +1,12 @@
 # data-table-postgres
 
-PostgreSQL adapter for [`remix/data-table`](https://github.com/remix-run/remix/tree/main/packages/data-table).
-Use this package when you want `data-table` APIs backed by `pg`.
+PostgreSQL database driver for [`remix/data-table`](https://github.com/remix-run/remix/tree/main/packages/data-table), backed by `pg`.
 
 ## Features
 
-- **Native `pg` Integration**: Works with `pg` `Pool` and `PoolClient` instances
+- **Native `pg` Integration**: Creates a pool from `pg` configuration or uses an existing pool or client
 - **Full `data-table` API Support**: Queries, relations, writes, and transactions
-- **Adapter-Owned Compiler**: SQL compilation lives in this adapter, with optional shared pure helpers from `data-table`
+- **PostgreSQL Compiler**: SQL compilation is handled automatically for PostgreSQL
 - **Multi-Statement Migrations**: `executeScript()` runs `up.sql` / `down.sql` files natively via `pg`
 - **Postgres Capabilities Enabled By Default**:
   - `returning: true`
@@ -25,21 +24,20 @@ npm i remix pg
 ## Usage
 
 ```ts
-import { Pool } from 'pg'
-import { createDatabase } from 'remix/data-table'
-import { createPostgresDatabaseAdapter } from 'remix/data-table/postgres'
+import { createPostgresDatabase } from 'remix/data-table/postgres'
 
-let pool = new Pool({
+let db = createPostgresDatabase({
   connectionString: process.env.DATABASE_URL,
 })
-
-let db = createDatabase(createPostgresDatabaseAdapter(pool))
 ```
 
-Use `db.query(...)`, relation loading, and transactions from `remix/data-table`.
-Import any driver-specific types you need directly from `pg`.
+Use `db.query(...)`, relation loading, and transactions from `remix/data-table`. Import any driver-specific types you need directly from `pg`.
+
+Config-backed databases support `db.wipe()` and `db.reset()`. Call `await db.close()` during application shutdown to close the internally created pool. You may pass an existing `pg` pool or client when your application owns the driver lifecycle; `db.close()` leaves supplied clients alone, and destructive lifecycle methods are unavailable in that mode. `db.wipe()` requires a database name resolvable from the connection config (`database`, the path of `connectionString`, or the `PGDATABASE` environment variable) and throws when none is present.
 
-## Adapter Capabilities
+Migration runs reserve one connection for the PostgreSQL advisory lock, migration SQL, and journal updates. Lock acquisition waits up to 60 seconds (via `lock_timeout`) and fails with an error instead of blocking forever. After a successful run the connection is unlocked and returned to the pool; if the migration or unlock fails, the reserved connection is destroyed instead of being reused, so a dirty session can never leak back into the pool. Nested migration lock acquisition throws instead of deadlocking.
+
+## Database Capabilities
 
 `data-table-postgres` reports this capability set by default:
 
@@ -53,7 +51,7 @@ Import any driver-specific types you need directly from `pg`.
 
 ### Transaction Options
 
-Transaction options are passed through to the adapter as hints.
+Transaction options are passed through to PostgreSQL as hints.
 
 ```ts
 await db.transaction(async (txDb) => txDb.exec('select 1'), {
@@ -62,12 +60,38 @@ await db.transaction(async (txDb) => txDb.exec('select 1'), {
 })
 ```
 
+## Running integration tests locally
+
+To start a local Postgres container matching CI:
+
+```sh
+podman run --name postgres \
+  -e POSTGRES_USER=postgres \
+  -e POSTGRES_PASSWORD=postgres \
+  -e POSTGRES_DB=remix \
+  -p 5432:5432 \
+  -d postgres:16
+```
+
+Then run:
+
+```sh
+REMIX_DATA_TABLE_POSTGRES_TEST_URL=postgres://postgres:postgres@127.0.0.1:5432/remix \
+pnpm test src/lib/driver.integration.test.ts
+```
+
+Remove the container when you are done:
+
+```sh
+podman rm -f postgres
+```
+
 ## Related Packages
 
 - [`data-table`](https://github.com/remix-run/remix/tree/main/packages/data-table) - Core query/relations API
 - [`data-schema`](https://github.com/remix-run/remix/tree/main/packages/data-schema) - Schema parsing and validation
-- [`data-table-mysql`](https://github.com/remix-run/remix/tree/main/packages/data-table-mysql) - MySQL adapter
-- [`data-table-sqlite`](https://github.com/remix-run/remix/tree/main/packages/data-table-sqlite) - SQLite adapter
+- [`data-table-mysql`](https://github.com/remix-run/remix/tree/main/packages/data-table-mysql) - MySQL database driver
+- [`data-table-sqlite`](https://github.com/remix-run/remix/tree/main/packages/data-table-sqlite) - SQLite database driver
 
 ## License
 

package/dist/index.d.ts

@@ -1,2 +1,4 @@
-export { createPostgresDatabaseAdapter, PostgresDatabaseAdapter } from './lib/adapter.ts';
+export { createPostgresDatabase, PostgresDatabase } from './lib/database.ts';
+export type { PostgresDatabaseOptions } from './lib/database.ts';
+export type { PostgresDatabaseInput } from './lib/driver.ts';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,6BAA6B,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAA;AAC5E,YAAY,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAA;AAChE,YAAY,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAA"}

package/dist/index.js

@@ -1 +1 @@
-export { createPostgresDatabaseAdapter, PostgresDatabaseAdapter } from "./lib/adapter.js";
+export { createPostgresDatabase, PostgresDatabase } from './lib/database.js';

package/dist/lib/database.d.ts

@@ -0,0 +1,35 @@
+import { Database, type DatabaseOptions } from '@remix-run/data-table';
+import { type PostgresDatabaseInput } from './driver.ts';
+/** Options for creating a PostgreSQL database. */
+export interface PostgresDatabaseOptions extends DatabaseOptions {
+    /** Database used while dropping and recreating the configured database (`postgres` by default). */
+    maintenanceDatabase?: string;
+    /** Template used to recreate the configured database (`template0` by default). */
+    template?: string;
+}
+/** A {@link Database} backed by PostgreSQL. */
+export declare class PostgresDatabase extends Database<'postgres'> {
+    /**
+     * Creates a PostgreSQL-backed database.
+     * @param input PostgreSQL pool configuration, pool, or client.
+     * @param options Database runtime and recreation options.
+     */
+    constructor(input: PostgresDatabaseInput, options?: PostgresDatabaseOptions);
+}
+/**
+ * Creates a PostgreSQL-backed database.
+ *
+ * @param input PostgreSQL pool configuration, pool, or client.
+ * @param options Database runtime and recreation options.
+ * @returns A PostgreSQL database.
+ * @example
+ * ```ts
+ * import { createPostgresDatabase } from 'remix/data-table/postgres'
+ *
+ * let db = createPostgresDatabase({
+ *   connectionString: process.env.DATABASE_URL,
+ * })
+ * ```
+ */
+export declare function createPostgresDatabase(input: PostgresDatabaseInput, options?: PostgresDatabaseOptions): PostgresDatabase;
+//# sourceMappingURL=database.d.ts.map

package/dist/lib/database.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../../src/lib/database.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,KAAK,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAEtE,OAAO,EAA0B,KAAK,qBAAqB,EAAE,MAAM,aAAa,CAAA;AAEhF,kDAAkD;AAClD,MAAM,WAAW,uBAAwB,SAAQ,eAAe;IAC9D,mGAAmG;IACnG,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAC5B,kFAAkF;IAClF,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED,+CAA+C;AAC/C,qBAAa,gBAAiB,SAAQ,QAAQ,CAAC,UAAU,CAAC;IACxD;;;;OAIG;IACH,YAAY,KAAK,EAAE,qBAAqB,EAAE,OAAO,GAAE,uBAA4B,EAE9E;CACF;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,qBAAqB,EAC5B,OAAO,GAAE,uBAA4B,GACpC,gBAAgB,CAElB"}

package/dist/lib/database.js

@@ -0,0 +1,31 @@
+import { Database } from '@remix-run/data-table';
+import { PostgresDatabaseDriver } from './driver.js';
+/** A {@link Database} backed by PostgreSQL. */
+export class PostgresDatabase extends Database {
+    /**
+     * Creates a PostgreSQL-backed database.
+     * @param input PostgreSQL pool configuration, pool, or client.
+     * @param options Database runtime and recreation options.
+     */
+    constructor(input, options = {}) {
+        super(new PostgresDatabaseDriver(input, options), options);
+    }
+}
+/**
+ * Creates a PostgreSQL-backed database.
+ *
+ * @param input PostgreSQL pool configuration, pool, or client.
+ * @param options Database runtime and recreation options.
+ * @returns A PostgreSQL database.
+ * @example
+ * ```ts
+ * import { createPostgresDatabase } from 'remix/data-table/postgres'
+ *
+ * let db = createPostgresDatabase({
+ *   connectionString: process.env.DATABASE_URL,
+ * })
+ * ```
+ */
+export function createPostgresDatabase(input, options = {}) {
+    return new PostgresDatabase(input, options);
+}

package/dist/lib/{adapter.d.ts → driver.d.ts}

@@ -1,26 +1,36 @@
-import type { DataManipulationRequest, DataManipulationResult, DataManipulationOperation, DatabaseAdapter, SqlStatement, TableRef, TransactionOptions, TransactionToken } from '@remix-run/data-table';
+import type { DataManipulationOperation, DataManipulationRequest, DataManipulationResult, DatabaseDriver, SqlStatement, TableRef, TransactionOptions, TransactionToken } from '@remix-run/data-table';
+import pg from 'pg';
 import type { Client as PostgresClient, Pool as PostgresPool, PoolClient as PostgresPoolClient } from 'pg';
+type PostgresPoolConfig = ConstructorParameters<typeof pg.Pool>[0];
+/** Database recreation options for a config-backed PostgreSQL driver. */
+export interface PostgresDatabaseDriverOptions {
+    /** Database used while dropping and recreating the configured database (`postgres` by default). */
+    maintenanceDatabase?: string;
+    /** Template used to recreate the configured database (`template0` by default). */
+    template?: string;
+}
 type PostgresQueryable = PostgresClient | PostgresPool | PostgresPoolClient;
+export type PostgresDatabaseInput = PostgresPoolConfig | PostgresQueryable;
 /**
- * `DatabaseAdapter` implementation for postgres-compatible clients.
+ * PostgreSQL database driver backed by a postgres-compatible client.
  */
-export declare class PostgresDatabaseAdapter implements DatabaseAdapter {
+export declare class PostgresDatabaseDriver implements DatabaseDriver<'postgres'> {
     #private;
     /**
-     * The SQL dialect identifier reported by this adapter.
+     * The SQL dialect identifier reported by this database.
      */
-    dialect: string;
+    get dialect(): 'postgres';
     /**
-     * Feature flags describing the postgres behaviors supported by this adapter.
+     * Feature flags describing the PostgreSQL behaviors supported by this database.
      */
-    capabilities: {
-        returning: boolean;
-        savepoints: boolean;
-        upsert: boolean;
-        transactionalDdl: boolean;
-        migrationLock: boolean;
-    };
-    constructor(client: PostgresQueryable);
+    get capabilities(): Readonly<{
+        returning: true;
+        savepoints: true;
+        upsert: true;
+        transactionalDdl: true;
+        migrationLock: true;
+    }>;
+    constructor(config: PostgresDatabaseInput, options?: PostgresDatabaseDriverOptions);
     /**
      * Compiles a data-manipulation operation to postgres SQL statements.
      * @param operation Operation to compile.
@@ -98,32 +108,24 @@ export declare class PostgresDatabaseAdapter implements DatabaseAdapter {
      */
     releaseSavepoint(token: TransactionToken, name: string): Promise<void>;
     /**
-     * Acquires the postgres migration lock.
-     * @returns A promise that resolves when the lock is acquired.
+     * Destructively recreates the configured PostgreSQL database.
+     * @returns A promise that resolves when the database is ready for use.
      */
-    acquireMigrationLock(): Promise<void>;
+    wipe(): Promise<void>;
+    /** Closes a pool created from configuration. Supplied clients and pools remain caller-owned. */
+    close(): Promise<void>;
     /**
-     * Releases the postgres migration lock.
-     * @returns A promise that resolves when the lock is released.
+     * Runs migration work on the postgres connection that owns the advisory lock.
+     *
+     * Lock acquisition waits up to 60 seconds and throws when the lock cannot
+     * be acquired. Re-entering this method from inside `run` throws instead of
+     * deadlocking, and a failed run destroys the reserved connection instead of
+     * returning it to the pool.
+     * @param name Logical migration lock name.
+     * @param run Migration work to run with a connection-bound driver.
+     * @returns The callback result.
      */
-    releaseMigrationLock(): Promise<void>;
+    withMigrationLock<result>(name: string, run: (driver: DatabaseDriver<'postgres'>) => Promise<result>): Promise<result>;
 }
-/**
- * Creates a postgres `DatabaseAdapter`.
- * @param client `pg` pool or pool client.
- * @param options Optional adapter capability overrides.
- * @returns A configured postgres adapter.
- * @example
- * ```ts
- * import { Pool } from 'pg'
- * import { createDatabase } from 'remix/data-table'
- * import { createPostgresDatabaseAdapter } from 'remix/data-table/postgres'
- *
- * let pool = new Pool({ connectionString: process.env.DATABASE_URL })
- * let adapter = createPostgresDatabaseAdapter(pool)
- * let db = createDatabase(adapter)
- * ```
- */
-export declare function createPostgresDatabaseAdapter(client: PostgresQueryable): PostgresDatabaseAdapter;
 export {};
-//# sourceMappingURL=adapter.d.ts.map
+//# sourceMappingURL=driver.d.ts.map

package/dist/lib/driver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"driver.d.ts","sourceRoot":"","sources":["../../src/lib/driver.ts"],"names":[],"mappings":"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"}