@remix-run/data-table-postgres 0.0.0 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Shopify Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,88 @@
-# Placeholder package
+# data-table-postgres
 
-This package is intentionally empty and published only as a temporary placeholder.
+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`.
+
+## Features
+
+- **Native `pg` Integration**: Works with `pg` `Pool` and `PoolClient` instances
+- **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`
+- **Migration DDL Support**: Compiles and executes `DataMigrationOperation` operations for `remix/data-table/migrations`
+- **Postgres Capabilities Enabled By Default**:
+  - `returning: true`
+  - `savepoints: true`
+  - `upsert: true`
+  - `transactionalDdl: true`
+  - `migrationLock: true`
+
+## Installation
+
+```sh
+npm i remix pg
+```
+
+## Usage
+
+```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 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`.
+
+## Adapter Capabilities
+
+`data-table-postgres` reports this capability set by default:
+
+- `returning: true`
+- `savepoints: true`
+- `upsert: true`
+- `transactionalDdl: true`
+- `migrationLock: true`
+
+## Advanced Usage
+
+### Transaction Options
+
+Transaction options are passed through to the adapter as hints.
+
+```ts
+await db.transaction(async (txDb) => txDb.exec('select 1'), {
+  isolationLevel: 'serializable',
+  readOnly: false,
+})
+```
+
+### Capability Overrides For Testing
+
+You can override capabilities to verify fallback paths in tests.
+
+```ts
+import { createPostgresDatabaseAdapter } from 'remix/data-table-postgres'
+
+let adapter = createPostgresDatabaseAdapter(pool, {
+  capabilities: {
+    returning: false,
+  },
+})
+```
+
+## 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
+
+## License
+
+See [LICENSE](https://github.com/remix-run/remix/blob/main/LICENSE)

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export type { PostgresDatabaseAdapterOptions } from './lib/adapter.ts';
+export { createPostgresDatabaseAdapter, PostgresDatabaseAdapter } from './lib/adapter.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,8BAA8B,EAAE,MAAM,kBAAkB,CAAA;AACtE,OAAO,EAAE,6BAA6B,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAA"}

package/dist/index.js

@@ -0,0 +1 @@
+export { createPostgresDatabaseAdapter, PostgresDatabaseAdapter } from "./lib/adapter.js";

package/dist/lib/adapter.d.ts

@@ -0,0 +1,131 @@
+import type { AdapterCapabilityOverrides, DataMigrationRequest, DataManipulationRequest, DataMigrationResult, DataMigrationOperation, DataManipulationResult, DataManipulationOperation, DatabaseAdapter, SqlStatement, TableRef, TransactionOptions, TransactionToken } from '@remix-run/data-table';
+import type { Pool as PostgresPool, PoolClient as PostgresPoolClient } from 'pg';
+/**
+ * Postgres adapter configuration.
+ */
+export type PostgresDatabaseAdapterOptions = {
+    capabilities?: AdapterCapabilityOverrides;
+};
+type PostgresQueryable = PostgresPool | PostgresPoolClient;
+/**
+ * `DatabaseAdapter` implementation for postgres-compatible clients.
+ */
+export declare class PostgresDatabaseAdapter implements DatabaseAdapter {
+    #private;
+    /**
+     * The SQL dialect identifier reported by this adapter.
+     */
+    dialect: string;
+    /**
+     * Feature flags describing the postgres behaviors supported by this adapter.
+     */
+    capabilities: {
+        returning: boolean;
+        savepoints: boolean;
+        upsert: boolean;
+        transactionalDdl: boolean;
+        migrationLock: boolean;
+    };
+    constructor(client: PostgresQueryable, options?: PostgresDatabaseAdapterOptions);
+    /**
+     * Compiles a data or migration operation to postgres SQL statements.
+     * @param operation Operation to compile.
+     * @returns Compiled SQL statements.
+     */
+    compileSql(operation: DataManipulationOperation | DataMigrationOperation): SqlStatement[];
+    /**
+     * Executes a postgres data-manipulation request.
+     * @param request Request to execute.
+     * @returns Execution result.
+     */
+    execute(request: DataManipulationRequest): Promise<DataManipulationResult>;
+    /**
+     * Executes postgres migration operations.
+     * @param request Migration request to execute.
+     * @returns Migration result.
+     */
+    migrate(request: DataMigrationRequest): Promise<DataMigrationResult>;
+    /**
+     * Checks whether a table exists in postgres.
+     * @param table Table reference to inspect.
+     * @param transaction Optional transaction token.
+     * @returns `true` when the table exists.
+     */
+    hasTable(table: TableRef, transaction?: TransactionToken): Promise<boolean>;
+    /**
+     * Checks whether a column exists in postgres.
+     * @param table Table reference to inspect.
+     * @param column Column name to look up.
+     * @param transaction Optional transaction token.
+     * @returns `true` when the column exists.
+     */
+    hasColumn(table: TableRef, column: string, transaction?: TransactionToken): Promise<boolean>;
+    /**
+     * Starts a postgres transaction.
+     * @param options Transaction options.
+     * @returns Transaction token.
+     */
+    beginTransaction(options?: TransactionOptions): Promise<TransactionToken>;
+    /**
+     * Commits an open postgres transaction.
+     * @param token Transaction token to commit.
+     * @returns A promise that resolves when the transaction is committed.
+     */
+    commitTransaction(token: TransactionToken): Promise<void>;
+    /**
+     * Rolls back an open postgres transaction.
+     * @param token Transaction token to roll back.
+     * @returns A promise that resolves when the transaction is rolled back.
+     */
+    rollbackTransaction(token: TransactionToken): Promise<void>;
+    /**
+     * Creates a savepoint in an open postgres transaction.
+     * @param token Transaction token to use.
+     * @param name Savepoint name.
+     * @returns A promise that resolves when the savepoint is created.
+     */
+    createSavepoint(token: TransactionToken, name: string): Promise<void>;
+    /**
+     * Rolls back to a savepoint in an open postgres transaction.
+     * @param token Transaction token to use.
+     * @param name Savepoint name.
+     * @returns A promise that resolves when the rollback completes.
+     */
+    rollbackToSavepoint(token: TransactionToken, name: string): Promise<void>;
+    /**
+     * Releases a savepoint in an open postgres transaction.
+     * @param token Transaction token to use.
+     * @param name Savepoint name.
+     * @returns A promise that resolves when the savepoint is released.
+     */
+    releaseSavepoint(token: TransactionToken, name: string): Promise<void>;
+    /**
+     * Acquires the postgres migration lock.
+     * @returns A promise that resolves when the lock is acquired.
+     */
+    acquireMigrationLock(): Promise<void>;
+    /**
+     * Releases the postgres migration lock.
+     * @returns A promise that resolves when the lock is released.
+     */
+    releaseMigrationLock(): Promise<void>;
+}
+/**
+ * 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, options?: PostgresDatabaseAdapterOptions): PostgresDatabaseAdapter;
+export {};
+//# sourceMappingURL=adapter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../src/lib/adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,0BAA0B,EAC1B,oBAAoB,EACpB,uBAAuB,EACvB,mBAAmB,EACnB,sBAAsB,EACtB,sBAAsB,EACtB,yBAAyB,EACzB,eAAe,EAEf,YAAY,EACZ,QAAQ,EACR,kBAAkB,EAClB,gBAAgB,EACjB,MAAM,uBAAuB,CAAA;AAO9B,OAAO,KAAK,EAAE,IAAI,IAAI,YAAY,EAAE,UAAU,IAAI,kBAAkB,EAAE,MAAM,IAAI,CAAA;AAIhF;;GAEG;AACH,MAAM,MAAM,8BAA8B,GAAG;IAC3C,YAAY,CAAC,EAAE,0BAA0B,CAAA;CAC1C,CAAA;AAOD,KAAK,iBAAiB,GAAG,YAAY,GAAG,kBAAkB,CAAA;AAE1D;;GAEG;AACH,qBAAa,uBAAwB,YAAW,eAAe;;IAC7D;;OAEG;IACH,OAAO,SAAa;IAEpB;;OAEG;IACH,YAAY;;;;;;MAAA;IAMZ,YAAY,MAAM,EAAE,iBAAiB,EAAE,OAAO,CAAC,EAAE,8BAA8B,EAS9E;IAED;;;;OAIG;IACH,UAAU,CAAC,SAAS,EAAE,yBAAyB,GAAG,sBAAsB,GAAG,YAAY,EAAE,CAOxF;IAED;;;;OAIG;IACG,OAAO,CAAC,OAAO,EAAE,uBAAuB,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAuB/E;IAED;;;;OAIG;IACG,OAAO,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAWzE;IAED;;;;;OAKG;IACG,QAAQ,CAAC,KAAK,EAAE,QAAQ,EAAE,WAAW,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,OAAO,CAAC,CAMhF;IAED;;;;;;OAMG;IACG,SAAS,CACb,KAAK,EAAE,QAAQ,EACf,MAAM,EAAE,MAAM,EACd,WAAW,CAAC,EAAE,gBAAgB,GAC7B,OAAO,CAAC,OAAO,CAAC,CASlB;IAED;;;;OAIG;IACG,gBAAgB,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CA0B9E;IAED;;;;OAIG;IACG,iBAAiB,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAgB9D;IAED;;;;OAIG;IACG,mBAAmB,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAgBhE;IAED;;;;;OAKG;IACG,eAAe,CAAC,KAAK,EAAE,gBAAgB,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAG1E;IAED;;;;;OAKG;IACG,mBAAmB,CAAC,KAAK,EAAE,gBAAgB,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAG9E;IAED;;;;;OAKG;IACG,gBAAgB,CAAC,KAAK,EAAE,gBAAgB,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAG3E;IAED;;;OAGG;IACG,oBAAoB,IAAI,OAAO,CAAC,IAAI,CAAC,CAE1C;IAED;;;OAGG;IACG,oBAAoB,IAAI,OAAO,CAAC,IAAI,CAAC,CAE1C;CAmBF;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,6BAA6B,CAC3C,MAAM,EAAE,iBAAiB,EACzB,OAAO,CAAC,EAAE,8BAA8B,GACvC,uBAAuB,CAEzB"}