@devries-cameron20 / t3code Mirror · read-only
Fork 0

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

main
ts 278 lines 10.7 KB
Raw
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))