@akal/supaforge 0.0.34 → 0.0.35

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (49) hide show
  1. package/README.md +28 -12
  2. package/dist/base-command.d.ts +1 -1
  3. package/dist/base-command.js +2 -2
  4. package/dist/{branch-C4ndfoj5.d.ts → branch-BppjQBv_.d.ts} +1 -1
  5. package/dist/{chunk-PYAGSMFB.js → chunk-44UVQJV2.js} +146 -13
  6. package/dist/{chunk-OB5GP7UB.js → chunk-4AGJRRBT.js} +376 -32
  7. package/dist/{chunk-MG3SFV5J.js → chunk-4M6OQLPO.js} +1 -1
  8. package/dist/{chunk-TPX2MAO4.js → chunk-5Q6LSLA3.js} +53 -4
  9. package/dist/{chunk-F46FFUKC.js → chunk-7N63OPFN.js} +20 -12
  10. package/dist/chunk-AGONS5JJ.js +242 -0
  11. package/dist/{chunk-7DL63NWP.js → chunk-H2D3YSKM.js} +6 -2
  12. package/dist/{chunk-3WKWPSFN.js → chunk-NEM5AEPQ.js} +171 -21
  13. package/dist/{chunk-6ERVCWLY.js → chunk-NX2KKUS7.js} +6 -6
  14. package/dist/{chunk-S5L4A3UR.js → chunk-O5ERC2SE.js} +2 -2
  15. package/dist/{chunk-ICSCHS72.js → chunk-SM7HP6EP.js} +10 -180
  16. package/dist/{chunk-N5VNNOA2.js → chunk-T7GMPGUO.js} +578 -16
  17. package/dist/{chunk-DQJSSTIJ.js → chunk-WNTCZM2J.js} +4 -476
  18. package/dist/{chunk-5STH2A6K.js → chunk-XLZCX6R2.js} +2 -2
  19. package/dist/{chunk-EFKQOQGG.js → chunk-YWERIWFD.js} +6 -4
  20. package/dist/{chunk-V2SBZERO.js → chunk-YZM76W22.js} +3 -3
  21. package/dist/commands/clone.d.ts +2 -2
  22. package/dist/commands/clone.js +7 -6
  23. package/dist/commands/diff.d.ts +24 -22
  24. package/dist/commands/diff.js +11 -11
  25. package/dist/commands/hukam.d.ts +2 -3
  26. package/dist/commands/hukam.js +11 -11
  27. package/dist/commands/init.d.ts +1 -1
  28. package/dist/commands/mcp.js +8 -8
  29. package/dist/commands/migrate/baseline.d.ts +1 -1
  30. package/dist/commands/migrate/baseline.js +3 -3
  31. package/dist/commands/migrate/create.d.ts +1 -1
  32. package/dist/commands/migrate/create.js +12 -7
  33. package/dist/commands/migrate/list.d.ts +1 -1
  34. package/dist/commands/migrate/list.js +3 -3
  35. package/dist/commands/migrate/run.d.ts +4 -1
  36. package/dist/commands/migrate/run.js +7 -6
  37. package/dist/commands/report.d.ts +1 -1
  38. package/dist/commands/report.js +2 -2
  39. package/dist/commands/restore.d.ts +1 -1
  40. package/dist/commands/restore.js +10 -10
  41. package/dist/commands/snapshot.d.ts +1 -1
  42. package/dist/commands/snapshot.js +5 -5
  43. package/dist/commands/sync.d.ts +2 -3
  44. package/dist/commands/sync.js +11 -11
  45. package/dist/{config-CTbeRlJk.d.ts → config-l3ggjw9r.d.ts} +2 -0
  46. package/dist/index.d.ts +21 -4
  47. package/dist/index.js +13 -13
  48. package/package.json +2 -2
  49. package/dist/chunk-DQQ5E563.js +0 -64
package/README.md CHANGED
@@ -9,13 +9,16 @@ order, in one transaction, and can be proved on a throwaway copy before
9
9
  anything changes. With a single project, it snapshots, restores and clones it.
10
10
 
11
11
  - **The whole project.** It covers schema, RLS, storage, auth, Edge Functions,
12
- cron, webhooks, Realtime, Vault, extensions, grants, reference data and
13
- migration history.
12
+ cron, webhooks, Realtime, queues, partition sets, Vault, extensions, grants,
13
+ reference data and migration history.
14
14
  - **Safe by default.** Every write needs `--apply`, and anything that loses
15
15
  data or opens up access also needs `--allow-destructive`. A failed apply
16
16
  leaves the target exactly as it was.
17
+ - **Production-aware.** Each fix says what it does to a live database: the
18
+ lock it holds and on which table, whether it may rewrite the table or scan
19
+ every row, whether it can't run in a transaction.
17
20
  - **Provable.** `--prove` rehearses the migration and refuses to apply one
18
- that wouldn't reproduce the source.
21
+ that wouldn't reproduce the source or would lose rows.
19
22
  - **Anywhere.** It works with Supabase Cloud, self-hosted stacks, plain
20
23
  PostgreSQL targets, CI pipelines and AI agents (MCP).
21
24
 
@@ -63,6 +66,8 @@ Docker image needs nothing at all, and carries the PostgreSQL client tools
63
66
  | Storage | Buckets and their policies (objects are never copied) | API and SQL |
64
67
  | Auth config | Management API, or GoTrue on self-hosted | API (hosted) |
65
68
  | Cron jobs | `cron.job` | SQL |
69
+ | Queues | Supabase Queues (`pgmq.meta`), created and dropped through pgmq | SQL |
70
+ | Partition sets | pg_partman registrations (`part_config`), made with `create_parent` | SQL |
66
71
  | Webhooks | Triggers calling `supabase_functions.http_request` | SQL |
67
72
  | Realtime | Publications, and policies on `realtime.messages` | SQL |
68
73
  | Vault | Secret names and descriptions (values can't be read) | Command to run |
@@ -71,10 +76,17 @@ Docker image needs nothing at all, and carries the PostgreSQL client tools
71
76
  | Roles and grants | Custom roles, and grants on tables, views, sequences and functions, including `anon`, `authenticated`, `service_role` | SQL |
72
77
 
73
78
  The schema check covers tables, columns, keys, indexes, partitions, views,
74
- materialized views, functions, triggers, sequences, enums, composite types,
75
- domains, policies, extensions and comments. It runs in every schema except
76
- Supabase's own (`auth`, `storage`, and so on) and those in `ignoreSchemas`.
77
- Objects owned by an extension belong to it and aren't compared.
79
+ materialized views, functions, aggregates, triggers, event triggers, rules,
80
+ sequences, enums, composite and range types, domains, casts, extended
81
+ statistics, text search configurations and dictionaries, foreign servers,
82
+ user mappings and foreign tables, policies, default privileges, replica
83
+ identity, statistics targets, extensions and comments. A renamed column,
84
+ table or sequence is renamed, keeping its rows, rather than dropped and
85
+ created again. It runs in every schema except Supabase's own (`auth`,
86
+ `storage`, and so on) and those in `ignoreSchemas`. Objects owned by an
87
+ extension belong to it and aren't compared. Objects of a kind it doesn't
88
+ compare, such as operator classes, are named under the check so you can look
89
+ at them by hand; they aren't counted as drift.
78
90
 
79
91
  A check that can't run, for example without API credentials, says so and why.
80
92
  It's never reported as a clean pass.
@@ -109,6 +121,7 @@ Useful `diff` flags:
109
121
  | `--only=<id,...>` | Apply only these findings (ids come from `--json`, globs allowed) |
110
122
  | `--dry-run` | Print the fixes in the order they'd run, run nothing |
111
123
  | `--prove` | Rehearse the fixes on a throwaway copy first |
124
+ | `--source-dir <dir>` | Compare a directory of schema files (such as `supabase/schemas`) with the target instead of a source database |
112
125
  | `--allow-destructive` | Also apply drops and deletes |
113
126
  | `--apply-posture` | Also apply the target-only checks' fixes |
114
127
  | `--no-transaction` | Apply fix by fix, keeping what works |
@@ -129,11 +142,13 @@ Useful `diff` flags:
129
142
  is unchanged. A fix the target can't hold, because it needs an extension or
130
143
  a Supabase schema the target lacks, is skipped with the reason, and the rest
131
144
  still applies.
132
- - **`--prove`.** The fixes are replayed on a structure-only copy of the target,
133
- made on the target's own server, the way the apply will run them. Nothing is
134
- applied unless the result matches the source, and nothing is applied if the
135
- proof can't run. Changes a copy can't hold, such as cron jobs (pg_cron lives
136
- in one database per server), are listed as not proved.
145
+ - **`--prove`.** The fixes are replayed on a copy of the target's structure,
146
+ made on the target's own server, the way the apply will run them, with a
147
+ sample of each table's rows. Nothing is applied unless the result matches
148
+ the source and the rows survive, and nothing is applied if the proof can't
149
+ run. It also names the tables the fixes rewrite. Changes a copy can't hold,
150
+ such as cron jobs (pg_cron lives in one database per server), are listed as
151
+ not proved.
137
152
 
138
153
  ```bash
139
154
  supaforge diff --dry-run # the plan, in order
@@ -260,6 +275,7 @@ supaforge migrate run --env=prod --apply
260
275
  | `SUPAFORGE_DBDIFF_MEMORY` | `1G` | Memory limit for `@dbdiff/cli` (`2G`, `-1` for none) |
261
276
  | `SUPAFORGE_CONNECT_TIMEOUT` | `15` | Seconds to wait for a connection |
262
277
  | `SUPAFORGE_CHECK_CONCURRENCY` | `4` | Checks run at once. Lower it behind a tight pooler |
278
+ | `SUPAFORGE_PROVE_ROWS` | `1000` | Rows of each table `--prove` copies to check they survive; `0` checks structure only |
263
279
  | `SUPAFORGE_PG_BIN` | — | A directory of PostgreSQL client tools (`pg_dump`, `psql`), used ahead of `PATH` — for a server newer than the tools on `PATH` |
264
280
 
265
281
  ## Self-hosted Supabase
@@ -1,5 +1,5 @@
1
1
  import { Command } from '@oclif/core';
2
- import { S as SupaForgeConfig, E as EnvironmentConfig } from './config-CTbeRlJk.js';
2
+ import { S as SupaForgeConfig, E as EnvironmentConfig } from './config-l3ggjw9r.js';
3
3
 
4
4
  /** Outcome of a single preflight check (DB connectivity or custom). */
5
5
  interface CheckEntry {
@@ -1,7 +1,7 @@
1
1
  import {
2
2
  BaseCommand
3
- } from "./chunk-5STH2A6K.js";
4
- import "./chunk-MG3SFV5J.js";
3
+ } from "./chunk-XLZCX6R2.js";
4
+ import "./chunk-4M6OQLPO.js";
5
5
  import "./chunk-GQPGH6YR.js";
6
6
  import "./chunk-KNXHLVF7.js";
7
7
  export {
@@ -1,4 +1,4 @@
1
- import { E as EnvironmentConfig, S as SupaForgeConfig } from './config-CTbeRlJk.js';
1
+ import { E as EnvironmentConfig, S as SupaForgeConfig } from './config-l3ggjw9r.js';
2
2
 
3
3
  /** Prefix for branch database names created by SupaForge. */
4
4
  declare const BRANCH_DB_PREFIX = "supaforge_branch_";
@@ -6,18 +6,22 @@ import {
6
6
  formatSkips,
7
7
  renderDetailed,
8
8
  renderSummary
9
- } from "./chunk-7DL63NWP.js";
9
+ } from "./chunk-H2D3YSKM.js";
10
10
  import {
11
11
  createDefaultRegistry,
12
12
  scan,
13
13
  summarizeByKind
14
- } from "./chunk-OB5GP7UB.js";
14
+ } from "./chunk-4AGJRRBT.js";
15
15
  import {
16
16
  comparedSchemas,
17
+ copyStructure,
18
+ dropDatabase,
17
19
  proofScope,
18
20
  proveConvergence,
19
- residualHeldBack
20
- } from "./chunk-3WKWPSFN.js";
21
+ psqlBeside,
22
+ residualHeldBack,
23
+ withDatabase
24
+ } from "./chunk-NEM5AEPQ.js";
21
25
  import {
22
26
  CHECK_META,
23
27
  CHECK_NAMES,
@@ -26,30 +30,42 @@ import {
26
30
  planWork,
27
31
  promote,
28
32
  resolveTableFilter
29
- } from "./chunk-DQJSSTIJ.js";
33
+ } from "./chunk-T7GMPGUO.js";
34
+ import {
35
+ isCommentOnly,
36
+ splitSqlStatements
37
+ } from "./chunk-WK5YTINL.js";
30
38
  import {
31
39
  renderTip
32
40
  } from "./chunk-ZI435CAU.js";
33
41
  import {
34
42
  BaseCommand
35
- } from "./chunk-5STH2A6K.js";
43
+ } from "./chunk-XLZCX6R2.js";
36
44
  import {
37
45
  isCloneDatabase,
38
46
  sourceLooksLikeCloneOf
39
- } from "./chunk-EFKQOQGG.js";
47
+ } from "./chunk-YWERIWFD.js";
40
48
  import {
41
- parseFlagList
42
- } from "./chunk-DQQ5E563.js";
49
+ describeMissingPgDump,
50
+ getServerMajorVersion,
51
+ parseFlagList,
52
+ resolvePgDumpPath
53
+ } from "./chunk-AGONS5JJ.js";
43
54
  import {
44
- Preflight
45
- } from "./chunk-MG3SFV5J.js";
55
+ Preflight,
56
+ pgQuery,
57
+ quoteName
58
+ } from "./chunk-4M6OQLPO.js";
46
59
  import {
47
60
  CLONE_SKIP_FLAGS,
48
61
  DEFAULT_IGNORE_SCHEMAS,
62
+ DiagnosticError,
63
+ SUPABASE_PLATFORM_SCHEMAS,
49
64
  bold,
50
65
  cmd,
51
66
  describeFailure,
52
67
  dim,
68
+ errMsg,
53
69
  ok,
54
70
  redactUrls,
55
71
  schemaDiffIgnores,
@@ -99,6 +115,7 @@ function formatCiSummary(result) {
99
115
  const warningIssues = [];
100
116
  const errors = [];
101
117
  const skipped = [];
118
+ const notices = [];
102
119
  for (const check of result.checks ?? []) {
103
120
  if (check?.status === "error") {
104
121
  errors.push({ check: check.check, message: check.error ?? "Check failed with no error message" });
@@ -106,6 +123,7 @@ function formatCiSummary(result) {
106
123
  if (check?.status === "skipped") {
107
124
  skipped.push({ check: check.check, reason: check.skipReason ?? "no reason given" });
108
125
  }
126
+ for (const notice of check?.notices ?? []) notices.push({ check: check.check, notice });
109
127
  for (const issue of check?.issues ?? []) {
110
128
  const entry = { check: check.check, id: issue.id, title: issue.title };
111
129
  if (issue.severity === "critical") {
@@ -123,12 +141,93 @@ function formatCiSummary(result) {
123
141
  errors,
124
142
  skipped,
125
143
  coverage: coverage(result),
144
+ notices,
126
145
  criticalIssues,
127
146
  warningIssues
128
147
  };
129
148
  }
130
149
 
150
+ // src/schema-dir.ts
151
+ import { randomBytes } from "crypto";
152
+ import { readdir, readFile } from "fs/promises";
153
+ import { join, relative } from "path";
154
+ async function openSchemaDir(dir, targetUrl) {
155
+ const files = await sqlFiles(dir);
156
+ if (files.length === 0) throw new DiagnosticError(`--source-dir: no .sql files in ${dir}`);
157
+ const serverMajor = await getServerMajorVersion(targetUrl);
158
+ const resolved = await resolvePgDumpPath(serverMajor);
159
+ if (!resolved) throw new DiagnosticError(`--source-dir needs pg_dump to copy the target's platform schemas: ${await describeMissingPgDump(serverMajor)}`);
160
+ const tools = { pgDump: resolved.path, psql: psqlBeside(resolved.path), clientMajor: resolved.major, serverMajor };
161
+ const name = `supaforge_schema_${randomBytes(4).toString("hex")}`;
162
+ const adminUrl = withDatabase(targetUrl, "postgres");
163
+ const url = withDatabase(targetUrl, name);
164
+ try {
165
+ await pgQuery(adminUrl, `CREATE DATABASE ${quoteName(name)}`);
166
+ } catch (err) {
167
+ throw new DiagnosticError(`--source-dir: could not create a throwaway database on the target's server: ${errMsg(err)}`);
168
+ }
169
+ const close = () => dropDatabase(adminUrl, name);
170
+ try {
171
+ const present = new Set((await pgQuery(targetUrl, "SELECT nspname FROM pg_namespace")).map((r) => r.nspname));
172
+ const platform = SUPABASE_PLATFORM_SCHEMAS.filter((s) => present.has(s) && s !== "pg_catalog" && s !== "information_schema");
173
+ if (platform.length > 0) await copyStructure(targetUrl, url, platform, tools);
174
+ const statements = await loadStatements(url, files);
175
+ return { url, statements, files: files.length, close, unavailable: await unavailableExtensions(targetUrl, url) };
176
+ } catch (err) {
177
+ await close();
178
+ throw err;
179
+ }
180
+ }
181
+ async function sqlFiles(dir) {
182
+ const entries = await readdir(dir, { recursive: true, withFileTypes: true });
183
+ return entries.filter((e) => e.isFile() && e.name.endsWith(".sql")).map((e) => {
184
+ const path = join(e.parentPath ?? e.path, e.name);
185
+ return { path, name: relative(dir, path) };
186
+ }).sort((a, b) => a.name.localeCompare(b.name));
187
+ }
188
+ async function loadStatements(url, files) {
189
+ let pending = [];
190
+ for (const f of files) {
191
+ for (const sql of splitSqlStatements(await readFile(f.path, "utf8"))) {
192
+ if (!isCommentOnly(sql)) pending.push({ file: f.name, sql });
193
+ }
194
+ }
195
+ const total = pending.length;
196
+ for (; ; ) {
197
+ const failed = [];
198
+ for (const p of pending) {
199
+ try {
200
+ await pgQuery(url, p.sql);
201
+ } catch (err) {
202
+ failed.push({ ...p, error: errMsg(err) });
203
+ }
204
+ }
205
+ if (failed.length === 0) return total;
206
+ if (failed.length === pending.length) {
207
+ const first = failed[0];
208
+ throw new DiagnosticError(
209
+ `--source-dir: ${failed.length} statement(s) could not be loaded. First, in ${first.file}: ${first.error}
210
+ ${first.sql.slice(0, 200).replace(/\s+/g, " ")}`
211
+ );
212
+ }
213
+ pending = failed;
214
+ }
215
+ }
216
+ async function unavailableExtensions(targetUrl, copyUrl) {
217
+ const sql = `SELECT e.extname AS name,
218
+ ARRAY(SELECT DISTINCT n.nspname FROM pg_depend d JOIN pg_class c ON c.oid = d.objid
219
+ JOIN pg_namespace n ON n.oid = c.relnamespace
220
+ WHERE d.classid = 'pg_class'::regclass AND d.refobjid = e.oid AND d.deptype = 'e')::text[] AS schemas
221
+ FROM pg_extension e`;
222
+ const [target, copy] = await Promise.all([targetUrl, copyUrl].map((url) => pgQuery(url, sql)));
223
+ const have = new Set(copy.map((e) => e.name));
224
+ const missing = target.filter((e) => !have.has(e.name));
225
+ return { extensions: missing.map((e) => e.name), schemas: [...new Set(missing.flatMap((e) => e.schemas))] };
226
+ }
227
+
131
228
  // src/commands/diff.ts
229
+ var SCHEMA_FILES_ENV = "schema files";
230
+ var SCHEMA_FILE_CHECKS = ["schema", "rls", "extensions"];
132
231
  function describeCheckOutcome(status, issueCount, skipReason) {
133
232
  if (status === "error") return { glyph: warn("\u2717"), text: warn("error") };
134
233
  if (status === "skipped") {
@@ -193,6 +292,10 @@ var Diff = class _Diff extends BaseCommand {
193
292
  { name: "SUPAFORGE_DBDIFF_MEMORY", description: "PHP memory limit for @dbdiff/cli \u2014 512M, 2G, or -1 for unlimited (default dbdiff's own 1G)." }
194
293
  ];
195
294
  static flags = {
295
+ "source-dir": Flags.string({
296
+ description: "Compare a directory of schema files (such as supabase/schemas) with the target, instead of a source database. They are loaded into a throwaway database on the target's server.",
297
+ exclusive: ["source"]
298
+ }),
196
299
  check: Flags.string({
197
300
  char: "l",
198
301
  description: "Limit to a specific check",
@@ -322,9 +425,30 @@ ${warn(`${result.errors.length} error(s):`)}`);
322
425
  `);
323
426
  }
324
427
  const config = await this.loadConfigOrFail();
428
+ if (flags["source-dir"]) {
429
+ const { envName: targetName } = this.resolveEnv(config, flags.target ?? config.target);
430
+ const loaded = await openSchemaDir(flags["source-dir"], config.environments[targetName].dbUrl);
431
+ this.log(` ${dim(`Loaded ${loaded.statements} statement(s) from ${loaded.files} file(s) in ${flags["source-dir"]}.`)}
432
+ `);
433
+ config.environments = { ...config.environments, [SCHEMA_FILES_ENV]: { dbUrl: loaded.url } };
434
+ config.ignoreSchemas = [...config.ignoreSchemas ?? DEFAULT_IGNORE_SCHEMAS, ...loaded.unavailable.schemas];
435
+ config.ignoreExtensions = [...config.ignoreExtensions ?? [], ...loaded.unavailable.extensions];
436
+ config.source = SCHEMA_FILES_ENV;
437
+ config.target = targetName;
438
+ try {
439
+ await this.compare(flags, config, flags.check ? void 0 : SCHEMA_FILE_CHECKS);
440
+ } finally {
441
+ await loaded.close();
442
+ }
443
+ return;
444
+ }
325
445
  this.validateDualEnvConfig(config, flags.source, flags.target);
446
+ await this.compare(flags, config);
447
+ }
448
+ /** The comparison itself, between the config's source and target. */
449
+ async compare(flags, config, defaultChecks) {
326
450
  const registry = createDefaultRegistry({ includeFiles: flags["include-files"] });
327
- const checks = flags.check ? [flags.check] : void 0;
451
+ const checks = flags.check ? [flags.check] : defaultChecks;
328
452
  const skip = flags.skip?.length ? flags.skip : void 0;
329
453
  const tableFilter = resolveTableFilter(config, {
330
454
  tables: flags.tables,
@@ -448,6 +572,15 @@ ${warn(`${result.errors.length} error(s):`)}`);
448
572
  `);
449
573
  }
450
574
  }
575
+ if (proof.data && !proof.skipped) {
576
+ const { sampled, unchecked: unchecked2, rewritten } = proof.data;
577
+ if (sampled.length > 0) this.log(` ${ok("Rows kept")} in the ${sampled.length} table(s) sampled.`);
578
+ if (rewritten.length > 0) {
579
+ this.log(` ${warn("Rewritten")} on the copy \u2014 a long lock on the real target: ${rewritten.join(", ")}`);
580
+ }
581
+ if (unchecked2.length > 0) this.log(` ${dim(`Rows not checked (the sample would not load): ${unchecked2.join(", ")}`)}`);
582
+ this.log("");
583
+ }
451
584
  }
452
585
  const result2 = await promote({
453
586
  dbUrl: targetEnv.dbUrl,
@@ -637,4 +770,4 @@ export {
637
770
  inertApplyFlags,
638
771
  Diff
639
772
  };
640
- //# sourceMappingURL=chunk-PYAGSMFB.js.map
773
+ //# sourceMappingURL=chunk-44UVQJV2.js.map