The best way to control Claude Code, Codex and more from any computer or phone
Mirrored from https://github.com/Camo67/t3code.git
Synced Nov 21, 04:45 UTC
| 1 | /** |
| 2 | * Runs database migrations for PostgreSQL projects that use Effect SQL. |
| 3 | * |
| 4 | * This module reuses the shared SQL migrator and connects it to PostgreSQL. It |
| 5 | * exposes the common migration helpers and adds `run` and `layer` functions |
| 6 | * that apply pending migration files with the current SQL client. When schema |
| 7 | * dumps are requested, it uses `pg_dump` and the usual process and filesystem |
| 8 | * services. |
| 9 | * |
| 10 | * @stability unstable |
| 11 | * @since 4.0.0 |
| 12 | */ |
| 13 | import * as Duration from "effect/Duration" |
| 14 | import * as Effect from "effect/Effect" |
| 15 | import * as FileSystem from "effect/FileSystem" |
| 16 | import * as Layer from "effect/Layer" |
| 17 | import * as Path from "effect/Path" |
| 18 | import * as ChildProcess from "effect/process/ChildProcess" |
| 19 | import * as ChildProcessSpawner from "effect/process/ChildProcessSpawner" |
| 20 | import * as Migrator from "effect/sql/Migrator" |
| 21 | import type { SqlClient } from "effect/sql/SqlClient" |
| 22 | import type { SqlError } from "effect/sql/SqlError" |
| 23 | import { Buffer } from "node:buffer" |
| 24 | import * as NodeFs from "node:fs/promises" |
| 25 | import * as Os from "node:os" |
| 26 | import * as NodePath from "node:path" |
| 27 | import * as Tls from "node:tls" |
| 28 | import { resolveConfig, type ResolvedConfig } from "./internal/config.ts" |
| 29 | import * as Password from "./internal/password.ts" |
| 30 | import { PgClient, type PgClientConfig } from "./PgClient.ts" |
| 31 | |
| 32 | /** |
| 33 | * @since 4.0.0 |
| 34 | */ |
| 35 | export * from "effect/sql/Migrator" |
| 36 | export { |
| 37 | /** |
| 38 | * @stability unstable |
| 39 | * @category loaders |
| 40 | * @since 4.0.0 |
| 41 | */ |
| 42 | fromFileSystem |
| 43 | } from "effect/sql/MigratorFileSystem" |
| 44 | |
| 45 | /** |
| 46 | * Runs PostgreSQL SQL migrations using the configured clients. Schema dumps use `pg_dump` and require child process, filesystem, and path services. |
| 47 | * |
| 48 | * **Details** |
| 49 | * |
| 50 | * `pg_dump` connects with the same resolved settings as `PgClient`: URL and |
| 51 | * explicit fields, Unix socket path, user, database, `application_name`, |
| 52 | * `options`, and connect timeout. The password is passed through `PGPASSWORD` |
| 53 | * and the inherited environment is not used. |
| 54 | * |
| 55 | * TLS maps to libpq as follows: no TLS uses `sslmode=disable`, |
| 56 | * `rejectUnauthorized: false` uses `require`, and verified TLS uses |
| 57 | * `verify-full` with the client's trusted CAs (`ssl.ca`, or Node's default CAs) |
| 58 | * written to a temporary `sslrootcert` file. A PEM `ssl.cert` / `ssl.key` pair |
| 59 | * is passed as `sslcert` / `sslkey`. |
| 60 | * |
| 61 | * URL `sslmode=prefer` / `allow` also uses `verify-full`, because the client |
| 62 | * verifies the certificate whenever the server accepts TLS and libpq cannot |
| 63 | * verify while keeping a plaintext fallback. Dumps from servers that refuse TLS |
| 64 | * therefore fail, even though the client falls back to plaintext. |
| 65 | * |
| 66 | * Node's default CAs require `tls.getCACertificates` (Node.js 22.15 / 23.10 or |
| 67 | * later). On older runtimes, verified TLS dumps require an explicit `ssl.ca`. |
| 68 | * |
| 69 | * The dump fails, and the migrator logs the error, for custom `stream` |
| 70 | * connections, TLS over Unix sockets, socket paths not named |
| 71 | * `.s.PGSQL.<port>`, a `servername` different from the host, and other `ssl` |
| 72 | * options. |
| 73 | * |
| 74 | * @stability unstable |
| 75 | * @category running |
| 76 | * @since 4.0.0 |
| 77 | */ |
| 78 | export const run: <R2 = never>( |
| 79 | options: Migrator.MigratorOptions<R2> |
| 80 | ) => Effect.Effect< |
| 81 | ReadonlyArray<readonly [id: number, name: string]>, |
| 82 | Migrator.MigrationError | SqlError, |
| 83 | | SqlClient |
| 84 | | PgClient |
| 85 | | ChildProcessSpawner.ChildProcessSpawner |
| 86 | | FileSystem.FileSystem |
| 87 | | Path.Path |
| 88 | | R2 |
| 89 | > = Migrator.make({ |
| 90 | dumpSchema(path, table) { |
| 91 | const pgDump = Effect.fnUntraced(function*(connection: DumpConnection, args: Array<string>) { |
| 92 | const spawner = yield* ChildProcessSpawner.ChildProcessSpawner |
| 93 | const dump = yield* ChildProcess.make("pg_dump", [ |
| 94 | ...args, |
| 95 | "--no-owner", |
| 96 | "--no-privileges", |
| 97 | "--no-password", |
| 98 | `--dbname=${connection.conninfo}` |
| 99 | ], { |
| 100 | env: { PATH: process.env.PATH, PGPASSWORD: connection.password }, |
| 101 | extendEnv: false |
| 102 | }).pipe(spawner.string) |
| 103 | |
| 104 | return dump.replace(/^--.*$/gm, "") |
| 105 | .replace(/^SET .*$/gm, "") |
| 106 | .replace(/^SELECT pg_catalog\..*$/gm, "") |
| 107 | .replace(/\n{2,}/gm, "\n\n") |
| 108 | .trim() |
| 109 | }) |
| 110 | |
| 111 | const pgDumpAll = Effect.gen(function*() { |
| 112 | const sql = yield* PgClient |
| 113 | const connection = yield* dumpConnection(sql.config) |
| 114 | const [schema, migrations] = yield* Effect.all([ |
| 115 | pgDump(connection, ["--schema-only"]), |
| 116 | pgDump(connection, ["--column-inserts", "--data-only", `--table=${table}`]) |
| 117 | ], { concurrency: 2 }) |
| 118 | return schema + "\n\n" + migrations |
| 119 | }).pipe(Effect.scoped) |
| 120 | |
| 121 | const pgDumpFile = Effect.fnUntraced( |
| 122 | function*(path: string) { |
| 123 | const fs = yield* FileSystem.FileSystem |
| 124 | const path_ = yield* Path.Path |
| 125 | const dump = yield* pgDumpAll |
| 126 | yield* fs.makeDirectory(path_.dirname(path), { recursive: true }) |
| 127 | yield* fs.writeFileString(path, dump) |
| 128 | }, |
| 129 | Effect.mapError((error) => new Migrator.MigrationError({ kind: "Failed", message: error.message, cause: error })) |
| 130 | ) |
| 131 | |
| 132 | return pgDumpFile(path) |
| 133 | } |
| 134 | }) |
| 135 | |
| 136 | interface DumpConnection { |
| 137 | readonly conninfo: string |
| 138 | readonly password: string | undefined |
| 139 | } |
| 140 | |
| 141 | const unsupported = (reason: string) => |
| 142 | Effect.fail( |
| 143 | new Migrator.MigrationError({ |
| 144 | kind: "Failed", |
| 145 | message: `pg_dump cannot connect the same way as PgClient: ${reason}` |
| 146 | }) |
| 147 | ) |
| 148 | |
| 149 | // Builds the libpq connection for pg_dump from the client's resolved config. |
| 150 | // The password is passed through PGPASSWORD, never in argv. |
| 151 | const dumpConnection = Effect.fnUntraced(function*(options: PgClientConfig) { |
| 152 | const config = yield* resolveConfig(options) |
| 153 | if (config.stream !== undefined) { |
| 154 | return yield* unsupported("custom `stream` connections have no libpq equivalent") |
| 155 | } |
| 156 | let host = config.host |
| 157 | let port = config.port |
| 158 | if (config.path !== undefined) { |
| 159 | // libpq takes the socket directory and derives the file name from the port |
| 160 | const socket = /^(.*)\/\.s\.PGSQL\.(\d+)$/.exec(config.path) |
| 161 | if (socket === null) { |
| 162 | return yield* unsupported(`the socket path "${config.path}" is not named .s.PGSQL.<port>`) |
| 163 | } |
| 164 | host = socket[1] || "/" |
| 165 | port = Number(socket[2]) |
| 166 | } |
| 167 | const startup = config.startupParameters |
| 168 | const connectTimeout = Duration.isFinite(config.connectTimeout) |
| 169 | ? String(Math.max(1, Math.ceil(Duration.toSeconds(config.connectTimeout)))) |
| 170 | : undefined |
| 171 | return { |
| 172 | conninfo: conninfo({ |
| 173 | host, |
| 174 | port: String(port), |
| 175 | user: config.username, |
| 176 | dbname: startup.database, |
| 177 | application_name: startup.application_name, |
| 178 | options: startup.options, |
| 179 | connect_timeout: connectTimeout, |
| 180 | ...yield* tlsParameters(config) |
| 181 | }), |
| 182 | password: yield* Password.resolve(config.password) |
| 183 | } satisfies DumpConnection |
| 184 | }) |
| 185 | |
| 186 | const conninfo = (parameters: Record<string, string | undefined>): string => |
| 187 | Object.entries(parameters) |
| 188 | .flatMap(([key, value]) => value === undefined ? [] : [`${key}='${value.replace(/[\\']/g, "\\$&")}'`]) |
| 189 | .join(" ") |
| 190 | |
| 191 | const supportedTlsOptions = new Set(["ca", "cert", "key", "rejectUnauthorized", "servername"]) |
| 192 | |
| 193 | // Maps the client's TLS behaviour to libpq. Certificates are written to a |
| 194 | // scoped temporary directory because libpq only reads them from files. Unused |
| 195 | // file parameters point at missing files inside that directory so libpq does |
| 196 | // not fall back to ~/.postgresql. |
| 197 | const tlsParameters = Effect.fnUntraced(function*(config: ResolvedConfig) { |
| 198 | if (config.ssl === false) return { sslmode: "disable" } |
| 199 | if (config.path !== undefined) { |
| 200 | // The server refuses TLS on Unix sockets, so optional TLS is plaintext |
| 201 | if (config.sslOptional) return { sslmode: "disable" } |
| 202 | return yield* unsupported("libpq does not use TLS over Unix sockets") |
| 203 | } |
| 204 | const ssl: Tls.ConnectionOptions = typeof config.ssl === "object" ? config.ssl : {} |
| 205 | const options = Object.keys(ssl).filter((key) => |
| 206 | (ssl as Record<string, unknown>)[key] !== undefined && !supportedTlsOptions.has(key) |
| 207 | ) |
| 208 | if (options.length > 0) { |
| 209 | return yield* unsupported(`the ssl options ${options.join(", ")} have no libpq equivalent`) |
| 210 | } |
| 211 | if (ssl.servername !== undefined && ssl.servername !== config.host) { |
| 212 | return yield* unsupported("libpq verifies the host, not a separate ssl servername") |
| 213 | } |
| 214 | if ((ssl.cert === undefined) !== (ssl.key === undefined)) { |
| 215 | return yield* unsupported("ssl cert and key must be set together") |
| 216 | } |
| 217 | if (ssl.key !== undefined && typeof ssl.key !== "string" && !(ssl.key instanceof Uint8Array)) { |
| 218 | return yield* unsupported("ssl key must be a single PEM string or Buffer") |
| 219 | } |
| 220 | // Optional TLS still verifies, and libpq cannot verify with a plaintext fallback |
| 221 | const verify = ssl.rejectUnauthorized !== false |
| 222 | if (verify && ssl.ca === undefined && typeof Tls.getCACertificates !== "function") { |
| 223 | return yield* unsupported( |
| 224 | "this Node.js version cannot report its default CAs (tls.getCACertificates needs Node.js 22.15 / 23.10), set ssl.ca" |
| 225 | ) |
| 226 | } |
| 227 | const directory = yield* Effect.acquireRelease( |
| 228 | Effect.tryPromise({ |
| 229 | try: () => NodeFs.mkdtemp(NodePath.join(Os.tmpdir(), "effect-sql-pg-dump-")), |
| 230 | catch: (cause) => |
| 231 | new Migrator.MigrationError({ kind: "Failed", message: "Could not create pg_dump TLS directory", cause }) |
| 232 | }), |
| 233 | (directory) => Effect.promise(() => NodeFs.rm(directory, { recursive: true, force: true })) |
| 234 | ) |
| 235 | // Without a PEM the parameter points at a missing file, so libpq does not |
| 236 | // fall back to ~/.postgresql |
| 237 | const file = (name: string, pem: Pem | undefined) => { |
| 238 | const path = NodePath.join(directory, pem === undefined ? "none" : name) |
| 239 | if (pem === undefined) return Effect.succeed(path) |
| 240 | return Effect.tryPromise({ |
| 241 | try: () => NodeFs.writeFile(path, toPem(pem), { mode: 0o600 }), |
| 242 | catch: (cause) => new Migrator.MigrationError({ kind: "Failed", message: `Could not write ${name}`, cause }) |
| 243 | }).pipe(Effect.as(path)) |
| 244 | } |
| 245 | return { |
| 246 | sslmode: verify ? "verify-full" : "require", |
| 247 | // Node replaces its default trust store when `ca` is set. The default |
| 248 | // store includes NODE_EXTRA_CA_CERTS and --use-system-ca. |
| 249 | sslrootcert: yield* file("root.crt", verify ? ssl.ca ?? Tls.getCACertificates("default") : undefined), |
| 250 | sslcert: yield* file("client.crt", ssl.cert), |
| 251 | sslkey: yield* file("client.key", ssl.key) |
| 252 | } |
| 253 | }) |
| 254 | |
| 255 | type Pem = string | Uint8Array | ReadonlyArray<string | Uint8Array> |
| 256 | |
| 257 | const toPem = (value: Pem): string => |
| 258 | (Array.isArray(value) ? value : [value]).map((pem) => Buffer.from(pem).toString().trim()).join("\n") + "\n" |
| 259 | |
| 260 | /** |
| 261 | * Creates a layer that runs PostgreSQL migrations during layer construction, including `pg_dump`-based schema dump support when requested. |
| 262 | * |
| 263 | * @stability unstable |
| 264 | * @category layers |
| 265 | * @since 4.0.0 |
| 266 | */ |
| 267 | export const layer = <R>( |
| 268 | options: Migrator.MigratorOptions<R> |
| 269 | ): Layer.Layer< |
| 270 | never, |
| 271 | Migrator.MigrationError | SqlError, |
| 272 | | SqlClient |
| 273 | | PgClient |
| 274 | | ChildProcessSpawner.ChildProcessSpawner |
| 275 | | FileSystem.FileSystem |
| 276 | | Path.Path |
| 277 | | R |
| 278 | > => Layer.effectDiscard(run(options)) |