better-supabase 0.12.0 → 0.13.0

package/dist/cli/metadata-CTStQPfV.js

@@ -0,0 +1,144 @@
+import { n as CliError, r as errorText } from "./errors-BTe6A15O.js";
+import { i as readStdin } from "./io-DH1kcmmP.js";
+import { a as parseMetadataDocument, t as MetadataRejectedError } from "./typegen-F9GEjpvD.js";
+import { i as metaPaths } from "./emit-CJKf47Bi.js";
+import { b as render, i as generationNotices, n as runGen, o as fromMetadata, r as UNFORMATTED, t as refuseRowConditionedBuckets } from "./run-BXhJoghZ.js";
+import { basename, join, relative, resolve, sep } from "node:path";
+import { readFile } from "node:fs/promises";
+import { jsonSchema, standardSchema, valibot, zod } from "better-supabase/config";
+//#region src/cli/gen/metadata.ts
+/** The files `gen --metadata` can write to stdout. */
+const EMITS = [
+	"schema",
+	"types",
+	"zod",
+	"valibot",
+	"json-schema",
+	"standard-schema"
+];
+const isEmit = (value) => EMITS.some((emit) => emit === value);
+/** The configured generator for an `--emit` target, or one with its defaults. */
+function emitGenerator(config, emit) {
+	const configured = config.generators.find((generator) => generator.name === emit);
+	switch (emit) {
+		case "schema":
+		case "types": return;
+		case "zod": return configured ?? zod();
+		case "valibot": return configured ?? valibot();
+		case "json-schema": return configured ?? jsonSchema();
+		case "standard-schema": return configured ?? standardSchema();
+		default: throw new Error(`unknown --emit ${String(emit)}`);
+	}
+}
+/**
+* The one file `gen --metadata` prints: the `defineSchema` module with its
+* metadata inlined, `database.types.ts`, or one generator's output.
+*/
+async function renderEmit(config, snapshot, emit) {
+	const generator = emitGenerator(config, emit);
+	const { files, warnings } = await render({
+		...config,
+		generators: generator ? [generator] : []
+	}, snapshot, { inlineMeta: emit === "schema" });
+	const path = emit === "schema" ? config.output : emit === "types" ? config.databaseTypesOutput : void 0;
+	const own = /* @__PURE__ */ new Set([
+		config.databaseTypesOutput,
+		config.output,
+		...Object.values(metaPaths(config.output))
+	]);
+	const picked = path === void 0 ? files.filter((file) => !own.has(file.path)) : files.filter((file) => file.path === path);
+	const [file] = picked;
+	if (!file || picked.length > 1) throw new CliError("usage", `--emit ${emit} expects one file, and the generator wrote ${picked.length}. Pass --out-dir <dir> to write them all.`);
+	return {
+		files: picked,
+		warnings,
+		contents: file.contents
+	};
+}
+/**
+* Reads `--metadata <path|->` (a file relative to `cwd`, or stdin for `-`) into
+* a snapshot. Throws `MetadataRejectedError` for a document that can't be read
+* or that `parseMetadataDocument` refuses.
+*/
+async function readMetadataSnapshot(source, cwd, io) {
+	if (source === "-") {
+		const piped = await readStdin(io, "--metadata -");
+		return fromMetadata(await parseMetadataDocument(piped));
+	}
+	let text;
+	try {
+		text = await readFile(resolve(cwd, source), "utf-8");
+	} catch (cause) {
+		throw new MetadataRejectedError(`Could not read ${source}: ${errorText(cause)}`);
+	}
+	return fromMetadata(await parseMetadataDocument(text));
+}
+/**
+* Refuses `--metadata` next to `conflicting`, the passed flags that read the
+* schema from somewhere else.
+*/
+function refuseWithMetadata(conflicting) {
+	if (conflicting.length > 0) throw new CliError("usage", `--metadata reads the schema from the document, so it can't be combined with ${conflicting.join(", ")}`);
+}
+/**
+* Throws the usage error for flags that don't combine with `--metadata`, or
+* need it.
+*/
+function checkMetadataFlags(flags) {
+	if (flags.metadata === void 0) {
+		if (flags.emit !== void 0 || flags.out !== void 0) throw new CliError("usage", `${flags.emit === void 0 ? "--out-dir" : "--emit"} only applies with --metadata`);
+		return;
+	}
+	refuseWithMetadata(flags.conflicting);
+	const problem = flags.out !== void 0 && flags.emit !== void 0 ? "--emit picks the one file gen prints; --out-dir writes them all. Pass one of them." : flags.out === void 0 && flags.check ? "--check with --metadata needs --out-dir <dir>" : flags.out === void 0 && flags.json ? "--metadata prints the generated code on stdout, so --json has nothing to print. Pass --out-dir <dir> for the JSON summary." : void 0;
+	if (problem !== void 0) throw new CliError("usage", problem);
+}
+/**
+* `gen --metadata`: the out-of-process generator contract of
+* `@supabase/typegen`. Without `--out-dir` it prints one file on stdout and
+* everything else on stderr; with `--out-dir` it writes the usual files there.
+*/
+async function runMetadataGen(options) {
+	const { config, io } = options;
+	const emit = options.emit ?? "schema";
+	if (!isEmit(emit)) throw new CliError("invalid_value", `--emit must be one of ${EMITS.join(", ")}, got "${emit}"`);
+	let snapshot;
+	try {
+		snapshot = await readMetadataSnapshot(options.metadata, options.cwd, io);
+	} catch (cause) {
+		if (cause instanceof MetadataRejectedError) return {
+			code: 65,
+			errorCode: "invalid_input",
+			error: cause.message
+		};
+		throw cause;
+	}
+	if (options.out !== void 0) {
+		const dir = relative(config.root, resolve(options.cwd, options.out));
+		const into = (path) => join(dir, basename(path)).split(sep).join("/");
+		return runGen({
+			config: {
+				...config,
+				output: into(config.output),
+				databaseTypesOutput: into(config.databaseTypesOutput)
+			},
+			env: options.env,
+			check: options.check,
+			snapshot,
+			isolated: true,
+			...options.paint ? { paint: options.paint } : {}
+		});
+	}
+	const refused = refuseRowConditionedBuckets(config);
+	if (refused) return refused;
+	const { contents, warnings } = await renderEmit(config, snapshot, emit);
+	const notices = await generationNotices(snapshot, warnings);
+	const shown = emit === "types" ? notices : notices.filter((line) => line !== UNFORMATTED);
+	for (const line of shown) options.log.info(line);
+	return {
+		code: 0,
+		raw: contents
+	};
+}
+//#endregion
+export { runMetadataGen as a, refuseWithMetadata as i, checkMetadataFlags as n, readMetadataSnapshot as r, EMITS as t };

package/dist/cli/migration-safety-Dg1lxomi.js

@@ -0,0 +1,305 @@
+import { c as splitStatements } from "./shared-CAdIkTR7.js";
+import { join } from "node:path";
+import { readdir } from "node:fs/promises";
+//#region src/cli/doctor/migration-safety.ts
+const NAME = String.raw`(?:"[^"]+"|[\w$]+)`;
+const TABLE = String.raw`(${NAME}(?:\s*\.\s*${NAME})?)`;
+const CREATE_TABLE = new RegExp(String.raw`^create\s+(?:(?:global\s+|local\s+)?(?:temporary|temp|unlogged)\s+)?table\s+(?:if\s+not\s+exists\s+)?${TABLE}`, "iu");
+const ALTER_TABLE = new RegExp(String.raw`^alter\s+table\s+(?:if\s+exists\s+)?(?:only\s+)?${TABLE}`, "iu");
+const CREATE_INDEX = new RegExp(String.raw`^create\s+(?:unique\s+)?index\s+(concurrently\s+)?(?:if\s+not\s+exists\s+)?(?:${NAME}\s+)?on\s+(?:only\s+)?${TABLE}`, "iu");
+const ADD_CONSTRAINT = /\badd\s+(?:constraint\s+(?:"[^"]+"|[\w$]+)\s+)?(foreign\s+key|check)\b/iu;
+const NOT_VALID = /\bnot\s+valid\b/iu;
+const ALTER_TYPE = /\balter\s+(?:column\s+)?(?:"[^"]+"|[\w$]+)\s+(?:set\s+data\s+)?type\b/iu;
+const SET_NOT_NULL = /\bset\s+not\s+null\b/iu;
+const VALIDATE = /\bvalidate\s+constraint\b/iu;
+const ADD_COLUMN_DEFAULT = /\badd\s+(?:column\s+)?(?:if\s+not\s+exists\s+)?(?:"[^"]+"|[\w$]+)\s[^,]*?\bdefault\s+([^,]+)/giu;
+const VOLATILE = /\b(?:gen_random_uuid|uuid_generate_v[14]|clock_timestamp|timeofday|random|nextval|statement_timestamp)\s*\(/iu;
+const LOCK_TIMEOUT = /^set\s+(?:local\s+)?lock_timeout\b/iu;
+const EXCLUSIVE = /^(?:drop\s+table|truncate|vacuum\s+full|reindex\b(?!.*\bconcurrently\b)|lock\s+table|cluster\b)/iu;
+const DROP = /^drop\s+table\b|\bdrop\s+(?:column\s+)?(?!constraint\b|default\b|not\b|identity\b|expression\b)(?:if\s+exists\s+)?(?:"[^"]+"|[\w$]+)/iu;
+const RENAME = /\brename\s+(?!constraint\b)(?:column\s+)?(?:(?:"[^"]+"|[\w$]+)\s+)?to\b/iu;
+/**
+* `name` without quotes and with `public.` for an unqualified name,
+* lower-cased.
+*/
+function tableKey(name) {
+	const parts = name.split(".").map((part) => part.trim().replaceAll("\"", "").toLowerCase());
+	return parts.length === 1 ? `public.${parts[0] ?? ""}` : parts.join(".");
+}
+/** The version a migration file name or a `since` value starts with. */
+function migrationVersion(name) {
+	const base = name.slice(name.lastIndexOf("/") + 1);
+	return base.replace(/\.sql$/u, "").split("_")[0] ?? base;
+}
+/**
+* The newest migration under `<root>/<supabaseDir>/migrations`, which `init`
+* and `adopt` write to `doctor.migrationSafety.since` so the migrations that
+* already ran aren't checked offline.
+*/
+async function latestMigrationVersion(root, supabaseDir = "supabase") {
+	return (await readdir(join(root, supabaseDir, "migrations")).catch(() => [])).filter((name) => name.endsWith(".sql")).map(migrationVersion).toSorted().at(-1);
+}
+const statementsCache = /* @__PURE__ */ new WeakMap();
+function parse(file) {
+	let parsed = statementsCache.get(file);
+	if (parsed === void 0) {
+		const statements = splitStatements(file.text);
+		parsed = {
+			file,
+			statements,
+			created: new Set(statements.flatMap((statement) => {
+				const match = CREATE_TABLE.exec(statement.text);
+				return match?.[1] === void 0 ? [] : [tableKey(match[1])];
+			}))
+		};
+		statementsCache.set(file, parsed);
+	}
+	return parsed;
+}
+const pending = /* @__PURE__ */ new WeakMap();
+/**
+* The migrations to check: with a database, the ones it hasn't applied;
+* offline, the ones after `doctor.migrationSafety.since`, or the newest one
+* without it.
+*/
+function unappliedMigrations(context) {
+	let files = pending.get(context);
+	if (files === void 0) {
+		files = findUnapplied(context);
+		pending.set(context, files);
+	}
+	return files;
+}
+async function findUnapplied(context) {
+	const dir = `${context.configToml?.dir ?? "supabase"}/migrations/`;
+	const migrations = (context.sqlFiles ?? []).filter((file) => file.path.startsWith(dir)).toSorted((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+	const db = context.database;
+	if (db !== void 0 && !("skipped" in db)) try {
+		const rows = await db.query("select version from supabase_migrations.schema_migrations");
+		const applied = new Set(rows.map((row) => row.version));
+		return migrations.filter((file) => !applied.has(migrationVersion(file.path)));
+	} catch {}
+	const since = context.config.doctor.migrationSafety?.since;
+	if (since === void 0) return migrations.slice(-1);
+	const after = migrationVersion(since);
+	return migrations.filter((file) => migrationVersion(file.path) > after);
+}
+/** A rule that runs `check` on each statement of the unapplied migrations. */
+function perStatement(check) {
+	return async (context) => (await unappliedMigrations(context)).flatMap((file) => {
+		const parsed = parse(file);
+		return parsed.statements.flatMap((statement) => {
+			const message = check(parsed, statement);
+			return message === void 0 ? [] : [{
+				message: `${file.path}:${String(statement.line)}: ${message}`,
+				target: `${file.path}:${String(statement.line)}`,
+				location: {
+					file: file.path,
+					line: statement.line
+				}
+			}];
+		});
+	});
+}
+/**
+* The table an `alter table` statement changes, unless the same file created
+* it.
+*/
+function alteredTable(parsed, statement) {
+	const match = ALTER_TABLE.exec(statement.text);
+	const table = match?.[1] === void 0 ? void 0 : tableKey(match[1]);
+	return table === void 0 || parsed.created.has(table) ? void 0 : table;
+}
+const indexWithoutConcurrently = (parsed, statement) => {
+	const match = CREATE_INDEX.exec(statement.text);
+	if (match === null || match[1] !== void 0 || match[2] === void 0) return;
+	const table = tableKey(match[2]);
+	return parsed.created.has(table) ? void 0 : `creates an index on ${table} without concurrently, which blocks writes to it until the index is built.`;
+};
+const constraintWithoutNotValid = (parsed, statement) => {
+	const table = alteredTable(parsed, statement);
+	const kind = ADD_CONSTRAINT.exec(statement.text)?.[1];
+	if (table === void 0 || kind === void 0 || NOT_VALID.test(statement.text)) return;
+	return `adds a ${kind.toLowerCase().replace(/\s+/u, " ")} to ${table} without not valid, which scans every row while it holds a lock.`;
+};
+const rewriteOrScan = (parsed, statement) => {
+	const table = alteredTable(parsed, statement);
+	if (table === void 0) return;
+	if (ALTER_TYPE.test(statement.text)) return `changes a column type of ${table}, which can rewrite the table under an access exclusive lock.`;
+	const validated = parsed.statements.some((each) => each.line < statement.line && VALIDATE.test(each.text) && alteredTable(parsed, each) === table);
+	return SET_NOT_NULL.test(statement.text) && !validated ? `sets not null on a column of ${table}, which scans every row under an access exclusive lock.` : void 0;
+};
+const volatileDefault = (parsed, statement) => {
+	const table = alteredTable(parsed, statement);
+	if (table === void 0) return;
+	for (const match of statement.text.matchAll(ADD_COLUMN_DEFAULT)) if (VOLATILE.test(match[1] ?? "")) return `adds a column to ${table} with a volatile default (${(match[1] ?? "").trim()}), which rewrites every row.`;
+};
+/** Whether `statement` takes an access exclusive lock on a table others use. */
+function takesExclusiveLock(parsed, statement) {
+	if (EXCLUSIVE.test(statement.text)) return true;
+	const match = CREATE_INDEX.exec(statement.text);
+	if (match?.[2] !== void 0 && match[1] === void 0) return !parsed.created.has(tableKey(match[2]));
+	return alteredTable(parsed, statement) !== void 0;
+}
+async function missingLockTimeout(context) {
+	return (await unappliedMigrations(context)).flatMap((file) => {
+		const parsed = parse(file);
+		const first = parsed.statements.find((statement) => takesExclusiveLock(parsed, statement));
+		if (first === void 0) return [];
+		return parsed.statements.some((statement) => statement.line <= first.line && LOCK_TIMEOUT.test(statement.text)) ? [] : [{
+			message: `${file.path} locks tables it didn't create (line ${String(first.line)}) without setting lock_timeout, so a long query ahead of it queues every read and write behind the migration.`,
+			target: file.path,
+			location: {
+				file: file.path,
+				line: first.line
+			}
+		}];
+	});
+}
+const dropOrRename = (parsed, statement) => {
+	const isDropTable = /^drop\s+table\b/iu.test(statement.text);
+	const table = alteredTable(parsed, statement);
+	if (isDropTable) return "drops a table; app code that still reads it fails once this runs.";
+	if (table === void 0) return;
+	if (RENAME.test(statement.text)) return `renames ${table} or one of its columns; app code that uses the old name fails once this runs.`;
+	return DROP.test(statement.text) ? `drops a column of ${table}; app code that still reads it fails once this runs.` : void 0;
+};
+const LIBRARY_FUNCTION = String.raw`(?:"better_supabase"|better_supabase)\s*\.\s*("[^"]+"|[\w$]+)\s*\(`;
+const DROP_FUNCTION = /^drop\s+(?:function|procedure)\s+(?:if\s+exists\s+)?/iu;
+const CREATE_FUNCTION = new RegExp(String.raw`^create\s+(?:or\s+replace\s+)?(?:function|procedure)\s+${LIBRARY_FUNCTION}`, "iu");
+/** The text between the parenthesis at `open` and its match, or undefined. */
+function parenthesized(text, open) {
+	let depth = 0;
+	let quote;
+	for (let index = open; index < text.length; index += 1) {
+		const char = text.charAt(index);
+		if (quote !== void 0) {
+			if (char === quote) quote = void 0;
+		} else if (char === "'" || char === "\"") quote = char;
+		else if (char === "(") depth += 1;
+		else if (char === ")") {
+			depth -= 1;
+			if (depth === 0) return text.slice(open + 1, index);
+		}
+	}
+}
+/**
+* How many input arguments a function argument list has: the top-level commas,
+* without `out` arguments, which are not part of the signature.
+*/
+function inputArity(args) {
+	const parts = [];
+	let depth = 0;
+	let quote;
+	let start = 0;
+	for (let index = 0; index < args.length; index += 1) {
+		const char = args.charAt(index);
+		if (quote !== void 0) {
+			if (char === quote) quote = void 0;
+		} else if (char === "'" || char === "\"") quote = char;
+		else if (char === "(") depth += 1;
+		else if (char === ")") depth -= 1;
+		else if (char === "," && depth === 0) {
+			parts.push(args.slice(start, index));
+			start = index + 1;
+		}
+	}
+	parts.push(args.slice(start));
+	return parts.filter((part) => {
+		const trimmed = part.trim();
+		return trimmed !== "" && !/^out\s/iu.test(trimmed);
+	}).length;
+}
+const functionName = (name) => name.replaceAll("\"", "").toLowerCase();
+/**
+* Each `better_supabase` function a `drop function` statement names, with its
+* arity.
+*/
+function droppedFunctions(text) {
+	const head = DROP_FUNCTION.exec(text);
+	if (head === null) return [];
+	const pattern = new RegExp(LIBRARY_FUNCTION, "giu");
+	const dropped = [];
+	for (const match of text.slice(head[0].length).matchAll(pattern)) {
+		const args = parenthesized(text, head[0].length + match.index + match[0].length - 1);
+		if (match[1] !== void 0 && args !== void 0) dropped.push({
+			name: functionName(match[1]),
+			arity: inputArity(args)
+		});
+	}
+	return dropped;
+}
+const createdSignatures = /* @__PURE__ */ new WeakMap();
+/** `name/arity` for every `better_supabase` function the file creates. */
+function createdFunctions(parsed) {
+	let created = createdSignatures.get(parsed);
+	if (created === void 0) {
+		created = new Set(parsed.statements.flatMap((statement) => {
+			const match = CREATE_FUNCTION.exec(statement.text);
+			if (match?.[1] === void 0) return [];
+			const args = parenthesized(statement.text, match[0].length - 1);
+			return args === void 0 ? [] : [`${functionName(match[1])}/${String(inputArity(args))}`];
+		}));
+		createdSignatures.set(parsed, created);
+	}
+	return created;
+}
+const droppedLibraryFunction = (parsed, statement) => {
+	const created = createdFunctions(parsed);
+	const changed = droppedFunctions(statement.text).filter((each) => !created.has(`${each.name}/${String(each.arity)}`));
+	if (changed.length === 0) return;
+	return `drops ${changed.map((each) => `better_supabase.${each.name}`).join(", ")} without creating it again with the same arguments. A call with positional arguments, or a grant on the old signature, fails once this runs.`;
+};
+const MIGRATION_SAFETY_RULES = [
+	{
+		code: "BS229",
+		severity: "warning",
+		title: "Index created without concurrently",
+		description: "A migration creates an index on an existing table without `concurrently`. The build holds a lock that blocks inserts, updates and deletes on the table until it finishes. Use `create index concurrently`, in a migration file of its own: the statement can't run inside a transaction block.",
+		check: perStatement(indexWithoutConcurrently)
+	},
+	{
+		code: "BS230",
+		severity: "warning",
+		title: "Constraint added without not valid",
+		description: "A migration adds a foreign key or check to an existing table without `not valid`, so Postgres checks every row while it holds the lock. Add it with `not valid`, then run `alter table ... validate constraint` in a later statement, which takes a lighter lock.",
+		check: perStatement(constraintWithoutNotValid)
+	},
+	{
+		code: "BS231",
+		severity: "warning",
+		title: "Column type change or set not null",
+		description: "A migration changes a column type or sets `not null` on an existing table. A type change can rewrite the table, and `set not null` scans every row, both under an access exclusive lock. For `not null`, add `check (column is not null) not valid`, validate it, then set not null. For a type, add a new column and backfill it.",
+		check: perStatement(rewriteOrScan)
+	},
+	{
+		code: "BS232",
+		severity: "warning",
+		title: "Column added with a volatile default",
+		description: "A migration adds a column with a volatile default, such as `gen_random_uuid()` or `clock_timestamp()`, to an existing table. Postgres writes the value into every row under an access exclusive lock. Add the column without a default, backfill it in batches, then set the default.",
+		check: perStatement(volatileDefault)
+	},
+	{
+		code: "BS233",
+		severity: "warning",
+		title: "Migration without lock_timeout",
+		description: "A migration takes an access exclusive lock on an existing table without `set lock_timeout`. While it waits behind a long query, every read and write of the table queues behind it. Start the file with `set lock_timeout = '5s';` and retry the migration when it times out.",
+		check: missingLockTimeout
+	},
+	{
+		code: "BS234",
+		severity: "info",
+		title: "Migration drops or renames",
+		description: `A migration drops or renames a table or column. App code deployed before it still uses the old name and fails once it runs. Expand and contract: add the new shape, deploy app code that uses it, then remove the old one in a later migration.`,
+		check: perStatement(dropOrRename)
+	},
+	{
+		code: "BS235",
+		severity: "warning",
+		title: "Migration drops a better-supabase function",
+		description: "A migration drops a `better_supabase` function and doesn't create it again with the same number of arguments. A schema diff does this when a better-supabase release changes a function's signature, such as `audit()` in 0.12. Calls with positional arguments and grants on the old signature fail once it runs. Read the upgrade notes for the release (/docs/migration), then update your calls and grants in the same migration.",
+		check: perStatement(droppedLibraryFunction)
+	}
+];
+//#endregion
+export { latestMigrationVersion as n, MIGRATION_SAFETY_RULES as t };