@geekmidas/db 1.1.1 → 10.0.0-alpha.0

package/dist/pg/roles.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"roles.cjs","names":["spec: RoleSpec","reader: string","role: string","runtime: string","name: string","value: string"],"sources":["../../src/pg/roles.ts"],"sourcesContent":["/**\n * The role DDL — an owner, a runtime role, and the grants between them.\n *\n * Generation only. The same statements have to run in-process from `gkm dev`\n * and from a provisioner inside a VPC at deploy, and one implementation is what\n * stops \"works locally, fails deployed\" — so this composes SQL and applies\n * none of it.\n *\n * **What the split is for.** A handler connects as the runtime role, which can\n * read and write rows and cannot create, alter, or drop anything. A migrator\n * connects as the owner, which can. That is a security property rather than a\n * convention — a compromised handler cannot `DROP TABLE` because its role holds\n * no such grant — and it is only a property at all once these statements have\n * actually run. Until then a schema is a namespace, not a boundary.\n *\n * **Passwords are an input.** This module invents no secrets: a caller derives\n * or fetches them and passes them in, because where a password comes from is\n * the one part that legitimately differs between a laptop and a deploy.\n */\n\n/** The roles and schema one tenant needs. */\nexport interface RoleSpec {\n\t/** The role a handler connects as. Reads and writes rows; owns nothing. */\n\truntime: string;\n\t/** The role a migrator connects as. Owns the schema and everything in it. */\n\towner: string;\n\t/**\n\t * A third role that may only read, for a reader endpoint.\n\t *\n\t * Optional because it is only worth creating where something points at it.\n\t * Read-only is enforced *here*, by the grants, rather than by which endpoint\n\t * a URL happens to name — which is what makes falling back to the writer's\n\t * endpoint safe when a cluster has no replica.\n\t */\n\treader?: string;\n\t/** The schema they operate in, pinned on every role's `search_path`. */\n\tschema: string;\n\t/** Supplied, never generated here. */\n\tpasswords: { runtime: string; owner: string; reader?: string };\n}\n\n/** One statement, and how to tell whether it still needs running. */\nexport interface RoleStatement {\n\t/** What it does, for the line a reconciler prints. */\n\tdescribe: string;\n\t/**\n\t * Answers \"does this already exist\", parameterised.\n\t *\n\t * Absent means the statement is idempotent in itself and is run every time —\n\t * a `GRANT` re-granting what is already granted is a no-op, and checking\n\t * would cost a round trip to learn nothing.\n\t */\n\texists?: { sql: string; values: unknown[] };\n\tsql: string;\n}\n\n/**\n * Everything one tenant's roles need, in dependency order.\n *\n * The owner before the schema it owns, the schema before the grants on it. A\n * caller applies them in sequence and may stop at the first failure without\n * leaving a half-granted role that looks complete.\n */\nexport function roleStatements(spec: RoleSpec): RoleStatement[] {\n\tconst { runtime, owner, schema, passwords } = spec;\n\n\treturn [\n\t\t{\n\t\t\tdescribe: `role ${owner}`,\n\t\t\texists: roleExists(owner),\n\t\t\tsql: `CREATE ROLE ${ident(owner)} LOGIN PASSWORD ${literal(passwords.owner)}`,\n\t\t},\n\t\t{\n\t\t\tdescribe: `role ${runtime}`,\n\t\t\texists: roleExists(runtime),\n\t\t\tsql: `CREATE ROLE ${ident(runtime)} LOGIN PASSWORD ${literal(passwords.runtime)}`,\n\t\t},\n\t\t{\n\t\t\t// Postgres will not let you create an object owned by a role you are\n\t\t\t// not a member of, and an RDS master is not a superuser — so\n\t\t\t// `CREATE SCHEMA … AUTHORIZATION` fails with \"must be able to SET\n\t\t\t// ROLE\" unless the connected role is granted membership first.\n\t\t\t//\n\t\t\t// Granting is idempotent and needs no check. It also leaves the master\n\t\t\t// able to administer the schema, which is what you want from the one\n\t\t\t// credential that exists before any role does.\n\t\t\tdescribe: `${owner} granted to the connecting role`,\n\t\t\tsql: `GRANT ${ident(owner)} TO CURRENT_USER`,\n\t\t},\n\t\t{\n\t\t\tdescribe: `schema ${schema}`,\n\t\t\texists: {\n\t\t\t\tsql: 'SELECT 1 FROM information_schema.schemata WHERE schema_name = $1',\n\t\t\t\tvalues: [schema],\n\t\t\t},\n\t\t\t// Owned by the owner from the moment it exists. Creating it as the\n\t\t\t// cluster master and granting afterwards leaves a window where the\n\t\t\t// master owns objects the owner is supposed to.\n\t\t\tsql: `CREATE SCHEMA ${ident(schema)} AUTHORIZATION ${ident(owner)}`,\n\t\t},\n\t\t{\n\t\t\t// And the schema that was already there, which the guard above skips.\n\t\t\t// A schema created before its roles existed is owned by whoever\n\t\t\t// created it — the cluster master — and nothing below fixes that, so\n\t\t\t// the owner cannot create in the schema it is supposed to own. The\n\t\t\t// failure is `no schema has been selected to create in`, which names\n\t\t\t// neither the schema nor the owner and reads like a missing\n\t\t\t// `search_path`.\n\t\t\t//\n\t\t\t// Idempotent when the owner is already right, so it costs a statement\n\t\t\t// rather than a check.\n\t\t\tdescribe: `${schema} is owned by ${owner}`,\n\t\t\tsql: `ALTER SCHEMA ${ident(schema)} OWNER TO ${ident(owner)}`,\n\t\t},\n\t\t{\n\t\t\tdescribe: `${runtime} may use ${schema}`,\n\t\t\tsql: `GRANT USAGE ON SCHEMA ${ident(schema)} TO ${ident(runtime)}`,\n\t\t},\n\t\t{\n\t\t\t// The important half: *future* tables. A grant on what exists today\n\t\t\t// covers nothing the next migration creates, which is how a runtime\n\t\t\t// role silently loses access one deploy later.\n\t\t\tdescribe: `${runtime} may read and write future tables in ${schema}`,\n\t\t\tsql:\n\t\t\t\t`ALTER DEFAULT PRIVILEGES FOR ROLE ${ident(owner)} IN SCHEMA ${ident(schema)} ` +\n\t\t\t\t`GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO ${ident(runtime)}`,\n\t\t},\n\t\t{\n\t\t\tdescribe: `${runtime} may use future sequences in ${schema}`,\n\t\t\tsql:\n\t\t\t\t`ALTER DEFAULT PRIVILEGES FOR ROLE ${ident(owner)} IN SCHEMA ${ident(schema)} ` +\n\t\t\t\t`GRANT USAGE, SELECT ON SEQUENCES TO ${ident(runtime)}`,\n\t\t},\n\t\t{\n\t\t\t// And the tables that are already there, for a schema that existed\n\t\t\t// before its roles did.\n\t\t\tdescribe: `${runtime} may read and write existing tables in ${schema}`,\n\t\t\tsql:\n\t\t\t\t`GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA ${ident(schema)} ` +\n\t\t\t\t`TO ${ident(runtime)}`,\n\t\t},\n\t\t{\n\t\t\tdescribe: `${runtime} may use existing sequences in ${schema}`,\n\t\t\tsql: `GRANT USAGE, SELECT ON ALL SEQUENCES IN SCHEMA ${ident(schema)} TO ${ident(runtime)}`,\n\t\t},\n\t\t{\n\t\t\t// Pinned on the role rather than carried in every URL. A connection\n\t\t\t// string that has to remember `search_path` is one that eventually\n\t\t\t// forgets, and the forgetting looks like an empty database.\n\t\t\tdescribe: `${runtime} resolves names in ${schema}`,\n\t\t\tsql: `ALTER ROLE ${ident(runtime)} SET search_path TO ${ident(schema)}`,\n\t\t},\n\t\t{\n\t\t\tdescribe: `${owner} resolves names in ${schema}`,\n\t\t\tsql: `ALTER ROLE ${ident(owner)} SET search_path TO ${ident(schema)}`,\n\t\t},\n\t\t...(spec.reader ? readerStatements(spec, spec.reader) : []),\n\t];\n}\n\n/**\n * A role that may read and nothing else.\n *\n * `SELECT` and no more, on what exists and on what the owner creates later. No\n * `INSERT`, no `UPDATE`, no `DELETE`, and no sequence `USAGE` — a reader that\n * could take a sequence value could not write the row it was for, so granting\n * it would be surface with no use.\n */\nfunction readerStatements(spec: RoleSpec, reader: string): RoleStatement[] {\n\tconst { owner, schema, passwords } = spec;\n\tconst password = passwords.reader;\n\n\tif (!password) throw new ReaderNeedsPassword(reader);\n\n\treturn [\n\t\t{\n\t\t\tdescribe: `role ${reader}`,\n\t\t\texists: roleExists(reader),\n\t\t\tsql: `CREATE ROLE ${ident(reader)} LOGIN PASSWORD ${literal(password)}`,\n\t\t},\n\t\t{\n\t\t\tdescribe: `${reader} may use ${schema}`,\n\t\t\tsql: `GRANT USAGE ON SCHEMA ${ident(schema)} TO ${ident(reader)}`,\n\t\t},\n\t\t{\n\t\t\tdescribe: `${reader} may read future tables in ${schema}`,\n\t\t\tsql:\n\t\t\t\t`ALTER DEFAULT PRIVILEGES FOR ROLE ${ident(owner)} IN SCHEMA ${ident(schema)} ` +\n\t\t\t\t`GRANT SELECT ON TABLES TO ${ident(reader)}`,\n\t\t},\n\t\t{\n\t\t\tdescribe: `${reader} may read existing tables in ${schema}`,\n\t\t\tsql: `GRANT SELECT ON ALL TABLES IN SCHEMA ${ident(schema)} TO ${ident(reader)}`,\n\t\t},\n\t\t{\n\t\t\tdescribe: `${reader} resolves names in ${schema}`,\n\t\t\tsql: `ALTER ROLE ${ident(reader)} SET search_path TO ${ident(schema)}`,\n\t\t},\n\t];\n}\n\n/** A reader role was named and no password was supplied for it. */\nexport class ReaderNeedsPassword extends Error {\n\tconstructor(readonly role: string) {\n\t\tsuper(\n\t\t\t`'${role}' is a reader role and no password was supplied for it. ` +\n\t\t\t\t`This module composes DDL and invents no secrets: pass ` +\n\t\t\t\t`passwords.reader alongside the role name.`,\n\t\t);\n\t\tthis.name = 'ReaderNeedsPassword';\n\t}\n}\n\n/** The read-only role's name for a given runtime role. */\nexport function readerRole(runtime: string): string {\n\treturn `${runtime}_reader`;\n}\n\n/** The owner role's name for a given runtime role. */\nexport function ownerRole(runtime: string): string {\n\treturn `${runtime}_owner`;\n}\n\nfunction roleExists(role: string): { sql: string; values: unknown[] } {\n\treturn { sql: 'SELECT 1 FROM pg_roles WHERE rolname = $1', values: [role] };\n}\n\n/**\n * Quote an identifier for use in DDL.\n *\n * Names reaching here are already canonical, so this is defence rather than\n * sanitisation — but DDL cannot be parameterised, and an unquoted identifier is\n * the one place a name could ever be more than a name.\n */\nfunction ident(name: string): string {\n\treturn `\"${name.replace(/\"/g, '\"\"')}\"`;\n}\n\n/**\n * Quote a string literal.\n *\n * A password cannot be a bind parameter in `CREATE ROLE`, which is the one\n * place in this module where a value rather than a name is interpolated — so it\n * is escaped rather than trusted, whatever the caller believes it derived.\n */\nfunction literal(value: string): string {\n\treturn `'${value.replace(/'/g, \"''\")}'`;\n}\n"],"mappings":"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"}

package/dist/pg/roles.d.cts

@@ -0,0 +1,82 @@
+//#region src/pg/roles.d.ts
+/**
+ * The role DDL — an owner, a runtime role, and the grants between them.
+ *
+ * Generation only. The same statements have to run in-process from `gkm dev`
+ * and from a provisioner inside a VPC at deploy, and one implementation is what
+ * stops "works locally, fails deployed" — so this composes SQL and applies
+ * none of it.
+ *
+ * **What the split is for.** A handler connects as the runtime role, which can
+ * read and write rows and cannot create, alter, or drop anything. A migrator
+ * connects as the owner, which can. That is a security property rather than a
+ * convention — a compromised handler cannot `DROP TABLE` because its role holds
+ * no such grant — and it is only a property at all once these statements have
+ * actually run. Until then a schema is a namespace, not a boundary.
+ *
+ * **Passwords are an input.** This module invents no secrets: a caller derives
+ * or fetches them and passes them in, because where a password comes from is
+ * the one part that legitimately differs between a laptop and a deploy.
+ */
+/** The roles and schema one tenant needs. */
+interface RoleSpec {
+  /** The role a handler connects as. Reads and writes rows; owns nothing. */
+  runtime: string;
+  /** The role a migrator connects as. Owns the schema and everything in it. */
+  owner: string;
+  /**
+   * A third role that may only read, for a reader endpoint.
+   *
+   * Optional because it is only worth creating where something points at it.
+   * Read-only is enforced *here*, by the grants, rather than by which endpoint
+   * a URL happens to name — which is what makes falling back to the writer's
+   * endpoint safe when a cluster has no replica.
+   */
+  reader?: string;
+  /** The schema they operate in, pinned on every role's `search_path`. */
+  schema: string;
+  /** Supplied, never generated here. */
+  passwords: {
+    runtime: string;
+    owner: string;
+    reader?: string;
+  };
+}
+/** One statement, and how to tell whether it still needs running. */
+interface RoleStatement {
+  /** What it does, for the line a reconciler prints. */
+  describe: string;
+  /**
+   * Answers "does this already exist", parameterised.
+   *
+   * Absent means the statement is idempotent in itself and is run every time —
+   * a `GRANT` re-granting what is already granted is a no-op, and checking
+   * would cost a round trip to learn nothing.
+   */
+  exists?: {
+    sql: string;
+    values: unknown[];
+  };
+  sql: string;
+}
+/**
+ * Everything one tenant's roles need, in dependency order.
+ *
+ * The owner before the schema it owns, the schema before the grants on it. A
+ * caller applies them in sequence and may stop at the first failure without
+ * leaving a half-granted role that looks complete.
+ */
+declare function roleStatements(spec: RoleSpec): RoleStatement[];
+/** A reader role was named and no password was supplied for it. */
+declare class ReaderNeedsPassword extends Error {
+  readonly role: string;
+  constructor(role: string);
+}
+/** The read-only role's name for a given runtime role. */
+declare function readerRole(runtime: string): string;
+/** The owner role's name for a given runtime role. */
+declare function ownerRole(runtime: string): string;
+//# sourceMappingURL=roles.d.ts.map
+//#endregion
+export { ReaderNeedsPassword, RoleSpec, RoleStatement, ownerRole, readerRole, roleStatements };
+//# sourceMappingURL=roles.d.cts.map

package/dist/pg/roles.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"roles.d.cts","names":[],"sources":["../../src/pg/roles.ts"],"sourcesContent":[],"mappings":";;AAqBA;AAqBA;AAqBA;;;;AAA6D;AA2I7D;AAYA;AAKA;;;;;;;;;;UAtMiB,QAAA;;;;;;;;;;;;;;;;;;;;;;;;UAqBA,aAAA;;;;;;;;;;;;;;;;;;;;;;;iBAqBD,cAAA,OAAqB,WAAW;;cA2InC,mBAAA,SAA4B,KAAK;;;;;iBAY9B,UAAA;;iBAKA,SAAA"}

package/dist/pg/roles.d.mts

@@ -0,0 +1,82 @@
+//#region src/pg/roles.d.ts
+/**
+ * The role DDL — an owner, a runtime role, and the grants between them.
+ *
+ * Generation only. The same statements have to run in-process from `gkm dev`
+ * and from a provisioner inside a VPC at deploy, and one implementation is what
+ * stops "works locally, fails deployed" — so this composes SQL and applies
+ * none of it.
+ *
+ * **What the split is for.** A handler connects as the runtime role, which can
+ * read and write rows and cannot create, alter, or drop anything. A migrator
+ * connects as the owner, which can. That is a security property rather than a
+ * convention — a compromised handler cannot `DROP TABLE` because its role holds
+ * no such grant — and it is only a property at all once these statements have
+ * actually run. Until then a schema is a namespace, not a boundary.
+ *
+ * **Passwords are an input.** This module invents no secrets: a caller derives
+ * or fetches them and passes them in, because where a password comes from is
+ * the one part that legitimately differs between a laptop and a deploy.
+ */
+/** The roles and schema one tenant needs. */
+interface RoleSpec {
+  /** The role a handler connects as. Reads and writes rows; owns nothing. */
+  runtime: string;
+  /** The role a migrator connects as. Owns the schema and everything in it. */
+  owner: string;
+  /**
+   * A third role that may only read, for a reader endpoint.
+   *
+   * Optional because it is only worth creating where something points at it.
+   * Read-only is enforced *here*, by the grants, rather than by which endpoint
+   * a URL happens to name — which is what makes falling back to the writer's
+   * endpoint safe when a cluster has no replica.
+   */
+  reader?: string;
+  /** The schema they operate in, pinned on every role's `search_path`. */
+  schema: string;
+  /** Supplied, never generated here. */
+  passwords: {
+    runtime: string;
+    owner: string;
+    reader?: string;
+  };
+}
+/** One statement, and how to tell whether it still needs running. */
+interface RoleStatement {
+  /** What it does, for the line a reconciler prints. */
+  describe: string;
+  /**
+   * Answers "does this already exist", parameterised.
+   *
+   * Absent means the statement is idempotent in itself and is run every time —
+   * a `GRANT` re-granting what is already granted is a no-op, and checking
+   * would cost a round trip to learn nothing.
+   */
+  exists?: {
+    sql: string;
+    values: unknown[];
+  };
+  sql: string;
+}
+/**
+ * Everything one tenant's roles need, in dependency order.
+ *
+ * The owner before the schema it owns, the schema before the grants on it. A
+ * caller applies them in sequence and may stop at the first failure without
+ * leaving a half-granted role that looks complete.
+ */
+declare function roleStatements(spec: RoleSpec): RoleStatement[];
+/** A reader role was named and no password was supplied for it. */
+declare class ReaderNeedsPassword extends Error {
+  readonly role: string;
+  constructor(role: string);
+}
+/** The read-only role's name for a given runtime role. */
+declare function readerRole(runtime: string): string;
+/** The owner role's name for a given runtime role. */
+declare function ownerRole(runtime: string): string;
+//# sourceMappingURL=roles.d.ts.map
+//#endregion
+export { ReaderNeedsPassword, RoleSpec, RoleStatement, ownerRole, readerRole, roleStatements };
+//# sourceMappingURL=roles.d.mts.map

package/dist/pg/roles.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"roles.d.mts","names":[],"sources":["../../src/pg/roles.ts"],"sourcesContent":[],"mappings":";;AAqBA;AAqBA;AAqBA;;;;AAA6D;AA2I7D;AAYA;AAKA;;;;;;;;;;UAtMiB,QAAA;;;;;;;;;;;;;;;;;;;;;;;;UAqBA,aAAA;;;;;;;;;;;;;;;;;;;;;;;iBAqBD,cAAA,OAAqB,WAAW;;cA2InC,mBAAA,SAA4B,KAAK;;;;;iBAY9B,UAAA;;iBAKA,SAAA"}

package/dist/pg/roles.mjs

@@ -0,0 +1,150 @@
+//#region src/pg/roles.ts
+/**
+* Everything one tenant's roles need, in dependency order.
+*
+* The owner before the schema it owns, the schema before the grants on it. A
+* caller applies them in sequence and may stop at the first failure without
+* leaving a half-granted role that looks complete.
+*/
+function roleStatements(spec) {
+	const { runtime, owner, schema, passwords } = spec;
+	return [
+		{
+			describe: `role ${owner}`,
+			exists: roleExists(owner),
+			sql: `CREATE ROLE ${ident(owner)} LOGIN PASSWORD ${literal(passwords.owner)}`
+		},
+		{
+			describe: `role ${runtime}`,
+			exists: roleExists(runtime),
+			sql: `CREATE ROLE ${ident(runtime)} LOGIN PASSWORD ${literal(passwords.runtime)}`
+		},
+		{
+			describe: `${owner} granted to the connecting role`,
+			sql: `GRANT ${ident(owner)} TO CURRENT_USER`
+		},
+		{
+			describe: `schema ${schema}`,
+			exists: {
+				sql: "SELECT 1 FROM information_schema.schemata WHERE schema_name = $1",
+				values: [schema]
+			},
+			sql: `CREATE SCHEMA ${ident(schema)} AUTHORIZATION ${ident(owner)}`
+		},
+		{
+			describe: `${schema} is owned by ${owner}`,
+			sql: `ALTER SCHEMA ${ident(schema)} OWNER TO ${ident(owner)}`
+		},
+		{
+			describe: `${runtime} may use ${schema}`,
+			sql: `GRANT USAGE ON SCHEMA ${ident(schema)} TO ${ident(runtime)}`
+		},
+		{
+			describe: `${runtime} may read and write future tables in ${schema}`,
+			sql: `ALTER DEFAULT PRIVILEGES FOR ROLE ${ident(owner)} IN SCHEMA ${ident(schema)} GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO ${ident(runtime)}`
+		},
+		{
+			describe: `${runtime} may use future sequences in ${schema}`,
+			sql: `ALTER DEFAULT PRIVILEGES FOR ROLE ${ident(owner)} IN SCHEMA ${ident(schema)} GRANT USAGE, SELECT ON SEQUENCES TO ${ident(runtime)}`
+		},
+		{
+			describe: `${runtime} may read and write existing tables in ${schema}`,
+			sql: `GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA ${ident(schema)} TO ${ident(runtime)}`
+		},
+		{
+			describe: `${runtime} may use existing sequences in ${schema}`,
+			sql: `GRANT USAGE, SELECT ON ALL SEQUENCES IN SCHEMA ${ident(schema)} TO ${ident(runtime)}`
+		},
+		{
+			describe: `${runtime} resolves names in ${schema}`,
+			sql: `ALTER ROLE ${ident(runtime)} SET search_path TO ${ident(schema)}`
+		},
+		{
+			describe: `${owner} resolves names in ${schema}`,
+			sql: `ALTER ROLE ${ident(owner)} SET search_path TO ${ident(schema)}`
+		},
+		...spec.reader ? readerStatements(spec, spec.reader) : []
+	];
+}
+/**
+* A role that may read and nothing else.
+*
+* `SELECT` and no more, on what exists and on what the owner creates later. No
+* `INSERT`, no `UPDATE`, no `DELETE`, and no sequence `USAGE` — a reader that
+* could take a sequence value could not write the row it was for, so granting
+* it would be surface with no use.
+*/
+function readerStatements(spec, reader) {
+	const { owner, schema, passwords } = spec;
+	const password = passwords.reader;
+	if (!password) throw new ReaderNeedsPassword(reader);
+	return [
+		{
+			describe: `role ${reader}`,
+			exists: roleExists(reader),
+			sql: `CREATE ROLE ${ident(reader)} LOGIN PASSWORD ${literal(password)}`
+		},
+		{
+			describe: `${reader} may use ${schema}`,
+			sql: `GRANT USAGE ON SCHEMA ${ident(schema)} TO ${ident(reader)}`
+		},
+		{
+			describe: `${reader} may read future tables in ${schema}`,
+			sql: `ALTER DEFAULT PRIVILEGES FOR ROLE ${ident(owner)} IN SCHEMA ${ident(schema)} GRANT SELECT ON TABLES TO ${ident(reader)}`
+		},
+		{
+			describe: `${reader} may read existing tables in ${schema}`,
+			sql: `GRANT SELECT ON ALL TABLES IN SCHEMA ${ident(schema)} TO ${ident(reader)}`
+		},
+		{
+			describe: `${reader} resolves names in ${schema}`,
+			sql: `ALTER ROLE ${ident(reader)} SET search_path TO ${ident(schema)}`
+		}
+	];
+}
+/** A reader role was named and no password was supplied for it. */
+var ReaderNeedsPassword = class extends Error {
+	constructor(role) {
+		super(`'${role}' is a reader role and no password was supplied for it. This module composes DDL and invents no secrets: pass passwords.reader alongside the role name.`);
+		this.role = role;
+		this.name = "ReaderNeedsPassword";
+	}
+};
+/** The read-only role's name for a given runtime role. */
+function readerRole(runtime) {
+	return `${runtime}_reader`;
+}
+/** The owner role's name for a given runtime role. */
+function ownerRole(runtime) {
+	return `${runtime}_owner`;
+}
+function roleExists(role) {
+	return {
+		sql: "SELECT 1 FROM pg_roles WHERE rolname = $1",
+		values: [role]
+	};
+}
+/**
+* Quote an identifier for use in DDL.
+*
+* Names reaching here are already canonical, so this is defence rather than
+* sanitisation — but DDL cannot be parameterised, and an unquoted identifier is
+* the one place a name could ever be more than a name.
+*/
+function ident(name) {
+	return `"${name.replace(/"/g, "\"\"")}"`;
+}
+/**
+* Quote a string literal.
+*
+* A password cannot be a bind parameter in `CREATE ROLE`, which is the one
+* place in this module where a value rather than a name is interpolated — so it
+* is escaped rather than trusted, whatever the caller believes it derived.
+*/
+function literal(value) {
+	return `'${value.replace(/'/g, "''")}'`;
+}
+
+//#endregion
+export { ReaderNeedsPassword, ownerRole, readerRole, roleStatements };
+//# sourceMappingURL=roles.mjs.map

package/dist/pg/roles.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"roles.mjs","names":["spec: RoleSpec","reader: string","role: string","runtime: string","name: string","value: string"],"sources":["../../src/pg/roles.ts"],"sourcesContent":["/**\n * The role DDL — an owner, a runtime role, and the grants between them.\n *\n * Generation only. The same statements have to run in-process from `gkm dev`\n * and from a provisioner inside a VPC at deploy, and one implementation is what\n * stops \"works locally, fails deployed\" — so this composes SQL and applies\n * none of it.\n *\n * **What the split is for.** A handler connects as the runtime role, which can\n * read and write rows and cannot create, alter, or drop anything. A migrator\n * connects as the owner, which can. That is a security property rather than a\n * convention — a compromised handler cannot `DROP TABLE` because its role holds\n * no such grant — and it is only a property at all once these statements have\n * actually run. Until then a schema is a namespace, not a boundary.\n *\n * **Passwords are an input.** This module invents no secrets: a caller derives\n * or fetches them and passes them in, because where a password comes from is\n * the one part that legitimately differs between a laptop and a deploy.\n */\n\n/** The roles and schema one tenant needs. */\nexport interface RoleSpec {\n\t/** The role a handler connects as. Reads and writes rows; owns nothing. */\n\truntime: string;\n\t/** The role a migrator connects as. Owns the schema and everything in it. */\n\towner: string;\n\t/**\n\t * A third role that may only read, for a reader endpoint.\n\t *\n\t * Optional because it is only worth creating where something points at it.\n\t * Read-only is enforced *here*, by the grants, rather than by which endpoint\n\t * a URL happens to name — which is what makes falling back to the writer's\n\t * endpoint safe when a cluster has no replica.\n\t */\n\treader?: string;\n\t/** The schema they operate in, pinned on every role's `search_path`. */\n\tschema: string;\n\t/** Supplied, never generated here. */\n\tpasswords: { runtime: string; owner: string; reader?: string };\n}\n\n/** One statement, and how to tell whether it still needs running. */\nexport interface RoleStatement {\n\t/** What it does, for the line a reconciler prints. */\n\tdescribe: string;\n\t/**\n\t * Answers \"does this already exist\", parameterised.\n\t *\n\t * Absent means the statement is idempotent in itself and is run every time —\n\t * a `GRANT` re-granting what is already granted is a no-op, and checking\n\t * would cost a round trip to learn nothing.\n\t */\n\texists?: { sql: string; values: unknown[] };\n\tsql: string;\n}\n\n/**\n * Everything one tenant's roles need, in dependency order.\n *\n * The owner before the schema it owns, the schema before the grants on it. A\n * caller applies them in sequence and may stop at the first failure without\n * leaving a half-granted role that looks complete.\n */\nexport function roleStatements(spec: RoleSpec): RoleStatement[] {\n\tconst { runtime, owner, schema, passwords } = spec;\n\n\treturn [\n\t\t{\n\t\t\tdescribe: `role ${owner}`,\n\t\t\texists: roleExists(owner),\n\t\t\tsql: `CREATE ROLE ${ident(owner)} LOGIN PASSWORD ${literal(passwords.owner)}`,\n\t\t},\n\t\t{\n\t\t\tdescribe: `role ${runtime}`,\n\t\t\texists: roleExists(runtime),\n\t\t\tsql: `CREATE ROLE ${ident(runtime)} LOGIN PASSWORD ${literal(passwords.runtime)}`,\n\t\t},\n\t\t{\n\t\t\t// Postgres will not let you create an object owned by a role you are\n\t\t\t// not a member of, and an RDS master is not a superuser — so\n\t\t\t// `CREATE SCHEMA … AUTHORIZATION` fails with \"must be able to SET\n\t\t\t// ROLE\" unless the connected role is granted membership first.\n\t\t\t//\n\t\t\t// Granting is idempotent and needs no check. It also leaves the master\n\t\t\t// able to administer the schema, which is what you want from the one\n\t\t\t// credential that exists before any role does.\n\t\t\tdescribe: `${owner} granted to the connecting role`,\n\t\t\tsql: `GRANT ${ident(owner)} TO CURRENT_USER`,\n\t\t},\n\t\t{\n\t\t\tdescribe: `schema ${schema}`,\n\t\t\texists: {\n\t\t\t\tsql: 'SELECT 1 FROM information_schema.schemata WHERE schema_name = $1',\n\t\t\t\tvalues: [schema],\n\t\t\t},\n\t\t\t// Owned by the owner from the moment it exists. Creating it as the\n\t\t\t// cluster master and granting afterwards leaves a window where the\n\t\t\t// master owns objects the owner is supposed to.\n\t\t\tsql: `CREATE SCHEMA ${ident(schema)} AUTHORIZATION ${ident(owner)}`,\n\t\t},\n\t\t{\n\t\t\t// And the schema that was already there, which the guard above skips.\n\t\t\t// A schema created before its roles existed is owned by whoever\n\t\t\t// created it — the cluster master — and nothing below fixes that, so\n\t\t\t// the owner cannot create in the schema it is supposed to own. The\n\t\t\t// failure is `no schema has been selected to create in`, which names\n\t\t\t// neither the schema nor the owner and reads like a missing\n\t\t\t// `search_path`.\n\t\t\t//\n\t\t\t// Idempotent when the owner is already right, so it costs a statement\n\t\t\t// rather than a check.\n\t\t\tdescribe: `${schema} is owned by ${owner}`,\n\t\t\tsql: `ALTER SCHEMA ${ident(schema)} OWNER TO ${ident(owner)}`,\n\t\t},\n\t\t{\n\t\t\tdescribe: `${runtime} may use ${schema}`,\n\t\t\tsql: `GRANT USAGE ON SCHEMA ${ident(schema)} TO ${ident(runtime)}`,\n\t\t},\n\t\t{\n\t\t\t// The important half: *future* tables. A grant on what exists today\n\t\t\t// covers nothing the next migration creates, which is how a runtime\n\t\t\t// role silently loses access one deploy later.\n\t\t\tdescribe: `${runtime} may read and write future tables in ${schema}`,\n\t\t\tsql:\n\t\t\t\t`ALTER DEFAULT PRIVILEGES FOR ROLE ${ident(owner)} IN SCHEMA ${ident(schema)} ` +\n\t\t\t\t`GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO ${ident(runtime)}`,\n\t\t},\n\t\t{\n\t\t\tdescribe: `${runtime} may use future sequences in ${schema}`,\n\t\t\tsql:\n\t\t\t\t`ALTER DEFAULT PRIVILEGES FOR ROLE ${ident(owner)} IN SCHEMA ${ident(schema)} ` +\n\t\t\t\t`GRANT USAGE, SELECT ON SEQUENCES TO ${ident(runtime)}`,\n\t\t},\n\t\t{\n\t\t\t// And the tables that are already there, for a schema that existed\n\t\t\t// before its roles did.\n\t\t\tdescribe: `${runtime} may read and write existing tables in ${schema}`,\n\t\t\tsql:\n\t\t\t\t`GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA ${ident(schema)} ` +\n\t\t\t\t`TO ${ident(runtime)}`,\n\t\t},\n\t\t{\n\t\t\tdescribe: `${runtime} may use existing sequences in ${schema}`,\n\t\t\tsql: `GRANT USAGE, SELECT ON ALL SEQUENCES IN SCHEMA ${ident(schema)} TO ${ident(runtime)}`,\n\t\t},\n\t\t{\n\t\t\t// Pinned on the role rather than carried in every URL. A connection\n\t\t\t// string that has to remember `search_path` is one that eventually\n\t\t\t// forgets, and the forgetting looks like an empty database.\n\t\t\tdescribe: `${runtime} resolves names in ${schema}`,\n\t\t\tsql: `ALTER ROLE ${ident(runtime)} SET search_path TO ${ident(schema)}`,\n\t\t},\n\t\t{\n\t\t\tdescribe: `${owner} resolves names in ${schema}`,\n\t\t\tsql: `ALTER ROLE ${ident(owner)} SET search_path TO ${ident(schema)}`,\n\t\t},\n\t\t...(spec.reader ? readerStatements(spec, spec.reader) : []),\n\t];\n}\n\n/**\n * A role that may read and nothing else.\n *\n * `SELECT` and no more, on what exists and on what the owner creates later. No\n * `INSERT`, no `UPDATE`, no `DELETE`, and no sequence `USAGE` — a reader that\n * could take a sequence value could not write the row it was for, so granting\n * it would be surface with no use.\n */\nfunction readerStatements(spec: RoleSpec, reader: string): RoleStatement[] {\n\tconst { owner, schema, passwords } = spec;\n\tconst password = passwords.reader;\n\n\tif (!password) throw new ReaderNeedsPassword(reader);\n\n\treturn [\n\t\t{\n\t\t\tdescribe: `role ${reader}`,\n\t\t\texists: roleExists(reader),\n\t\t\tsql: `CREATE ROLE ${ident(reader)} LOGIN PASSWORD ${literal(password)}`,\n\t\t},\n\t\t{\n\t\t\tdescribe: `${reader} may use ${schema}`,\n\t\t\tsql: `GRANT USAGE ON SCHEMA ${ident(schema)} TO ${ident(reader)}`,\n\t\t},\n\t\t{\n\t\t\tdescribe: `${reader} may read future tables in ${schema}`,\n\t\t\tsql:\n\t\t\t\t`ALTER DEFAULT PRIVILEGES FOR ROLE ${ident(owner)} IN SCHEMA ${ident(schema)} ` +\n\t\t\t\t`GRANT SELECT ON TABLES TO ${ident(reader)}`,\n\t\t},\n\t\t{\n\t\t\tdescribe: `${reader} may read existing tables in ${schema}`,\n\t\t\tsql: `GRANT SELECT ON ALL TABLES IN SCHEMA ${ident(schema)} TO ${ident(reader)}`,\n\t\t},\n\t\t{\n\t\t\tdescribe: `${reader} resolves names in ${schema}`,\n\t\t\tsql: `ALTER ROLE ${ident(reader)} SET search_path TO ${ident(schema)}`,\n\t\t},\n\t];\n}\n\n/** A reader role was named and no password was supplied for it. */\nexport class ReaderNeedsPassword extends Error {\n\tconstructor(readonly role: string) {\n\t\tsuper(\n\t\t\t`'${role}' is a reader role and no password was supplied for it. ` +\n\t\t\t\t`This module composes DDL and invents no secrets: pass ` +\n\t\t\t\t`passwords.reader alongside the role name.`,\n\t\t);\n\t\tthis.name = 'ReaderNeedsPassword';\n\t}\n}\n\n/** The read-only role's name for a given runtime role. */\nexport function readerRole(runtime: string): string {\n\treturn `${runtime}_reader`;\n}\n\n/** The owner role's name for a given runtime role. */\nexport function ownerRole(runtime: string): string {\n\treturn `${runtime}_owner`;\n}\n\nfunction roleExists(role: string): { sql: string; values: unknown[] } {\n\treturn { sql: 'SELECT 1 FROM pg_roles WHERE rolname = $1', values: [role] };\n}\n\n/**\n * Quote an identifier for use in DDL.\n *\n * Names reaching here are already canonical, so this is defence rather than\n * sanitisation — but DDL cannot be parameterised, and an unquoted identifier is\n * the one place a name could ever be more than a name.\n */\nfunction ident(name: string): string {\n\treturn `\"${name.replace(/\"/g, '\"\"')}\"`;\n}\n\n/**\n * Quote a string literal.\n *\n * A password cannot be a bind parameter in `CREATE ROLE`, which is the one\n * place in this module where a value rather than a name is interpolated — so it\n * is escaped rather than trusted, whatever the caller believes it derived.\n */\nfunction literal(value: string): string {\n\treturn `'${value.replace(/'/g, \"''\")}'`;\n}\n"],"mappings":";;;;;;;;AA+DA,SAAgB,eAAeA,MAAiC;CAC/D,MAAM,EAAE,SAAS,OAAO,QAAQ,WAAW,GAAG;AAE9C,QAAO;EACN;GACC,WAAW,OAAO,MAAM;GACxB,QAAQ,WAAW,MAAM;GACzB,MAAM,cAAc,MAAM,MAAM,CAAC,kBAAkB,QAAQ,UAAU,MAAM,CAAC;EAC5E;EACD;GACC,WAAW,OAAO,QAAQ;GAC1B,QAAQ,WAAW,QAAQ;GAC3B,MAAM,cAAc,MAAM,QAAQ,CAAC,kBAAkB,QAAQ,UAAU,QAAQ,CAAC;EAChF;EACD;GASC,WAAW,EAAE,MAAM;GACnB,MAAM,QAAQ,MAAM,MAAM,CAAC;EAC3B;EACD;GACC,WAAW,SAAS,OAAO;GAC3B,QAAQ;IACP,KAAK;IACL,QAAQ,CAAC,MAAO;GAChB;GAID,MAAM,gBAAgB,MAAM,OAAO,CAAC,iBAAiB,MAAM,MAAM,CAAC;EAClE;EACD;GAWC,WAAW,EAAE,OAAO,eAAe,MAAM;GACzC,MAAM,eAAe,MAAM,OAAO,CAAC,YAAY,MAAM,MAAM,CAAC;EAC5D;EACD;GACC,WAAW,EAAE,QAAQ,WAAW,OAAO;GACvC,MAAM,wBAAwB,MAAM,OAAO,CAAC,MAAM,MAAM,QAAQ,CAAC;EACjE;EACD;GAIC,WAAW,EAAE,QAAQ,uCAAuC,OAAO;GACnE,MACE,oCAAoC,MAAM,MAAM,CAAC,aAAa,MAAM,OAAO,CAAC,qDACxB,MAAM,QAAQ,CAAC;EACrE;EACD;GACC,WAAW,EAAE,QAAQ,+BAA+B,OAAO;GAC3D,MACE,oCAAoC,MAAM,MAAM,CAAC,aAAa,MAAM,OAAO,CAAC,uCACtC,MAAM,QAAQ,CAAC;EACvD;EACD;GAGC,WAAW,EAAE,QAAQ,yCAAyC,OAAO;GACrE,MACE,+DAA+D,MAAM,OAAO,CAAC,MACxE,MAAM,QAAQ,CAAC;EACtB;EACD;GACC,WAAW,EAAE,QAAQ,iCAAiC,OAAO;GAC7D,MAAM,iDAAiD,MAAM,OAAO,CAAC,MAAM,MAAM,QAAQ,CAAC;EAC1F;EACD;GAIC,WAAW,EAAE,QAAQ,qBAAqB,OAAO;GACjD,MAAM,aAAa,MAAM,QAAQ,CAAC,sBAAsB,MAAM,OAAO,CAAC;EACtE;EACD;GACC,WAAW,EAAE,MAAM,qBAAqB,OAAO;GAC/C,MAAM,aAAa,MAAM,MAAM,CAAC,sBAAsB,MAAM,OAAO,CAAC;EACpE;EACD,GAAI,KAAK,SAAS,iBAAiB,MAAM,KAAK,OAAO,GAAG,CAAE;CAC1D;AACD;;;;;;;;;AAUD,SAAS,iBAAiBA,MAAgBC,QAAiC;CAC1E,MAAM,EAAE,OAAO,QAAQ,WAAW,GAAG;CACrC,MAAM,WAAW,UAAU;AAE3B,MAAK,SAAU,OAAM,IAAI,oBAAoB;AAE7C,QAAO;EACN;GACC,WAAW,OAAO,OAAO;GACzB,QAAQ,WAAW,OAAO;GAC1B,MAAM,cAAc,MAAM,OAAO,CAAC,kBAAkB,QAAQ,SAAS,CAAC;EACtE;EACD;GACC,WAAW,EAAE,OAAO,WAAW,OAAO;GACtC,MAAM,wBAAwB,MAAM,OAAO,CAAC,MAAM,MAAM,OAAO,CAAC;EAChE;EACD;GACC,WAAW,EAAE,OAAO,6BAA6B,OAAO;GACxD,MACE,oCAAoC,MAAM,MAAM,CAAC,aAAa,MAAM,OAAO,CAAC,6BAChD,MAAM,OAAO,CAAC;EAC5C;EACD;GACC,WAAW,EAAE,OAAO,+BAA+B,OAAO;GAC1D,MAAM,uCAAuC,MAAM,OAAO,CAAC,MAAM,MAAM,OAAO,CAAC;EAC/E;EACD;GACC,WAAW,EAAE,OAAO,qBAAqB,OAAO;GAChD,MAAM,aAAa,MAAM,OAAO,CAAC,sBAAsB,MAAM,OAAO,CAAC;EACrE;CACD;AACD;;AAGD,IAAa,sBAAb,cAAyC,MAAM;CAC9C,YAAqBC,MAAc;AAClC,SACE,GAAG,KAAK,yJAGT;EALmB;AAMpB,OAAK,OAAO;CACZ;AACD;;AAGD,SAAgB,WAAWC,SAAyB;AACnD,SAAQ,EAAE,QAAQ;AAClB;;AAGD,SAAgB,UAAUA,SAAyB;AAClD,SAAQ,EAAE,QAAQ;AAClB;AAED,SAAS,WAAWD,MAAkD;AACrE,QAAO;EAAE,KAAK;EAA6C,QAAQ,CAAC,IAAK;CAAE;AAC3E;;;;;;;;AASD,SAAS,MAAME,MAAsB;AACpC,SAAQ,GAAG,KAAK,QAAQ,MAAM,OAAK,CAAC;AACpC;;;;;;;;AASD,SAAS,QAAQC,OAAuB;AACvC,SAAQ,GAAG,MAAM,QAAQ,MAAM,KAAK,CAAC;AACrC"}

package/dist/pg/url.cjs

@@ -0,0 +1,33 @@
+const require_errors = require('../errors-Cs5jlAv-.cjs');
+
+//#region src/pg/url.ts
+const SCHEME = "postgres:";
+const DEFAULT_PORT = 5432;
+/**
+* `search_path` travels as a libpq connection option, not a query parameter.
+* The server reads `options`; a plain `?search_path=app` is accepted by the URL
+* parser, ignored by the server, and produces a database that looks empty.
+* The `-c` prefix is what makes it a runtime configuration setting.
+*/
+function searchPathOption(schema) {
+	return `-c search_path=${schema}`;
+}
+/** Compose an address into a connection string. */
+function build(address) {
+	const { host, port, database, username, password, searchPath, ssl } = address;
+	if (!host) throw new require_errors.MissingDatabaseHost();
+	if (!database) throw new require_errors.MissingDatabaseName();
+	const url = new URL(`${SCHEME}//`);
+	url.hostname = host;
+	if (port && port !== DEFAULT_PORT) url.port = String(port);
+	if (username) url.username = encodeURIComponent(username);
+	if (password) url.password = encodeURIComponent(password);
+	url.pathname = `/${database}`;
+	if (searchPath) url.searchParams.set("options", searchPathOption(searchPath));
+	if (ssl === false) url.searchParams.set("sslmode", "disable");
+	return url.toString();
+}
+
+//#endregion
+exports.build = build;
+//# sourceMappingURL=url.cjs.map

package/dist/pg/url.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"url.cjs","names":["schema: string","address: PostgresAddress","MissingDatabaseHost","MissingDatabaseName"],"sources":["../../src/pg/url.ts"],"sourcesContent":["/**\n * Composing a `postgres://` connection string.\n *\n * One direction only. Parsing exists in `pg` already — every consumer hands the\n * string straight to `new Pool({ connectionString })` — so a parser here would\n * be surface whose only caller is its own round-trip test.\n *\n * What is *not* already solved is composition: a provisioned instance exposes\n * host, port, database, username, and password as five separate values, and the\n * construct reads one URL. Doing that join by hand is where `search_path`\n * quietly goes missing.\n *\n * A URL built here is a secret — it carries the role's password. See\n * {@link redactDatabaseUrl} before writing one anywhere.\n */\n\nimport { MissingDatabaseHost, MissingDatabaseName } from '../errors';\n\n/** What a Postgres connection string addresses. */\nexport interface PostgresAddress {\n\thost: string;\n\tport?: number;\n\t/** The logical database. */\n\tdatabase: string;\n\t/** The role connecting — which is what decides DDL versus DML. */\n\tusername?: string;\n\tpassword?: string;\n\t/**\n\t * The schema to resolve unqualified names against.\n\t *\n\t * Normally pinned on the *role* instead (`ALTER ROLE … SET search_path`), so\n\t * it does not appear in the URL at all. It is carried here for the one case\n\t * with no role of its own to pin — connecting as the cluster master under\n\t * `roles: false` — where without it every query looks in `public`.\n\t *\n\t * Postgres-specific by nature, not just by spelling: it becomes a libpq\n\t * connection option, and no other engine accepts one. MySQL has no schemas\n\t * distinct from databases at all.\n\t */\n\tsearchPath?: string;\n\t/** Off only for local development, where there is no certificate to verify. */\n\tssl?: boolean;\n}\n\nconst SCHEME = 'postgres:';\n\nconst DEFAULT_PORT = 5432;\n\n/**\n * `search_path` travels as a libpq connection option, not a query parameter.\n * The server reads `options`; a plain `?search_path=app` is accepted by the URL\n * parser, ignored by the server, and produces a database that looks empty.\n * The `-c` prefix is what makes it a runtime configuration setting.\n */\nfunction searchPathOption(schema: string): string {\n\treturn `-c search_path=${schema}`;\n}\n\n/** Compose an address into a connection string. */\nexport function build(address: PostgresAddress): string {\n\tconst { host, port, database, username, password, searchPath, ssl } = address;\n\n\tif (!host) throw new MissingDatabaseHost();\n\tif (!database) throw new MissingDatabaseName();\n\n\tconst url = new URL(`${SCHEME}//`);\n\turl.hostname = host;\n\tif (port && port !== DEFAULT_PORT) url.port = String(port);\n\t// Username before password: WHATWG URL drops a password set without one.\n\tif (username) url.username = encodeURIComponent(username);\n\tif (password) url.password = encodeURIComponent(password);\n\turl.pathname = `/${database}`;\n\n\tif (searchPath) url.searchParams.set('options', searchPathOption(searchPath));\n\tif (ssl === false) url.searchParams.set('sslmode', 'disable');\n\n\treturn url.toString();\n}\n"],"mappings":";;;AA4CA,MAAM,SAAS;AAEf,MAAM,eAAe;;;;;;;AAQrB,SAAS,iBAAiBA,QAAwB;AACjD,SAAQ,iBAAiB,OAAO;AAChC;;AAGD,SAAgB,MAAMC,SAAkC;CACvD,MAAM,EAAE,MAAM,MAAM,UAAU,UAAU,UAAU,YAAY,KAAK,GAAG;AAEtE,MAAK,KAAM,OAAM,IAAIC;AACrB,MAAK,SAAU,OAAM,IAAIC;CAEzB,MAAM,MAAM,IAAI,KAAK,EAAE,OAAO;AAC9B,KAAI,WAAW;AACf,KAAI,QAAQ,SAAS,aAAc,KAAI,OAAO,OAAO,KAAK;AAE1D,KAAI,SAAU,KAAI,WAAW,mBAAmB,SAAS;AACzD,KAAI,SAAU,KAAI,WAAW,mBAAmB,SAAS;AACzD,KAAI,YAAY,GAAG,SAAS;AAE5B,KAAI,WAAY,KAAI,aAAa,IAAI,WAAW,iBAAiB,WAAW,CAAC;AAC7E,KAAI,QAAQ,MAAO,KAAI,aAAa,IAAI,WAAW,UAAU;AAE7D,QAAO,IAAI,UAAU;AACrB"}

package/dist/pg/url.d.cts

@@ -0,0 +1,47 @@
+//#region src/pg/url.d.ts
+/**
+ * Composing a `postgres://` connection string.
+ *
+ * One direction only. Parsing exists in `pg` already — every consumer hands the
+ * string straight to `new Pool({ connectionString })` — so a parser here would
+ * be surface whose only caller is its own round-trip test.
+ *
+ * What is *not* already solved is composition: a provisioned instance exposes
+ * host, port, database, username, and password as five separate values, and the
+ * construct reads one URL. Doing that join by hand is where `search_path`
+ * quietly goes missing.
+ *
+ * A URL built here is a secret — it carries the role's password. See
+ * {@link redactDatabaseUrl} before writing one anywhere.
+ */
+/** What a Postgres connection string addresses. */
+interface PostgresAddress {
+  host: string;
+  port?: number;
+  /** The logical database. */
+  database: string;
+  /** The role connecting — which is what decides DDL versus DML. */
+  username?: string;
+  password?: string;
+  /**
+   * The schema to resolve unqualified names against.
+   *
+   * Normally pinned on the *role* instead (`ALTER ROLE … SET search_path`), so
+   * it does not appear in the URL at all. It is carried here for the one case
+   * with no role of its own to pin — connecting as the cluster master under
+   * `roles: false` — where without it every query looks in `public`.
+   *
+   * Postgres-specific by nature, not just by spelling: it becomes a libpq
+   * connection option, and no other engine accepts one. MySQL has no schemas
+   * distinct from databases at all.
+   */
+  searchPath?: string;
+  /** Off only for local development, where there is no certificate to verify. */
+  ssl?: boolean;
+}
+/** Compose an address into a connection string. */
+declare function build(address: PostgresAddress): string;
+//# sourceMappingURL=url.d.ts.map
+//#endregion
+export { PostgresAddress, build };
+//# sourceMappingURL=url.d.cts.map

package/dist/pg/url.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"url.d.cts","names":[],"sources":["../../src/pg/url.ts"],"sourcesContent":[],"mappings":";;AAmBA;AAwCA;;;;;;;;;;;;;;UAxCiB,eAAA;;;;;;;;;;;;;;;;;;;;;;;;;iBAwCD,KAAA,UAAe"}

package/dist/pg/url.d.mts

@@ -0,0 +1,47 @@
+//#region src/pg/url.d.ts
+/**
+ * Composing a `postgres://` connection string.
+ *
+ * One direction only. Parsing exists in `pg` already — every consumer hands the
+ * string straight to `new Pool({ connectionString })` — so a parser here would
+ * be surface whose only caller is its own round-trip test.
+ *
+ * What is *not* already solved is composition: a provisioned instance exposes
+ * host, port, database, username, and password as five separate values, and the
+ * construct reads one URL. Doing that join by hand is where `search_path`
+ * quietly goes missing.
+ *
+ * A URL built here is a secret — it carries the role's password. See
+ * {@link redactDatabaseUrl} before writing one anywhere.
+ */
+/** What a Postgres connection string addresses. */
+interface PostgresAddress {
+  host: string;
+  port?: number;
+  /** The logical database. */
+  database: string;
+  /** The role connecting — which is what decides DDL versus DML. */
+  username?: string;
+  password?: string;
+  /**
+   * The schema to resolve unqualified names against.
+   *
+   * Normally pinned on the *role* instead (`ALTER ROLE … SET search_path`), so
+   * it does not appear in the URL at all. It is carried here for the one case
+   * with no role of its own to pin — connecting as the cluster master under
+   * `roles: false` — where without it every query looks in `public`.
+   *
+   * Postgres-specific by nature, not just by spelling: it becomes a libpq
+   * connection option, and no other engine accepts one. MySQL has no schemas
+   * distinct from databases at all.
+   */
+  searchPath?: string;
+  /** Off only for local development, where there is no certificate to verify. */
+  ssl?: boolean;
+}
+/** Compose an address into a connection string. */
+declare function build(address: PostgresAddress): string;
+//# sourceMappingURL=url.d.ts.map
+//#endregion
+export { PostgresAddress, build };
+//# sourceMappingURL=url.d.mts.map

package/dist/pg/url.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"url.d.mts","names":[],"sources":["../../src/pg/url.ts"],"sourcesContent":[],"mappings":";;AAmBA;AAwCA;;;;;;;;;;;;;;UAxCiB,eAAA;;;;;;;;;;;;;;;;;;;;;;;;;iBAwCD,KAAA,UAAe"}

package/dist/pg/url.mjs

@@ -0,0 +1,33 @@
+import { MissingDatabaseHost, MissingDatabaseName } from "../errors-CfFCan-X.mjs";
+
+//#region src/pg/url.ts
+const SCHEME = "postgres:";
+const DEFAULT_PORT = 5432;
+/**
+* `search_path` travels as a libpq connection option, not a query parameter.
+* The server reads `options`; a plain `?search_path=app` is accepted by the URL
+* parser, ignored by the server, and produces a database that looks empty.
+* The `-c` prefix is what makes it a runtime configuration setting.
+*/
+function searchPathOption(schema) {
+	return `-c search_path=${schema}`;
+}
+/** Compose an address into a connection string. */
+function build(address) {
+	const { host, port, database, username, password, searchPath, ssl } = address;
+	if (!host) throw new MissingDatabaseHost();
+	if (!database) throw new MissingDatabaseName();
+	const url = new URL(`${SCHEME}//`);
+	url.hostname = host;
+	if (port && port !== DEFAULT_PORT) url.port = String(port);
+	if (username) url.username = encodeURIComponent(username);
+	if (password) url.password = encodeURIComponent(password);
+	url.pathname = `/${database}`;
+	if (searchPath) url.searchParams.set("options", searchPathOption(searchPath));
+	if (ssl === false) url.searchParams.set("sslmode", "disable");
+	return url.toString();
+}
+
+//#endregion
+export { build };
+//# sourceMappingURL=url.mjs.map

package/dist/pg/url.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"url.mjs","names":["schema: string","address: PostgresAddress"],"sources":["../../src/pg/url.ts"],"sourcesContent":["/**\n * Composing a `postgres://` connection string.\n *\n * One direction only. Parsing exists in `pg` already — every consumer hands the\n * string straight to `new Pool({ connectionString })` — so a parser here would\n * be surface whose only caller is its own round-trip test.\n *\n * What is *not* already solved is composition: a provisioned instance exposes\n * host, port, database, username, and password as five separate values, and the\n * construct reads one URL. Doing that join by hand is where `search_path`\n * quietly goes missing.\n *\n * A URL built here is a secret — it carries the role's password. See\n * {@link redactDatabaseUrl} before writing one anywhere.\n */\n\nimport { MissingDatabaseHost, MissingDatabaseName } from '../errors';\n\n/** What a Postgres connection string addresses. */\nexport interface PostgresAddress {\n\thost: string;\n\tport?: number;\n\t/** The logical database. */\n\tdatabase: string;\n\t/** The role connecting — which is what decides DDL versus DML. */\n\tusername?: string;\n\tpassword?: string;\n\t/**\n\t * The schema to resolve unqualified names against.\n\t *\n\t * Normally pinned on the *role* instead (`ALTER ROLE … SET search_path`), so\n\t * it does not appear in the URL at all. It is carried here for the one case\n\t * with no role of its own to pin — connecting as the cluster master under\n\t * `roles: false` — where without it every query looks in `public`.\n\t *\n\t * Postgres-specific by nature, not just by spelling: it becomes a libpq\n\t * connection option, and no other engine accepts one. MySQL has no schemas\n\t * distinct from databases at all.\n\t */\n\tsearchPath?: string;\n\t/** Off only for local development, where there is no certificate to verify. */\n\tssl?: boolean;\n}\n\nconst SCHEME = 'postgres:';\n\nconst DEFAULT_PORT = 5432;\n\n/**\n * `search_path` travels as a libpq connection option, not a query parameter.\n * The server reads `options`; a plain `?search_path=app` is accepted by the URL\n * parser, ignored by the server, and produces a database that looks empty.\n * The `-c` prefix is what makes it a runtime configuration setting.\n */\nfunction searchPathOption(schema: string): string {\n\treturn `-c search_path=${schema}`;\n}\n\n/** Compose an address into a connection string. */\nexport function build(address: PostgresAddress): string {\n\tconst { host, port, database, username, password, searchPath, ssl } = address;\n\n\tif (!host) throw new MissingDatabaseHost();\n\tif (!database) throw new MissingDatabaseName();\n\n\tconst url = new URL(`${SCHEME}//`);\n\turl.hostname = host;\n\tif (port && port !== DEFAULT_PORT) url.port = String(port);\n\t// Username before password: WHATWG URL drops a password set without one.\n\tif (username) url.username = encodeURIComponent(username);\n\tif (password) url.password = encodeURIComponent(password);\n\turl.pathname = `/${database}`;\n\n\tif (searchPath) url.searchParams.set('options', searchPathOption(searchPath));\n\tif (ssl === false) url.searchParams.set('sslmode', 'disable');\n\n\treturn url.toString();\n}\n"],"mappings":";;;AA4CA,MAAM,SAAS;AAEf,MAAM,eAAe;;;;;;;AAQrB,SAAS,iBAAiBA,QAAwB;AACjD,SAAQ,iBAAiB,OAAO;AAChC;;AAGD,SAAgB,MAAMC,SAAkC;CACvD,MAAM,EAAE,MAAM,MAAM,UAAU,UAAU,UAAU,YAAY,KAAK,GAAG;AAEtE,MAAK,KAAM,OAAM,IAAI;AACrB,MAAK,SAAU,OAAM,IAAI;CAEzB,MAAM,MAAM,IAAI,KAAK,EAAE,OAAO;AAC9B,KAAI,WAAW;AACf,KAAI,QAAQ,SAAS,aAAc,KAAI,OAAO,OAAO,KAAK;AAE1D,KAAI,SAAU,KAAI,WAAW,mBAAmB,SAAS;AACzD,KAAI,SAAU,KAAI,WAAW,mBAAmB,SAAS;AACzD,KAAI,YAAY,GAAG,SAAS;AAE5B,KAAI,WAAY,KAAI,aAAa,IAAI,WAAW,iBAAiB,WAAW,CAAC;AAC7E,KAAI,QAAQ,MAAO,KAAI,aAAa,IAAI,WAAW,UAAU;AAE7D,QAAO,IAAI,UAAU;AACrB"}

package/dist/rls.cjs

@@ -21,7 +21,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 }) : target, mod));
 
 //#endregion
-const require_kysely = require('./kysely-8WPSKCZG.cjs');
+const require_kysely = require('./kysely-LWvS2ekY.cjs');
 const kysely = __toESM(require("kysely"));
 
 //#region src/rls.ts

package/dist/rls.d.mts

@@ -1,4 +1,4 @@
-import { DatabaseConnection, TransactionSettings } from "./kysely-Dm1w5gAY.mjs";
+import { DatabaseConnection, TransactionSettings } from "./kysely-BAedYsvn.mjs";
 import { Transaction } from "kysely";
 
 //#region src/rls.d.ts

package/dist/rls.mjs

@@ -1,4 +1,4 @@
-import { withTransaction } from "./kysely-DmfA94RY.mjs";
+import { withTransaction } from "./kysely-Bo_Zg-D3.mjs";
 import { sql } from "kysely";
 
 //#region src/rls.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geekmidas/db",
-  "version": "1.1.1",
+  "version": "10.0.0-alpha.0",
   "private": false,
   "type": "module",
   "exports": {
@@ -53,8 +53,41 @@
         "types": "./dist/rls.d.cts",
         "default": "./dist/rls.cjs"
       }
+    },
+    "./pg/url": {
+      "import": {
+        "types": "./dist/pg/url.d.mts",
+        "default": "./dist/pg/url.mjs"
+      },
+      "require": {
+        "types": "./dist/pg/url.d.cts",
+        "default": "./dist/pg/url.cjs"
+      }
+    },
+    "./pg/roles": {
+      "import": {
+        "types": "./dist/pg/roles.d.mts",
+        "default": "./dist/pg/roles.mjs"
+      },
+      "require": {
+        "types": "./dist/pg/roles.d.cts",
+        "default": "./dist/pg/roles.cjs"
+      }
+    },
+    "./errors": {
+      "import": {
+        "types": "./dist/errors.d.mts",
+        "default": "./dist/errors.mjs"
+      },
+      "require": {
+        "types": "./dist/errors.d.cts",
+        "default": "./dist/errors.cjs"
+      }
     }
   },
+  "files": [
+    "dist"
+  ],
   "dependencies": {
     "@faker-js/faker": "~9.9.0"
   },