@effect/sql-pg 4.0.0-beta.7 → 4.0.0-beta.70

package/src/PgMigrator.ts

@@ -1,94 +1,132 @@
 /**
- * @since 1.0.0
+ * Utilities for applying Effect SQL migrations to PostgreSQL databases.
+ *
+ * This module re-exports the shared `Migrator` loaders and error types, then
+ * provides `run` and `layer` helpers for applying ordered migrations through
+ * the current PostgreSQL `SqlClient` and `PgClient`. It is typically used at
+ * application startup, during deployment, in integration tests that provision a
+ * temporary PostgreSQL database, or in layer graphs that must prepare the
+ * schema before dependent services are acquired.
+ *
+ * Migrations are recorded in `effect_sql_migrations` by default and are loaded
+ * using the shared `<id>_<name>` file or record-key convention. Only migrations
+ * with an id greater than the latest recorded id are applied, so concurrent
+ * application instances should coordinate startup against the same database and
+ * avoid racing to install the same changes. When `schemaDirectory` is enabled,
+ * this adapter shells out to `pg_dump` using the active `PgClient`
+ * configuration, so `pg_dump` must be available on `PATH` and the layer must
+ * provide child process, filesystem, and path services. The generated dumps
+ * intentionally strip comments, session settings, ownership, and privilege
+ * statements to keep schema snapshots portable across PostgreSQL environments.
+ *
+ * @since 4.0.0
  */
-import type * as Effect from "effect/Effect"
+import * as Effect from "effect/Effect"
+import * as FileSystem from "effect/FileSystem"
 import * as Layer from "effect/Layer"
+import * as Path from "effect/Path"
+import * as Redacted from "effect/Redacted"
+import * as ChildProcess from "effect/unstable/process/ChildProcess"
+import * as ChildProcessSpawner from "effect/unstable/process/ChildProcessSpawner"
 import * as Migrator from "effect/unstable/sql/Migrator"
-import type * as Client from "effect/unstable/sql/SqlClient"
+import type { SqlClient } from "effect/unstable/sql/SqlClient"
 import type { SqlError } from "effect/unstable/sql/SqlError"
+import { PgClient } from "./PgClient.ts"
 
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 export * from "effect/unstable/sql/Migrator"
 
 /**
- * @category constructor
- * @since 1.0.0
+ * Runs PostgreSQL SQL migrations using the configured clients. Schema dumps use `pg_dump` and require child process, filesystem, and path services.
+ *
+ * @category constructors
+ * @since 4.0.0
  */
 export const run: <R2 = never>(
   options: Migrator.MigratorOptions<R2>
 ) => Effect.Effect<
   ReadonlyArray<readonly [id: number, name: string]>,
   Migrator.MigrationError | SqlError,
-  Client.SqlClient | R2
+  | SqlClient
+  | PgClient
+  | ChildProcessSpawner.ChildProcessSpawner
+  | FileSystem.FileSystem
+  | Path.Path
+  | R2
 > = Migrator.make({
-  // TODO: Wait for Command module
-  // dumpSchema(path, table) {
-  //   const pgDump = (args: Array<string>) =>
-  //     Effect.gen(function*() {
-  //       const sql = yield* PgClient
-  //       const dump = yield* pipe(
-  //         Command.make("pg_dump", ...args, "--no-owner", "--no-privileges"),
-  //         Command.env({
-  //           PATH: (globalThis as any).process?.env.PATH,
-  //           PGHOST: sql.config.host,
-  //           PGPORT: sql.config.port?.toString(),
-  //           PGUSER: sql.config.username,
-  //           PGPASSWORD: sql.config.password
-  //             ? Redacted.value(sql.config.password)
-  //             : undefined,
-  //           PGDATABASE: sql.config.database,
-  //           PGSSLMODE: sql.config.ssl ? "require" : "prefer"
-  //         }),
-  //         Command.string
-  //       )
-  //
-  //       return dump.replace(/^--.*$/gm, "")
-  //         .replace(/^SET .*$/gm, "")
-  //         .replace(/^SELECT pg_catalog\..*$/gm, "")
-  //         .replace(/\n{2,}/gm, "\n\n")
-  //         .trim()
-  //     }).pipe(
-  //       Effect.mapError((error) => new Migrator.MigrationError({ kind: "Failed", message: error.message }))
-  //     )
-  //
-  //   const pgDumpSchema = pgDump(["--schema-only"])
-  //
-  //   const pgDumpMigrations = pgDump([
-  //     "--column-inserts",
-  //     "--data-only",
-  //     `--table=${table}`
-  //   ])
-  //
-  //   const pgDumpAll = Effect.map(
-  //     Effect.all([pgDumpSchema, pgDumpMigrations], { concurrency: 2 }),
-  //     ([schema, migrations]) => schema + "\n\n" + migrations
-  //   )
-  //
-  //   const pgDumpFile = (path: string) =>
-  //     Effect.gen(function*() {
-  //       const fs = yield* FileSystem
-  //       const path_ = yield* Path
-  //       const dump = yield* pgDumpAll
-  //       yield* fs.makeDirectory(path_.dirname(path), { recursive: true })
-  //       yield* fs.writeFileString(path, dump)
-  //     }).pipe(
-  //       Effect.mapError((error) => new Migrator.MigrationError({ kind: "Failed", message: error.message }))
-  //     )
-  //
-  //   return pgDumpFile(path)
-  // }
+  dumpSchema(path, table) {
+    const pgDump = (args: Array<string>) =>
+      Effect.gen(function*() {
+        const sql = yield* PgClient
+        const spawner = yield* ChildProcessSpawner.ChildProcessSpawner
+        const dump = yield* ChildProcess.make("pg_dump", [...args, "--no-owner", "--no-privileges"], {
+          env: {
+            PATH: (globalThis as any).process?.env.PATH,
+            PGHOST: sql.config.host,
+            PGPORT: sql.config.port?.toString(),
+            PGUSER: sql.config.username,
+            PGPASSWORD: sql.config.password
+              ? Redacted.value(sql.config.password)
+              : undefined,
+            PGDATABASE: sql.config.database,
+            PGSSLMODE: sql.config.ssl ? "require" : "prefer"
+          }
+        }).pipe(spawner.string)
+
+        return dump.replace(/^--.*$/gm, "")
+          .replace(/^SET .*$/gm, "")
+          .replace(/^SELECT pg_catalog\..*$/gm, "")
+          .replace(/\n{2,}/gm, "\n\n")
+          .trim();
+      }).pipe(
+        Effect.mapError((error) => new Migrator.MigrationError({ kind: "Failed", message: error.message }))
+      )
+
+    const pgDumpSchema = pgDump(["--schema-only"])
+
+    const pgDumpMigrations = pgDump([
+      "--column-inserts",
+      "--data-only",
+      `--table=${table}`
+    ])
+
+    const pgDumpAll = Effect.map(
+      Effect.all([pgDumpSchema, pgDumpMigrations], { concurrency: 2 }),
+      ([schema, migrations]) => schema + "\n\n" + migrations
+    )
+
+    const pgDumpFile = (path: string) =>
+      Effect.gen(function*() {
+        const fs = yield* FileSystem.FileSystem
+        const path_ = yield* Path.Path
+        const dump = yield* pgDumpAll
+        yield* fs.makeDirectory(path_.dirname(path), { recursive: true })
+        yield* fs.writeFileString(path, dump)
+      }).pipe(
+        Effect.mapError((error) => new Migrator.MigrationError({ kind: "Failed", message: error.message }))
+      )
+
+    return pgDumpFile(path)
+  }
 })
 
 /**
+ * Creates a layer that runs PostgreSQL migrations during layer construction, including `pg_dump`-based schema dump support when requested.
+ *
  * @category layers
- * @since 1.0.0
+ * @since 4.0.0
  */
 export const layer = <R>(
   options: Migrator.MigratorOptions<R>
 ): Layer.Layer<
   never,
   Migrator.MigrationError | SqlError,
-  Client.SqlClient | R
+  | SqlClient
+  | PgClient
+  | ChildProcessSpawner.ChildProcessSpawner
+  | FileSystem.FileSystem
+  | Path.Path
+  | R
 > => Layer.effectDiscard(run(options))

package/src/index.ts

@@ -1,15 +1,52 @@
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 
 // @barrel: Auto-generated exports. Do not edit manually.
 
 /**
- * @since 1.0.0
+ * PostgreSQL client implementation for Effect SQL, backed by `pg`.
+ *
+ * This module exposes constructors for creating a scoped `PgClient` from a
+ * managed `pg` pool, a single managed `pg` client, or lower-level connection
+ * acquirers. The resulting service can be provided as both `PgClient` and the
+ * generic `SqlClient`, and is intended for application database access,
+ * migrations, transactional workflows, row streaming, JSON parameters, and
+ * PostgreSQL LISTEN/NOTIFY integration.
+ *
+ * Pool-backed clients acquire connections per operation and reserve dedicated
+ * connections for transactions and cursor streams. Clients built from one
+ * `pg.Client` serialize shared access; enable `acquireForStream` when streams
+ * or listeners need their own client instead of sharing the query connection.
+ * LISTEN uses a scoped long-lived client and automatically issues `UNLISTEN`
+ * when the stream scope closes, so listeners should be scoped for as long as
+ * notifications are needed.
+ *
+ * @since 4.0.0
  */
 export * as PgClient from "./PgClient.ts"
 
 /**
- * @since 1.0.0
+ * Utilities for applying Effect SQL migrations to PostgreSQL databases.
+ *
+ * This module re-exports the shared `Migrator` loaders and error types, then
+ * provides `run` and `layer` helpers for applying ordered migrations through
+ * the current PostgreSQL `SqlClient` and `PgClient`. It is typically used at
+ * application startup, during deployment, in integration tests that provision a
+ * temporary PostgreSQL database, or in layer graphs that must prepare the
+ * schema before dependent services are acquired.
+ *
+ * Migrations are recorded in `effect_sql_migrations` by default and are loaded
+ * using the shared `<id>_<name>` file or record-key convention. Only migrations
+ * with an id greater than the latest recorded id are applied, so concurrent
+ * application instances should coordinate startup against the same database and
+ * avoid racing to install the same changes. When `schemaDirectory` is enabled,
+ * this adapter shells out to `pg_dump` using the active `PgClient`
+ * configuration, so `pg_dump` must be available on `PATH` and the layer must
+ * provide child process, filesystem, and path services. The generated dumps
+ * intentionally strip comments, session settings, ownership, and privilege
+ * statements to keep schema snapshots portable across PostgreSQL environments.
+ *
+ * @since 4.0.0
  */
 export * as PgMigrator from "./PgMigrator.ts"