@decohere/data-postgres 0.0.0-stage → 0.0.1-dev.5

package/README.md

@@ -1,3 +1,25 @@
-# Temporary Holding Version
+# @decohere/data-postgres
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Everything in Decohere's data layer that only Postgres needs. An app installs it when its database is Postgres; the scaffold does this for you.
+
+## Setting up a data source at startup
+
+```ts
+import { postgres } from "@decohere/data-postgres";
+
+builder.use(mikroOrm({ entities, bootstrap: postgres.bootstrap })); // or typeOrm({ … })
+```
+
+Before the provider connects, `postgres.bootstrap` does what each data source's config asks:
+- creates the database;
+- creates an app role and an optional migrate role;
+- creates the schema;
+- grants each role only what it needs.
+
+Data sources on one server and database are set up once, in order, and running it again changes nothing. The rules (`bootstrap`, `auth: trust`, the admin and migrate roles) are in [ADR 0011](../../../docs/adr/0011-database-bootstrap.md).
+
+A runner or script that opens its own connection can call `bootstrapDataSources(dataSources, { applicationName })` directly.
+
+## What else goes here
+
+Postgres-only code in general, as it's built: the migration runner's advisory lock and history table, and starting a development Postgres on demand. Another database would get a package of its own with the same shape.

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "@decohere/data-postgres",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.1-dev.5",
+  "description": "Postgres for @decohere/data: creates a data source's database, least-privilege roles and schema at startup",
+  "keywords": [
+    "typescript",
+    "postgres",
+    "data-access",
+    "decohere"
+  ],
+  "homepage": "https://github.com/typesmiths/decohere/tree/main/projects/data/data-postgres#readme",
+  "bugs": {
+    "url": "https://github.com/typesmiths/decohere/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/typesmiths/decohere.git",
+    "directory": "projects/data/data-postgres"
+  },
+  "license": "ISC",
+  "author": "Typesmiths",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./types/src/index.d.ts",
+      "import": "./es6/src/index.js"
+    }
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "dependencies": {
+    "@decohere/data": "0.0.1-dev.5",
+    "pg": "^8.23.1"
+  },
+  "devDependencies": {}
+}

package/src/bootstrap.ts

@@ -0,0 +1,82 @@
+import {
+	assertBootstrapCredentials,
+	assertDataSourceAuth,
+	assertSynchronizeAllowed,
+	type ConnectionInfo,
+	DataConfigurationError,
+	shouldBootstrapDatabase,
+} from "@decohere/data";
+import { PostgresServerManager } from "./server-manager.js";
+
+export type BootstrapDataSourcesOptions = {
+	/** Shown as `application_name` on the bootstrap connections. */
+	applicationName: string;
+	/** Defaults to `process.env.NODE_ENV`. Decides whether `auth: trust` and `synchronize` are allowed. */
+	nodeEnv?: string;
+};
+
+/** What every data source on one server and database must agree on. */
+const SHARED_FIELDS = ["auth", "adminUser", "migrateUsername"] as const;
+
+/**
+ * Check every data source's auth and `synchronize`, then create the databases, roles and schemas of those that
+ * bootstrap. Data sources on the same server and database are bootstrapped once, one after the
+ * other: in parallel they would race to create the same database and roles. Running it again
+ * changes nothing.
+ *
+ * Pass it to a provider as `bootstrap: postgres.bootstrap`; runners and scripts that open their own
+ * connection can call it directly.
+ */
+export async function bootstrapDataSources(
+	dataSources: readonly ConnectionInfo[],
+	options: BootstrapDataSourcesOptions,
+): Promise<void> {
+	const nodeEnv = options.nodeEnv ?? process.env.NODE_ENV;
+	for (const info of dataSources) {
+		assertDataSourceAuth(info, nodeEnv);
+		assertSynchronizeAllowed(info, nodeEnv);
+	}
+
+	const toBootstrap = dataSources.filter((info) => shouldBootstrapDatabase(info, nodeEnv));
+	for (const info of toBootstrap) assertBootstrapCredentials(info);
+
+	for (const group of byServerAndDatabase(toBootstrap)) {
+		const [first] = group;
+		await using server = new PostgresServerManager(options.applicationName, first);
+		await server.connect();
+		await server.initializeDatabase(first.database);
+		for (const info of group) {
+			await server.provisionRoles({
+				database: info.database,
+				appUsername: info.username,
+				appPassword: info.password,
+				migrateUsername: info.migrateUsername,
+				migratePassword: info.migratePassword,
+				allowAppDdl: info.synchronize === true,
+				schema: info.schema,
+			});
+		}
+	}
+}
+
+function byServerAndDatabase(dataSources: readonly ConnectionInfo[]): ConnectionInfo[][] {
+	const groups = new Map<string, ConnectionInfo[]>();
+	for (const info of dataSources) {
+		const key = `${info.host}:${info.port}/${info.database}`;
+		const group = groups.get(key);
+		if (group == null) {
+			groups.set(key, [info]);
+			continue;
+		}
+		const [first] = group;
+		for (const field of SHARED_FIELDS) {
+			if (info[field] !== first[field]) {
+				throw new DataConfigurationError(
+					`Data sources "${first.name}" and "${info.name}" share database ${key} but set different ${field} (${JSON.stringify(first[field])} and ${JSON.stringify(info[field])})`,
+				);
+			}
+		}
+		group.push(info);
+	}
+	return [...groups.values()];
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+// Everything Postgres-only in Decohere's data layer. Today: creating a data source's database,
+// least-privilege roles and schema at startup, which a provider runs when it is passed
+// `bootstrap: postgres.bootstrap`.
+import { bootstrapDataSources } from "./bootstrap.js";
+
+export * from "./bootstrap.js";
+
+export const postgres = { bootstrap: bootstrapDataSources };

package/src/server-manager.ts

@@ -0,0 +1,300 @@
+import { type ConnectionInfo, DataConfigurationError } from "@decohere/data";
+import { Pool } from "pg";
+import {
+	alterDatabaseOwnerQuery,
+	createSchemaQuery,
+	createUserQuery,
+	databaseOwnerQuery,
+	defaultPrivilegesForAppQueries,
+	grantConnectQuery,
+	grantRoleMembershipQuery,
+	grantSchemaCreateQuery,
+	grantSchemaPrivilegesQuery,
+	grantSchemaUsageQuery,
+	hasDatabasePrivilegeQuery,
+	hasRolePrivilegesQuery,
+	hasSchemaPrivilegeQuery,
+	quoteIdent,
+	revokeRoleMembershipQuery,
+	roleExistsQuery,
+	type SqlQuery,
+} from "./user-scripts.js";
+
+export type ProvisionRolesOptions = {
+	database: string;
+	appUsername: string;
+	/** Omit only when the server is declared `auth: trust`. */
+	appPassword?: string;
+	migrateUsername?: string;
+	migratePassword?: string;
+	/** When true (TypeORM synchronize), grant CREATE on the schema to the app role (dev only). */
+	allowAppDdl: boolean;
+	/** The schema the app role works in, created when missing. Default `public`. */
+	schema?: string;
+};
+
+/**
+ * Official Postgres images always have this DB. `pg` defaults an omitted
+ * `database` to the username — bootstrap roles like `decohere_bootstrap` are
+ * not databases, so connect here before CREATE DATABASE.
+ */
+const MAINTENANCE_DATABASE = "postgres";
+
+export class PostgresServerManager {
+	private pool: Pool;
+	private client: import("pg").PoolClient;
+
+	public constructor(
+		private readonly applicationName: string,
+		private readonly config: ConnectionInfo,
+	) {}
+
+	/** `auth: trust`: the server lets every connection in, so roles have no password. */
+	private get trusted(): boolean {
+		return this.config.auth === "trust";
+	}
+
+	public async connect() {
+		const { adminUser, adminPassword, host, port } = this.config;
+		if (!adminUser || (!adminPassword && !this.trusted)) {
+			throw new DataConfigurationError(
+				`Data source "${this.config.name}": adminUser and adminPassword are required to bootstrap the database (adminPassword may be left out only with auth: trust)`,
+			);
+		}
+		this.pool = new Pool({
+			user: adminUser,
+			host,
+			password: adminPassword,
+			port,
+			database: MAINTENANCE_DATABASE,
+			application_name: this.applicationName,
+		});
+		try {
+			this.client = await this.pool.connect();
+		} catch (err) {
+			const cause = err instanceof Error ? err.message : String(err);
+			throw new DataConfigurationError(
+				`Cannot connect to PostgreSQL at ${host}:${port}. Is the server running? Cause: ${cause}`,
+			);
+		}
+	}
+
+	public async initializeDatabase(database: string) {
+		quoteIdent(database, "database");
+		const result = await this.pool.query(
+			`SELECT datname FROM pg_catalog.pg_database WHERE lower(datname) = lower($1)`,
+			[database],
+		);
+		if (result.rowCount === 1) {
+			return;
+		}
+
+		const dbIdent = quoteIdent(database, "database");
+		await this.pool.query(`CREATE DATABASE ${dbIdent}`);
+	}
+
+	/**
+	 * Create the runtime app role (+ optional migrate role) and its schema, with least-privilege
+	 * grants. Running it again changes nothing: each grant is made only where the role lacks it,
+	 * since Postgres checks the grantor's rights even for a grant that would change nothing.
+	 *
+	 * The admin acts with the database owner's rights while it runs (it is made a member of the
+	 * owner, and of the migrate role, only for as long as it needs to be). That is how it creates a
+	 * schema and grants on it once the migrate role owns the database.
+	 */
+	public async provisionRoles(options: ProvisionRolesOptions): Promise<void> {
+		const {
+			database,
+			appUsername,
+			appPassword,
+			migrateUsername,
+			migratePassword,
+			allowAppDdl,
+			schema = "public",
+		} = options;
+		quoteIdent(schema, "schema");
+
+		if (appUsername === this.config.adminUser) {
+			throw new DataConfigurationError(
+				`Runtime username "${appUsername}" must not equal adminUser — use a dedicated app role`,
+			);
+		}
+		if (migrateUsername && migrateUsername === appUsername) {
+			throw new DataConfigurationError(
+				"migrateUsername must differ from the runtime app username",
+			);
+		}
+		if (migrateUsername && migrateUsername === this.config.adminUser) {
+			throw new DataConfigurationError("migrateUsername must not equal adminUser");
+		}
+
+		const adminUser = this.config.adminUser;
+		if (!adminUser) {
+			throw new DataConfigurationError("adminUser is required to provision database roles");
+		}
+
+		const pool = new Pool({
+			host: this.config.host,
+			port: this.config.port,
+			user: adminUser,
+			database,
+			password: this.config.adminPassword,
+			application_name: this.applicationName,
+		});
+
+		try {
+			await using roles = new BorrowedRoles(pool, adminUser);
+
+			if (migrateUsername) {
+				await this.ensureRole(pool, migrateUsername, migratePassword);
+				// Membership is required for OWNER TO and DEFAULT PRIVILEGES FOR ROLE (not superuser).
+				await roles.borrow(migrateUsername);
+				// The owner holds every privilege on the database, so no separate GRANT is needed.
+				if ((await databaseOwner(pool, database)) !== migrateUsername) {
+					await pool.query(alterDatabaseOwnerQuery(database, migrateUsername).text);
+				}
+			}
+
+			const owner = await databaseOwner(pool, database);
+			if (owner !== adminUser) await roles.borrow(owner);
+
+			// Owned by the database owner (the migrate role, when there is one), like `public`.
+			await pool.query(createSchemaQuery(schema, owner).text);
+
+			if (
+				migrateUsername &&
+				!(await hasAll(pool, (privilege) =>
+					hasSchemaPrivilegeQuery(migrateUsername, schema, privilege),
+				))
+			) {
+				await pool.query(grantSchemaPrivilegesQuery(migrateUsername, schema).text);
+			}
+
+			await this.ensureRole(pool, appUsername, appPassword);
+			if (
+				!(await granted(pool, hasDatabasePrivilegeQuery(appUsername, database, "CONNECT")))
+			) {
+				await pool.query(grantConnectQuery(appUsername, database).text);
+			}
+			if (!(await granted(pool, hasSchemaPrivilegeQuery(appUsername, schema, "USAGE")))) {
+				await pool.query(grantSchemaUsageQuery(appUsername, schema).text);
+			}
+			// Dev synchronize: the app connection must be able to CREATE tables.
+			if (
+				allowAppDdl &&
+				!(await granted(pool, hasSchemaPrivilegeQuery(appUsername, schema, "CREATE")))
+			) {
+				await pool.query(grantSchemaCreateQuery(appUsername, schema).text);
+			}
+
+			if (migrateUsername) {
+				// Setting a default privilege that is already set changes nothing.
+				for (const q of defaultPrivilegesForAppQueries(migrateUsername, appUsername, schema)) {
+					await pool.query(q.text);
+				}
+			}
+		} finally {
+			await pool.end();
+		}
+	}
+
+	/** @deprecated Use provisionRoles. */
+	public async createApiUser(
+		username: string,
+		password: string,
+		database: string,
+		_role?: string,
+	) {
+		await this.provisionRoles({
+			database,
+			appUsername: username,
+			appPassword: password,
+			migrateUsername: this.config.migrateUsername,
+			migratePassword: this.config.migratePassword,
+			allowAppDdl: this.config.synchronize === true,
+			schema: this.config.schema,
+		});
+	}
+
+	private async ensureRole(pool: Pool, username: string, password?: string): Promise<void> {
+		if (!password && !this.trusted) {
+			throw new DataConfigurationError(
+				`A password is required for database role "${username}" unless the data source sets auth: trust`,
+			);
+		}
+		const exists = roleExistsQuery(username);
+		const found = await pool.query(exists.text, exists.values);
+		if (found.rowCount === 1) {
+			return;
+		}
+		const create = createUserQuery(username, password);
+		await pool.query(create.text, create.values);
+	}
+
+	public [Symbol.asyncDispose]() {
+		return this.closeConnection();
+	}
+
+	public async closeConnection() {
+		this.client?.release();
+		await this.pool?.end();
+	}
+}
+
+async function granted(pool: Pool, query: SqlQuery): Promise<boolean> {
+	const result = await pool.query(query.text, query.values);
+	return result.rows[0]?.granted === true;
+}
+
+/** Every schema privilege that `GRANT ALL ON SCHEMA` gives. Checked one at a time: Postgres
+ * answers true for a list when any one of them is held. */
+async function hasAll(pool: Pool, query: (privilege: string) => SqlQuery): Promise<boolean> {
+	for (const privilege of ["USAGE", "CREATE"]) {
+		if (!(await granted(pool, query(privilege)))) return false;
+	}
+	return true;
+}
+
+async function databaseOwner(pool: Pool, database: string): Promise<string> {
+	const query = databaseOwnerQuery(database);
+	const result = await pool.query(query.text, query.values);
+	const owner: string | undefined = result.rows[0]?.owner;
+	if (owner == null) {
+		throw new DataConfigurationError(`Database "${database}" does not exist`);
+	}
+	return owner;
+}
+
+/**
+ * Roles the admin is made a member of for one provisioning run, so it acts with their rights.
+ * Disposing gives back exactly what was borrowed, even when the run fails: memberships the admin
+ * already had (or rights it has as a superuser) are left alone.
+ */
+class BorrowedRoles {
+	private readonly borrowed: string[] = [];
+
+	public constructor(
+		private readonly pool: Pool,
+		private readonly adminUser: string,
+	) {}
+
+	public async borrow(role: string): Promise<void> {
+		if (this.borrowed.includes(role)) return;
+		if (await granted(this.pool, hasRolePrivilegesQuery(this.adminUser, role))) return;
+		try {
+			await this.pool.query(grantRoleMembershipQuery(this.adminUser, role).text);
+		} catch (err) {
+			throw new DataConfigurationError(
+				`Bootstrap role "${this.adminUser}" cannot act as "${role}". Make it a member of "${role}" (or create "${role}" with it), then run again.`,
+				{ cause: err },
+			);
+		}
+		this.borrowed.push(role);
+	}
+
+	public async [Symbol.asyncDispose](): Promise<void> {
+		for (const role of this.borrowed.reverse()) {
+			await this.pool.query(revokeRoleMembershipQuery(this.adminUser, role).text);
+		}
+	}
+}

package/src/user-scripts.ts

@@ -0,0 +1,234 @@
+/** Postgres identifier: letters, digits, underscore; must start with letter or underscore. */
+const SAFE_IDENT = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+export function assertSafeSqlIdent(value: string, label: string): string {
+	if (typeof value !== "string" || value.length === 0 || !SAFE_IDENT.test(value)) {
+		throw new Error(
+			`Invalid ${label}: must match ${SAFE_IDENT} (got ${JSON.stringify(value)})`,
+		);
+	}
+	return value;
+}
+
+/** Double-quote a validated identifier for use in DDL. */
+export function quoteIdent(value: string, label = "identifier"): string {
+	const safe = assertSafeSqlIdent(value, label);
+	return `"${safe.replaceAll('"', '""')}"`;
+}
+
+/**
+ * Single-quote a string literal for DDL that cannot take bind parameters
+ * (e.g. CREATE USER … PASSWORD — Postgres rejects PASSWORD $1).
+ */
+export function quoteLiteral(value: string): string {
+	return `'${value.replaceAll("'", "''")}'`;
+}
+
+export type SqlQuery = { text: string; values: unknown[] };
+
+/** Existence check — username bound as $1 (never concatenated). */
+export function roleExistsQuery(username: string): SqlQuery {
+	assertSafeSqlIdent(username, "username");
+	return {
+		text: `SELECT 1 FROM pg_catalog.pg_roles WHERE rolname = $1`,
+		values: [username],
+	};
+}
+
+/**
+ * CREATE USER with password as an escaped SQL literal.
+ * Username is validated + quoted as an identifier (cannot be parameterized in DDL).
+ * Password cannot use bind params in CREATE USER … PASSWORD (Postgres syntax error).
+ *
+ * `password` omitted (undefined, or null from a config file) creates a role with no password, for a local dev server that
+ * trusts every connection. An empty string is still an error: that is a typo, not a choice.
+ * Callers decide when no password is allowed (see PostgresServerManager).
+ */
+export function createUserQuery(username: string, password?: string | null): SqlQuery {
+	const userIdent = quoteIdent(username, "username");
+	const attributes = "NOSUPERUSER NOBYPASSRLS NOCREATEDB NOCREATEROLE";
+	if (password == null) {
+		return { text: `CREATE USER ${userIdent} WITH LOGIN ${attributes}`, values: [] };
+	}
+	if (typeof password !== "string" || password.length === 0) {
+		throw new Error("Invalid password: must be a non-empty string");
+	}
+	const passwordLiteral = quoteLiteral(password);
+	return {
+		text: `CREATE USER ${userIdent} WITH LOGIN PASSWORD ${passwordLiteral} ${attributes}`,
+		values: [],
+	};
+}
+
+/** CONNECT only — production runtime app role. */
+export function grantConnectQuery(username: string, database: string): SqlQuery {
+	const userIdent = quoteIdent(username, "username");
+	const dbIdent = quoteIdent(database, "database");
+	return {
+		text: `GRANT CONNECT ON DATABASE ${dbIdent} TO ${userIdent}`,
+		values: [],
+	};
+}
+
+export function grantSchemaUsageQuery(username: string, schema = "public"): SqlQuery {
+	const userIdent = quoteIdent(username, "username");
+	const schemaIdent = quoteIdent(schema, "schema");
+	return {
+		text: `GRANT USAGE ON SCHEMA ${schemaIdent} TO ${userIdent}`,
+		values: [],
+	};
+}
+
+/** Needed for TypeORM synchronize (dev only). */
+export function grantSchemaCreateQuery(username: string, schema = "public"): SqlQuery {
+	const userIdent = quoteIdent(username, "username");
+	const schemaIdent = quoteIdent(schema, "schema");
+	return {
+		text: `GRANT CREATE ON SCHEMA ${schemaIdent} TO ${userIdent}`,
+		values: [],
+	};
+}
+
+/** The schema, owned by `owner`. Unchanged when it already exists. */
+export function createSchemaQuery(schema: string, owner: string): SqlQuery {
+	const schemaIdent = quoteIdent(schema, "schema");
+	const ownerIdent = quoteIdent(owner, "owner");
+	return {
+		text: `CREATE SCHEMA IF NOT EXISTS ${schemaIdent} AUTHORIZATION ${ownerIdent}`,
+		values: [],
+	};
+}
+
+/**
+ * Whether a role already holds a privilege. Postgres checks that the grantor may grant even when
+ * the grant would change nothing, so bootstrap asks first and grants only what is missing.
+ */
+export function hasDatabasePrivilegeQuery(
+	username: string,
+	database: string,
+	privilege: string,
+): SqlQuery {
+	assertSafeSqlIdent(username, "username");
+	assertSafeSqlIdent(database, "database");
+	return {
+		text: `SELECT has_database_privilege($1, $2, $3) AS granted`,
+		values: [username, database, privilege],
+	};
+}
+
+export function hasSchemaPrivilegeQuery(
+	username: string,
+	schema: string,
+	privilege: string,
+): SqlQuery {
+	assertSafeSqlIdent(username, "username");
+	assertSafeSqlIdent(schema, "schema");
+	return {
+		text: `SELECT has_schema_privilege($1, $2, $3) AS granted`,
+		values: [username, schema, privilege],
+	};
+}
+
+/** Whether `member` already has the privileges of `role` (inherited, or as a superuser). */
+export function hasRolePrivilegesQuery(member: string, role: string): SqlQuery {
+	assertSafeSqlIdent(member, "member");
+	assertSafeSqlIdent(role, "role");
+	return {
+		text: `SELECT pg_has_role($1, $2, 'USAGE') AS granted`,
+		values: [member, role],
+	};
+}
+
+export function databaseOwnerQuery(database: string): SqlQuery {
+	assertSafeSqlIdent(database, "database");
+	return {
+		text: `SELECT pg_get_userbyid(datdba) AS owner FROM pg_catalog.pg_database WHERE datname = $1`,
+		values: [database],
+	};
+}
+
+export function grantSchemaPrivilegesQuery(username: string, schema = "public"): SqlQuery {
+	const userIdent = quoteIdent(username, "username");
+	const schemaIdent = quoteIdent(schema, "schema");
+	return {
+		text: `GRANT ALL ON SCHEMA ${schemaIdent} TO ${userIdent}`,
+		values: [],
+	};
+}
+
+export function alterDatabaseOwnerQuery(database: string, username: string): SqlQuery {
+	const dbIdent = quoteIdent(database, "database");
+	const userIdent = quoteIdent(username, "username");
+	return {
+		text: `ALTER DATABASE ${dbIdent} OWNER TO ${userIdent}`,
+		values: [],
+	};
+}
+
+/**
+ * Postgres requires the session user to be a member of the target role to
+ * `ALTER DATABASE … OWNER TO` / `ALTER DEFAULT PRIVILEGES FOR ROLE`.
+ */
+export function grantRoleMembershipQuery(member: string, role: string): SqlQuery {
+	const memberIdent = quoteIdent(member, "member");
+	const roleIdent = quoteIdent(role, "role");
+	return {
+		text: `GRANT ${roleIdent} TO ${memberIdent}`,
+		values: [],
+	};
+}
+
+export function revokeRoleMembershipQuery(member: string, role: string): SqlQuery {
+	const memberIdent = quoteIdent(member, "member");
+	const roleIdent = quoteIdent(role, "role");
+	return {
+		text: `REVOKE ${roleIdent} FROM ${memberIdent}`,
+		values: [],
+	};
+}
+
+/**
+ * Future tables/sequences created by the migration role are usable by the app role (DML only).
+ */
+export function defaultPrivilegesForAppQueries(
+	migrateUsername: string,
+	appUsername: string,
+	schema = "public",
+): SqlQuery[] {
+	const migrateIdent = quoteIdent(migrateUsername, "migrateUsername");
+	const appIdent = quoteIdent(appUsername, "username");
+	const schemaIdent = quoteIdent(schema, "schema");
+	return [
+		{
+			text: `ALTER DEFAULT PRIVILEGES FOR ROLE ${migrateIdent} IN SCHEMA ${schemaIdent} GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO ${appIdent}`,
+			values: [],
+		},
+		{
+			text: `ALTER DEFAULT PRIVILEGES FOR ROLE ${migrateIdent} IN SCHEMA ${schemaIdent} GRANT USAGE, SELECT ON SEQUENCES TO ${appIdent}`,
+			values: [],
+		},
+	];
+}
+
+/**
+ * @deprecated Prefer discrete query helpers + PostgresServerManager.provisionRoles.
+ * Kept for call-site / pen-test migration: emits create + CONNECT + USAGE (not ALL PRIVILEGES).
+ */
+const createOwnerUser = (username: string, password: string, database: string): SqlQuery => {
+	quoteIdent(username, "username");
+	quoteIdent(database, "database");
+	if (typeof password !== "string" || password.length === 0) {
+		throw new Error("Invalid password: must be a non-empty string");
+	}
+	const create = createUserQuery(username, password);
+	const connect = grantConnectQuery(username, database);
+	const usage = grantSchemaUsageQuery(username);
+	return {
+		text: [create.text, connect.text, usage.text].join(";\n"),
+		values: [],
+	};
+};
+
+const userExists = (username: string): SqlQuery => roleExistsQuery(username);
+
+export const userScripts = { createOwnerUser, userExists };