@plumbus/core 0.7.1 → 0.8.0-beta.1

package/dist/tenancy/data-plane-connection.js

@@ -0,0 +1,320 @@
+// ── Data-Plane Connections ──
+// Opening one data plane: a pooled connection to a named database, opened as a
+// named role, handed back in the `{ db, close }` shape the pooled resolver's
+// `connect` step has to produce.
+//
+// `createPooledDataPlaneResolver` deliberately does not know how a connection is
+// made — the host answers that. Without a framework-supplied answer every host
+// reaches for the raw driver, which is where unbounded pools and credentials in
+// error messages come from. This is that answer, with three properties a
+// hand-rolled `connect` rarely has:
+//
+//   bounded    — a ceiling is always applied (`DEFAULT_DATA_PLANE_POOL_SIZE` by
+//                default, never above `MAX_DATA_PLANE_POOL_SIZE`), so a resolver
+//                holding many data planes open cannot multiply into an unbounded
+//                number of server backends.
+//   quiet      — no password and no connection string reaches a message, error
+//                metadata or the notice stream. Failures are re-raised as
+//                `DataPlaneConnectionError` carrying only host, port, database,
+//                role and SQLSTATE, with the driver's text scrubbed of secrets.
+//   per-tenant — every call builds its own client and its own `close`, sharing
+//                no state with any other call, so it is safe to invoke once per
+//                tenant. `close` is idempotent and closes the whole pool.
+//
+// By default the connection is verified with a round trip before it is returned,
+// so a wrong credential or an unreachable placement fails at resolve time rather
+// than inside the first capability that happens to query.
+//
+// Key exports: openDataPlaneConnection, DataPlaneConnectionError.
+import { PlumbusError } from '../errors/plumbus-error.js';
+import { ErrorCode } from '../types/enums.js';
+/** Connections a data-plane pool holds when the caller names no ceiling. */
+export const DEFAULT_DATA_PLANE_POOL_SIZE = 5;
+/**
+ * Largest pool one data plane may hold. A resolver caches many data planes at
+ * once, so the per-tenant ceiling is what keeps the total number of server
+ * backends finite; a request for more is a configuration error, not a tuning
+ * choice the framework silently honours.
+ */
+export const MAX_DATA_PLANE_POOL_SIZE = 64;
+const DEFAULT_PORT = 5432;
+const DEFAULT_CONNECT_TIMEOUT_SECONDS = 10;
+const DEFAULT_IDLE_TIMEOUT_SECONDS = 30;
+const DEFAULT_CLOSE_TIMEOUT_SECONDS = 5;
+/** What a scrubbed secret is replaced with wherever one could have appeared. */
+const REDACTED = '[redacted]';
+const NUL = '\u0000';
+// ── Errors ──
+/**
+ * A data plane could not be opened, or the connection did not answer.
+ *
+ * Carries only non-secret coordinates: `host`, `port`, `database`, `user` and,
+ * when the server rejected the attempt, `sqlState`. The driver's own error is
+ * never re-thrown and never attached, because its text and its fields are
+ * outside this module's control.
+ */
+export class DataPlaneConnectionError extends PlumbusError {
+    constructor(message, metadata) {
+        super(ErrorCode.Internal, message, metadata);
+        this.name = 'DataPlaneConnectionError';
+    }
+}
+function validationError(message, metadata) {
+    return new PlumbusError(ErrorCode.Validation, message, metadata);
+}
+function isConnectionUrl(target) {
+    return typeof target.connectionString === 'string';
+}
+/**
+ * Connection parameters travel in the startup packet, where a NUL terminates the
+ * value: a parameter carrying one is refused rather than silently truncated.
+ */
+function assertParameter(value, field) {
+    if (typeof value !== 'string' || value.length === 0) {
+        throw validationError(`${field} must be a non-empty string`, { field });
+    }
+    if (value.includes(NUL)) {
+        throw validationError(`${field} must not contain a NUL character`, { field });
+    }
+    return value;
+}
+function assertPort(value, field) {
+    if (!Number.isInteger(value) || value < 1 || value > 65535) {
+        throw validationError(`${field} must be an integer between 1 and 65535`, { field });
+    }
+    return value;
+}
+function assertSeconds(value, field) {
+    if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) {
+        throw validationError(`${field} must be a positive, finite number of seconds`, { field });
+    }
+    return value;
+}
+function normalizePoolSize(value) {
+    if (value === undefined)
+        return DEFAULT_DATA_PLANE_POOL_SIZE;
+    if (!Number.isInteger(value) || value < 1 || value > MAX_DATA_PLANE_POOL_SIZE) {
+        throw validationError(`maxConnections must be an integer between 1 and ${MAX_DATA_PLANE_POOL_SIZE} (received ${String(value)})`, { field: 'maxConnections' });
+    }
+    return value;
+}
+function hasControlCharacter(value) {
+    for (const character of value) {
+        const code = character.codePointAt(0) ?? 0;
+        if (code < 0x20 || code === 0x7f)
+            return true;
+    }
+    return false;
+}
+function normalizeApplicationName(value) {
+    const name = assertParameter(value, 'applicationName');
+    if (hasControlCharacter(name)) {
+        throw validationError('applicationName must not contain control characters', {
+            field: 'applicationName',
+        });
+    }
+    return name;
+}
+/**
+ * Reads the non-secret coordinates out of a URL. A string that does not parse
+ * yields no coordinates rather than an excerpt — an excerpt of a connection
+ * string is an excerpt of a credential.
+ */
+function endpointOfUrl(connectionString) {
+    let url;
+    try {
+        url = new URL(connectionString);
+    }
+    catch {
+        return { endpoint: {} };
+    }
+    const database = decodeURIComponent(url.pathname.replace(/^\//, ''));
+    const endpoint = {
+        ...(url.hostname ? { host: url.hostname } : {}),
+        ...(url.port ? { port: Number(url.port) } : {}),
+        ...(database ? { database } : {}),
+        ...(url.username ? { user: decodeURIComponent(url.username) } : {}),
+    };
+    const password = url.password ? decodeURIComponent(url.password) : '';
+    return password ? { endpoint, secret: password } : { endpoint };
+}
+function normalizeTarget(target) {
+    if (target === null || typeof target !== 'object') {
+        throw validationError('target must describe the database to connect to', { field: 'target' });
+    }
+    if (isConnectionUrl(target)) {
+        const connectionString = assertParameter(target.connectionString, 'target.connectionString');
+        const scheme = connectionString.slice(0, connectionString.indexOf(':') + 1);
+        if (scheme !== 'postgres:' && scheme !== 'postgresql:') {
+            throw validationError('target.connectionString must be a postgres:// or postgresql:// URL', {
+                field: 'target.connectionString',
+            });
+        }
+        const databaseOverride = target.database === undefined
+            ? undefined
+            : assertParameter(target.database, 'target.database');
+        const { endpoint, secret } = endpointOfUrl(connectionString);
+        return {
+            kind: 'url',
+            endpoint: databaseOverride ? { ...endpoint, database: databaseOverride } : endpoint,
+            secrets: secret ? [connectionString, secret] : [connectionString],
+            connectionString,
+            ...(databaseOverride === undefined ? {} : { databaseOverride }),
+        };
+    }
+    const host = assertParameter(target.host, 'target.host');
+    const database = assertParameter(target.database, 'target.database');
+    const user = assertParameter(target.user, 'target.user');
+    const port = target.port === undefined ? DEFAULT_PORT : assertPort(target.port, 'target.port');
+    const password = target.password === undefined ? undefined : assertParameter(target.password, 'target.password');
+    return {
+        kind: 'fields',
+        endpoint: { host, port, database, user },
+        secrets: password === undefined ? [] : [password],
+        host,
+        port,
+        database,
+        user,
+        ...(password === undefined ? {} : { password }),
+        ...(target.ssl === undefined ? {} : { ssl: target.ssl }),
+    };
+}
+// ── Failure reporting ──
+function sqlStateOf(error) {
+    if (typeof error !== 'object' || error === null)
+        return undefined;
+    const code = error.code;
+    return typeof code === 'string' ? code : undefined;
+}
+function messageOf(error) {
+    if (error instanceof Error && typeof error.message === 'string')
+        return error.message;
+    return typeof error === 'string' ? error : 'unknown error';
+}
+/** Replaces every occurrence of every secret, longest first so overlaps are covered. */
+function redact(text, secrets) {
+    let scrubbed = text;
+    for (const secret of [...secrets].sort((a, b) => b.length - a.length)) {
+        if (secret.length === 0)
+            continue;
+        scrubbed = scrubbed.split(secret).join(REDACTED);
+    }
+    return scrubbed;
+}
+function describeEndpoint(endpoint) {
+    const where = endpoint.host
+        ? `${endpoint.host}:${endpoint.port ?? DEFAULT_PORT}`
+        : 'the configured host';
+    const database = endpoint.database ? `"${endpoint.database}"` : 'the configured database';
+    const role = endpoint.user ? ` as role "${endpoint.user}"` : '';
+    return `database ${database} on ${where}${role}`;
+}
+function connectionFailure(action, target, error) {
+    const sqlState = sqlStateOf(error);
+    return new DataPlaneConnectionError(`Could not ${action} ${describeEndpoint(target.endpoint)}: ${redact(messageOf(error), target.secrets)}`, {
+        ...target.endpoint,
+        ...(sqlState === undefined ? {} : { sqlState }),
+    });
+}
+// ── Opening ──
+/**
+ * Opens a pooled connection to one database as one role.
+ *
+ * This is the `connect` step of `createPooledDataPlaneResolver`:
+ *
+ * ```ts
+ * const resolver = createPooledDataPlaneResolver<Placement>({
+ *   describe: async (tenantRef) => placements.get(tenantRef),
+ *   connect: ({ descriptor }) =>
+ *     openDataPlaneConnection({ target: descriptor.connectionInfo, maxConnections: 4 }),
+ * });
+ * ```
+ *
+ * Each call owns its pool: nothing is shared between calls, so calling it once
+ * per tenant gives every tenant an isolated set of connections that the resolver
+ * closes through the returned `close` when it evicts or invalidates the entry.
+ *
+ * Throws `PlumbusError` (`validation`) for an unusable target or option before
+ * any socket is opened, and `DataPlaneConnectionError` when the server refuses
+ * or does not answer. Neither carries a password or a connection string.
+ */
+export async function openDataPlaneConnection(options) {
+    const target = normalizeTarget(options.target);
+    const max = normalizePoolSize(options.maxConnections);
+    const connectTimeout = options.connectTimeoutSeconds === undefined
+        ? DEFAULT_CONNECT_TIMEOUT_SECONDS
+        : assertSeconds(options.connectTimeoutSeconds, 'connectTimeoutSeconds');
+    const idleTimeout = options.idleTimeoutSeconds === undefined
+        ? DEFAULT_IDLE_TIMEOUT_SECONDS
+        : assertSeconds(options.idleTimeoutSeconds, 'idleTimeoutSeconds');
+    const closeTimeout = options.closeTimeoutSeconds === undefined
+        ? DEFAULT_CLOSE_TIMEOUT_SECONDS
+        : assertSeconds(options.closeTimeoutSeconds, 'closeTimeoutSeconds');
+    const maxLifetime = options.maxLifetimeSeconds === undefined
+        ? undefined
+        : assertSeconds(options.maxLifetimeSeconds, 'maxLifetimeSeconds');
+    const applicationName = options.applicationName === undefined
+        ? undefined
+        : normalizeApplicationName(options.applicationName);
+    const postgresModule = (await import('postgres')).default;
+    const { drizzle } = await import('drizzle-orm/postgres-js');
+    const shared = {
+        max,
+        connect_timeout: connectTimeout,
+        idle_timeout: idleTimeout,
+        // The server's notice stream can echo statement text; the caller's own
+        // logging is the record, not this module's stderr.
+        onnotice: () => { },
+        ...(maxLifetime === undefined ? {} : { max_lifetime: maxLifetime }),
+        ...(applicationName === undefined ? {} : { connection: { application_name: applicationName } }),
+    };
+    let client;
+    try {
+        client =
+            target.kind === 'url'
+                ? postgresModule(target.connectionString, target.databaseOverride === undefined
+                    ? shared
+                    : { ...shared, database: target.databaseOverride })
+                : postgresModule({
+                    ...shared,
+                    host: target.host,
+                    port: target.port,
+                    database: target.database,
+                    username: target.user,
+                    ...(target.password === undefined ? {} : { password: target.password }),
+                    ...(target.ssl === undefined ? {} : { ssl: target.ssl }),
+                });
+    }
+    catch (error) {
+        throw connectionFailure('open a connection to', target, error);
+    }
+    const close = createCloser(client, closeTimeout, target);
+    if (options.verify !== false) {
+        try {
+            await client `SELECT 1`;
+        }
+        catch (error) {
+            await close().catch(() => undefined);
+            throw connectionFailure('open a connection to', target, error);
+        }
+    }
+    return { db: drizzle(client), close };
+}
+/**
+ * Idempotent pool shutdown. Concurrent and repeated calls await the same
+ * shutdown; a failed one is not cached, so a later call may try again.
+ */
+function createCloser(client, timeoutSeconds, target) {
+    let ending;
+    return async function close() {
+        ending ??= client.end({ timeout: timeoutSeconds }).then(() => undefined);
+        try {
+            await ending;
+        }
+        catch (error) {
+            ending = undefined;
+            throw connectionFailure('close the connection to', target, error);
+        }
+    };
+}
+//# sourceMappingURL=data-plane-connection.js.map

package/dist/tenancy/data-plane-connection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-plane-connection.js","sourceRoot":"","sources":["../../src/tenancy/data-plane-connection.ts"],"names":[],"mappings":"AAAA,+BAA+B;AAC/B,+EAA+E;AAC/E,6EAA6E;AAC7E,iCAAiC;AACjC,EAAE;AACF,iFAAiF;AACjF,+EAA+E;AAC/E,gFAAgF;AAChF,yEAAyE;AACzE,oCAAoC;AACpC,EAAE;AACF,gFAAgF;AAChF,iFAAiF;AACjF,iFAAiF;AACjF,4CAA4C;AAC5C,+EAA+E;AAC/E,0EAA0E;AAC1E,gFAAgF;AAChF,gFAAgF;AAChF,+EAA+E;AAC/E,gFAAgF;AAChF,0EAA0E;AAC1E,EAAE;AACF,iFAAiF;AACjF,iFAAiF;AACjF,0DAA0D;AAC1D,EAAE;AACF,kEAAkE;AAIlE,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC1D,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAG9C,4EAA4E;AAC5E,MAAM,CAAC,MAAM,4BAA4B,GAAG,CAAC,CAAC;AAE9C;;;;;GAKG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,EAAE,CAAC;AAE3C,MAAM,YAAY,GAAG,IAAI,CAAC;AAC1B,MAAM,+BAA+B,GAAG,EAAE,CAAC;AAC3C,MAAM,4BAA4B,GAAG,EAAE,CAAC;AACxC,MAAM,6BAA6B,GAAG,CAAC,CAAC;AAExC,gFAAgF;AAChF,MAAM,QAAQ,GAAG,YAAY,CAAC;AAE9B,MAAM,GAAG,GAAG,QAAQ,CAAC;AAErB,eAAe;AAEf;;;;;;;GAOG;AACH,MAAM,OAAO,wBAAyB,SAAQ,YAAY;IACxD,YAAY,OAAe,EAAE,QAAkC;QAC7D,KAAK,CAAC,SAAS,CAAC,QAAQ,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC;QAC7C,IAAI,CAAC,IAAI,GAAG,0BAA0B,CAAC;IACzC,CAAC;CACF;AAED,SAAS,eAAe,CAAC,OAAe,EAAE,QAAkC;IAC1E,OAAO,IAAI,YAAY,CAAC,SAAS,CAAC,UAAU,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC;AACnE,CAAC;AAgGD,SAAS,eAAe,CAAC,MAAiC;IACxD,OAAO,OAAQ,MAAyC,CAAC,gBAAgB,KAAK,QAAQ,CAAC;AACzF,CAAC;AAED;;;GAGG;AACH,SAAS,eAAe,CAAC,KAAc,EAAE,KAAa;IACpD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACpD,MAAM,eAAe,CAAC,GAAG,KAAK,6BAA6B,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;IAC1E,CAAC;IACD,IAAI,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QACxB,MAAM,eAAe,CAAC,GAAG,KAAK,mCAAmC,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;IAChF,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,UAAU,CAAC,KAAc,EAAE,KAAa;IAC/C,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAK,KAAgB,GAAG,CAAC,IAAK,KAAgB,GAAG,KAAK,EAAE,CAAC;QACnF,MAAM,eAAe,CAAC,GAAG,KAAK,yCAAyC,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;IACtF,CAAC;IACD,OAAO,KAAe,CAAC;AACzB,CAAC;AAED,SAAS,aAAa,CAAC,KAAc,EAAE,KAAa;IAClD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,EAAE,CAAC;QACvE,MAAM,eAAe,CAAC,GAAG,KAAK,+CAA+C,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;IAC5F,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,iBAAiB,CAAC,KAAyB;IAClD,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,4BAA4B,CAAC;IAC7D,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,IAAI,KAAK,GAAG,wBAAwB,EAAE,CAAC;QAC9E,MAAM,eAAe,CACnB,mDAAmD,wBAAwB,cAAc,MAAM,CAAC,KAAK,CAAC,GAAG,EACzG,EAAE,KAAK,EAAE,gBAAgB,EAAE,CAC5B,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,mBAAmB,CAAC,KAAa;IACxC,KAAK,MAAM,SAAS,IAAI,KAAK,EAAE,CAAC;QAC9B,MAAM,IAAI,GAAG,SAAS,CAAC,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QAC3C,IAAI,IAAI,GAAG,IAAI,IAAI,IAAI,KAAK,IAAI;YAAE,OAAO,IAAI,CAAC;IAChD,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,wBAAwB,CAAC,KAAc;IAC9C,MAAM,IAAI,GAAG,eAAe,CAAC,KAAK,EAAE,iBAAiB,CAAC,CAAC;IACvD,IAAI,mBAAmB,CAAC,IAAI,CAAC,EAAE,CAAC;QAC9B,MAAM,eAAe,CAAC,qDAAqD,EAAE;YAC3E,KAAK,EAAE,iBAAiB;SACzB,CAAC,CAAC;IACL,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;GAIG;AACH,SAAS,aAAa,CAAC,gBAAwB;IAC7C,IAAI,GAAQ,CAAC;IACb,IAAI,CAAC;QACH,GAAG,GAAG,IAAI,GAAG,CAAC,gBAAgB,CAAC,CAAC;IAClC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;IAC1B,CAAC;IACD,MAAM,QAAQ,GAAG,kBAAkB,CAAC,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC;IACrE,MAAM,QAAQ,GAAsB;QAClC,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,GAAG,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/C,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/C,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACjC,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,kBAAkB,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACpE,CAAC;IACF,MAAM,QAAQ,GAAG,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,kBAAkB,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACtE,OAAO,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC;AAClE,CAAC;AAED,SAAS,eAAe,CAAC,MAAiC;IACxD,IAAI,MAAM,KAAK,IAAI,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;QAClD,MAAM,eAAe,CAAC,iDAAiD,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC;IAChG,CAAC;IAED,IAAI,eAAe,CAAC,MAAM,CAAC,EAAE,CAAC;QAC5B,MAAM,gBAAgB,GAAG,eAAe,CAAC,MAAM,CAAC,gBAAgB,EAAE,yBAAyB,CAAC,CAAC;QAC7F,MAAM,MAAM,GAAG,gBAAgB,CAAC,KAAK,CAAC,CAAC,EAAE,gBAAgB,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;QAC5E,IAAI,MAAM,KAAK,WAAW,IAAI,MAAM,KAAK,aAAa,EAAE,CAAC;YACvD,MAAM,eAAe,CAAC,oEAAoE,EAAE;gBAC1F,KAAK,EAAE,yBAAyB;aACjC,CAAC,CAAC;QACL,CAAC;QACD,MAAM,gBAAgB,GACpB,MAAM,CAAC,QAAQ,KAAK,SAAS;YAC3B,CAAC,CAAC,SAAS;YACX,CAAC,CAAC,eAAe,CAAC,MAAM,CAAC,QAAQ,EAAE,iBAAiB,CAAC,CAAC;QAC1D,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,aAAa,CAAC,gBAAgB,CAAC,CAAC;QAC7D,OAAO;YACL,IAAI,EAAE,KAAK;YACX,QAAQ,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAAE,GAAG,QAAQ,EAAE,QAAQ,EAAE,gBAAgB,EAAE,CAAC,CAAC,CAAC,QAAQ;YACnF,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,gBAAgB,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,gBAAgB,CAAC;YACjE,gBAAgB;YAChB,GAAG,CAAC,gBAAgB,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,gBAAgB,EAAE,CAAC;SAChE,CAAC;IACJ,CAAC;IAED,MAAM,IAAI,GAAG,eAAe,CAAC,MAAM,CAAC,IAAI,EAAE,aAAa,CAAC,CAAC;IACzD,MAAM,QAAQ,GAAG,eAAe,CAAC,MAAM,CAAC,QAAQ,EAAE,iBAAiB,CAAC,CAAC;IACrE,MAAM,IAAI,GAAG,eAAe,CAAC,MAAM,CAAC,IAAI,EAAE,aAAa,CAAC,CAAC;IACzD,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI,EAAE,aAAa,CAAC,CAAC;IAC/F,MAAM,QAAQ,GACZ,MAAM,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,eAAe,CAAC,MAAM,CAAC,QAAQ,EAAE,iBAAiB,CAAC,CAAC;IAClG,OAAO;QACL,IAAI,EAAE,QAAQ;QACd,QAAQ,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE;QACxC,OAAO,EAAE,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;QACjD,IAAI;QACJ,IAAI;QACJ,QAAQ;QACR,IAAI;QACJ,GAAG,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC;QAC/C,GAAG,CAAC,MAAM,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,EAAE,CAAC;KACzD,CAAC;AACJ,CAAC;AAED,0BAA0B;AAE1B,SAAS,UAAU,CAAC,KAAc;IAChC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IAClE,MAAM,IAAI,GAAI,KAA4B,CAAC,IAAI,CAAC;IAChD,OAAO,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;AACrD,CAAC;AAED,SAAS,SAAS,CAAC,KAAc;IAC/B,IAAI,KAAK,YAAY,KAAK,IAAI,OAAO,KAAK,CAAC,OAAO,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC,OAAO,CAAC;IACtF,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,eAAe,CAAC;AAC7D,CAAC;AAED,wFAAwF;AACxF,SAAS,MAAM,CAAC,IAAY,EAAE,OAA0B;IACtD,IAAI,QAAQ,GAAG,IAAI,CAAC;IACpB,KAAK,MAAM,MAAM,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC;QACtE,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;YAAE,SAAS;QAClC,QAAQ,GAAG,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACnD,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,SAAS,gBAAgB,CAAC,QAA2B;IACnD,MAAM,KAAK,GAAG,QAAQ,CAAC,IAAI;QACzB,CAAC,CAAC,GAAG,QAAQ,CAAC,IAAI,IAAI,QAAQ,CAAC,IAAI,IAAI,YAAY,EAAE;QACrD,CAAC,CAAC,qBAAqB,CAAC;IAC1B,MAAM,QAAQ,GAAG,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,QAAQ,CAAC,QAAQ,GAAG,CAAC,CAAC,CAAC,yBAAyB,CAAC;IAC1F,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,aAAa,QAAQ,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IAChE,OAAO,YAAY,QAAQ,OAAO,KAAK,GAAG,IAAI,EAAE,CAAC;AACnD,CAAC;AAED,SAAS,iBAAiB,CACxB,MAAc,EACd,MAAwB,EACxB,KAAc;IAEd,MAAM,QAAQ,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC;IACnC,OAAO,IAAI,wBAAwB,CACjC,aAAa,MAAM,IAAI,gBAAgB,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,OAAO,CAAC,EAAE,EACvG;QACE,GAAG,MAAM,CAAC,QAAQ;QAClB,GAAG,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC;KAChD,CACF,CAAC;AACJ,CAAC;AAED,gBAAgB;AAEhB;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,OAAuC;IAEvC,MAAM,MAAM,GAAG,eAAe,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAC/C,MAAM,GAAG,GAAG,iBAAiB,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC;IACtD,MAAM,cAAc,GAClB,OAAO,CAAC,qBAAqB,KAAK,SAAS;QACzC,CAAC,CAAC,+BAA+B;QACjC,CAAC,CAAC,aAAa,CAAC,OAAO,CAAC,qBAAqB,EAAE,uBAAuB,CAAC,CAAC;IAC5E,MAAM,WAAW,GACf,OAAO,CAAC,kBAAkB,KAAK,SAAS;QACtC,CAAC,CAAC,4BAA4B;QAC9B,CAAC,CAAC,aAAa,CAAC,OAAO,CAAC,kBAAkB,EAAE,oBAAoB,CAAC,CAAC;IACtE,MAAM,YAAY,GAChB,OAAO,CAAC,mBAAmB,KAAK,SAAS;QACvC,CAAC,CAAC,6BAA6B;QAC/B,CAAC,CAAC,aAAa,CAAC,OAAO,CAAC,mBAAmB,EAAE,qBAAqB,CAAC,CAAC;IACxE,MAAM,WAAW,GACf,OAAO,CAAC,kBAAkB,KAAK,SAAS;QACtC,CAAC,CAAC,SAAS;QACX,CAAC,CAAC,aAAa,CAAC,OAAO,CAAC,kBAAkB,EAAE,oBAAoB,CAAC,CAAC;IACtE,MAAM,eAAe,GACnB,OAAO,CAAC,eAAe,KAAK,SAAS;QACnC,CAAC,CAAC,SAAS;QACX,CAAC,CAAC,wBAAwB,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC;IAExD,MAAM,cAAc,GAAG,CAAC,MAAM,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,OAAO,CAAC;IAC1D,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,MAAM,CAAC,yBAAyB,CAAC,CAAC;IAE5D,MAAM,MAAM,GAAG;QACb,GAAG;QACH,eAAe,EAAE,cAAc;QAC/B,YAAY,EAAE,WAAW;QACzB,uEAAuE;QACvE,mDAAmD;QACnD,QAAQ,EAAE,GAAG,EAAE,GAAE,CAAC;QAClB,GAAG,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,WAAW,EAAE,CAAC;QACnE,GAAG,CAAC,eAAe,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,EAAE,gBAAgB,EAAE,eAAe,EAAE,EAAE,CAAC;KAChG,CAAC;IAEF,IAAI,MAAoB,CAAC;IACzB,IAAI,CAAC;QACH,MAAM;YACJ,MAAM,CAAC,IAAI,KAAK,KAAK;gBACnB,CAAC,CAAC,cAAc,CACZ,MAAM,CAAC,gBAAgB,EACvB,MAAM,CAAC,gBAAgB,KAAK,SAAS;oBACnC,CAAC,CAAC,MAAM;oBACR,CAAC,CAAC,EAAE,GAAG,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,gBAAgB,EAAE,CACrD;gBACH,CAAC,CAAC,cAAc,CAAC;oBACb,GAAG,MAAM;oBACT,IAAI,EAAE,MAAM,CAAC,IAAI;oBACjB,IAAI,EAAE,MAAM,CAAC,IAAI;oBACjB,QAAQ,EAAE,MAAM,CAAC,QAAQ;oBACzB,QAAQ,EAAE,MAAM,CAAC,IAAI;oBACrB,GAAG,CAAC,MAAM,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC;oBACvE,GAAG,CAAC,MAAM,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,EAAE,CAAC;iBACzD,CAAC,CAAC;IACX,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,iBAAiB,CAAC,sBAAsB,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC;IACjE,CAAC;IAED,MAAM,KAAK,GAAG,YAAY,CAAC,MAAM,EAAE,YAAY,EAAE,MAAM,CAAC,CAAC;IAEzD,IAAI,OAAO,CAAC,MAAM,KAAK,KAAK,EAAE,CAAC;QAC7B,IAAI,CAAC;YACH,MAAM,MAAM,CAAA,UAAU,CAAC;QACzB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;YACrC,MAAM,iBAAiB,CAAC,sBAAsB,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC;QACjE,CAAC;IACH,CAAC;IAED,OAAO,EAAE,EAAE,EAAE,OAAO,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,CAAC;AACxC,CAAC;AAED;;;GAGG;AACH,SAAS,YAAY,CACnB,MAAoB,EACpB,cAAsB,EACtB,MAAwB;IAExB,IAAI,MAAiC,CAAC;IACtC,OAAO,KAAK,UAAU,KAAK;QACzB,MAAM,KAAK,MAAM,CAAC,GAAG,CAAC,EAAE,OAAO,EAAE,cAAc,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QACzE,IAAI,CAAC;YACH,MAAM,MAAM,CAAC;QACf,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,GAAG,SAAS,CAAC;YACnB,MAAM,iBAAiB,CAAC,yBAAyB,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC;QACpE,CAAC;IACH,CAAC,CAAC;AACJ,CAAC"}

package/dist/tenancy/data-plane-migrate.d.ts

@@ -0,0 +1,30 @@
+import { type MigrationApplyResult } from '../data/migration.js';
+import { type DataPlaneConnectionTarget } from './data-plane-connection.js';
+export declare const DATA_PLANE_MIGRATE_APPLICATION_NAME = "plumbus-migrate";
+export interface ApplyDataPlaneMigrationsOptions {
+    /** Named tenant database, opened as the role that may run DDL (typically the owner). */
+    target: DataPlaneConnectionTarget;
+    /** Folder that holds generated SQL and `meta/_journal.json` (usually `drizzle/`). */
+    migrationsFolder: string;
+    /**
+     * Maximum connections this one-shot apply may open. Default 1.
+     * Must stay within the factory ceiling.
+     */
+    maxConnections?: number;
+    /** Reported to the server as `application_name`. Default `plumbus-migrate`. */
+    applicationName?: string;
+}
+export interface DataPlaneMigrationApplyResult extends MigrationApplyResult {
+    /** The database name when the target named one (fields target, or URL override). */
+    database?: string;
+}
+/**
+ * Open one named tenant database through `openDataPlaneConnection` and apply
+ * pending migrations from `migrationsFolder`. Always closes the pool, including
+ * when apply fails.
+ *
+ * This is the host-side counterpart of `plumbus migrate apply --database`.
+ * It does not create the database or roles — call `provisionDataPlane` first.
+ */
+export declare function applyDataPlaneMigrations(options: ApplyDataPlaneMigrationsOptions): Promise<DataPlaneMigrationApplyResult>;
+//# sourceMappingURL=data-plane-migrate.d.ts.map

package/dist/tenancy/data-plane-migrate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-plane-migrate.d.ts","sourceRoot":"","sources":["../../src/tenancy/data-plane-migrate.ts"],"names":[],"mappings":"AASA,OAAO,EAAmB,KAAK,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAClF,OAAO,EAEL,KAAK,yBAAyB,EAC/B,MAAM,4BAA4B,CAAC;AAEpC,eAAO,MAAM,mCAAmC,oBAAoB,CAAC;AAErE,MAAM,WAAW,+BAA+B;IAC9C,wFAAwF;IACxF,MAAM,EAAE,yBAAyB,CAAC;IAClC,qFAAqF;IACrF,gBAAgB,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,+EAA+E;IAC/E,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,6BAA8B,SAAQ,oBAAoB;IACzE,oFAAoF;IACpF,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AASD;;;;;;;GAOG;AACH,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,+BAA+B,GACvC,OAAO,CAAC,6BAA6B,CAAC,CAiBxC"}

package/dist/tenancy/data-plane-migrate.js

@@ -0,0 +1,44 @@
+// ── Data-plane migrations ──
+// A host applies the same generated framework/app migrations to one named
+// tenant database. The connection is the existing factory
+// (`openDataPlaneConnection`); the SQL runner is the existing
+// `applyMigrations`. This module only composes those two and always closes.
+//
+// Connect as the owner role from `provisionDataPlane`. The runtime role is
+// DML-only and cannot apply schema.
+import { applyMigrations } from '../data/migration.js';
+import { openDataPlaneConnection, } from './data-plane-connection.js';
+export const DATA_PLANE_MIGRATE_APPLICATION_NAME = 'plumbus-migrate';
+function databaseNameOf(target) {
+    if (typeof target.database === 'string') {
+        return target.database;
+    }
+    return undefined;
+}
+/**
+ * Open one named tenant database through `openDataPlaneConnection` and apply
+ * pending migrations from `migrationsFolder`. Always closes the pool, including
+ * when apply fails.
+ *
+ * This is the host-side counterpart of `plumbus migrate apply --database`.
+ * It does not create the database or roles — call `provisionDataPlane` first.
+ */
+export async function applyDataPlaneMigrations(options) {
+    const connection = await openDataPlaneConnection({
+        target: options.target,
+        maxConnections: options.maxConnections ?? 1,
+        applicationName: options.applicationName ?? DATA_PLANE_MIGRATE_APPLICATION_NAME,
+    });
+    try {
+        const result = await applyMigrations({
+            db: connection.db,
+            migrationsFolder: options.migrationsFolder,
+        });
+        const database = databaseNameOf(options.target);
+        return database === undefined ? result : { ...result, database };
+    }
+    finally {
+        await connection.close();
+    }
+}
+//# sourceMappingURL=data-plane-migrate.js.map

package/dist/tenancy/data-plane-migrate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-plane-migrate.js","sourceRoot":"","sources":["../../src/tenancy/data-plane-migrate.ts"],"names":[],"mappings":"AAAA,8BAA8B;AAC9B,0EAA0E;AAC1E,0DAA0D;AAC1D,8DAA8D;AAC9D,4EAA4E;AAC5E,EAAE;AACF,2EAA2E;AAC3E,oCAAoC;AAEpC,OAAO,EAAE,eAAe,EAA6B,MAAM,sBAAsB,CAAC;AAClF,OAAO,EACL,uBAAuB,GAExB,MAAM,4BAA4B,CAAC;AAEpC,MAAM,CAAC,MAAM,mCAAmC,GAAG,iBAAiB,CAAC;AAqBrE,SAAS,cAAc,CAAC,MAAiC;IACvD,IAAI,OAAQ,MAAiC,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;QACpE,OAAQ,MAA+B,CAAC,QAAQ,CAAC;IACnD,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAC5C,OAAwC;IAExC,MAAM,UAAU,GAAG,MAAM,uBAAuB,CAAC;QAC/C,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,cAAc,EAAE,OAAO,CAAC,cAAc,IAAI,CAAC;QAC3C,eAAe,EAAE,OAAO,CAAC,eAAe,IAAI,mCAAmC;KAChF,CAAC,CAAC;IAEH,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,eAAe,CAAC;YACnC,EAAE,EAAE,UAAU,CAAC,EAAE;YACjB,gBAAgB,EAAE,OAAO,CAAC,gBAAgB;SAC3C,CAAC,CAAC;QACH,MAAM,QAAQ,GAAG,cAAc,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAChD,OAAO,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,GAAG,MAAM,EAAE,QAAQ,EAAE,CAAC;IACnE,CAAC;YAAS,CAAC;QACT,MAAM,UAAU,CAAC,KAAK,EAAE,CAAC;IAC3B,CAAC;AACH,CAAC"}

package/dist/tenancy/data-plane-provisioning.d.ts

@@ -0,0 +1,135 @@
+import { PlumbusError } from '../errors/plumbus-error.js';
+import type { DatabaseConfig } from '../types/config.js';
+/** An identifier supplied by a caller is not safe to use as a SQL identifier. */
+export declare class DataPlaneNameError extends PlumbusError {
+    constructor(message: string, metadata?: Record<string, unknown>);
+}
+/** A destructive operation was refused because it fell outside the caller's guard. */
+export declare class DataPlaneGuardError extends PlumbusError {
+    constructor(message: string, metadata?: Record<string, unknown>);
+}
+/** A provisioning step failed; `metadata.step` names the step that failed. */
+export declare class DataPlaneProvisioningError extends PlumbusError {
+    constructor(message: string, metadata?: Record<string, unknown>);
+}
+declare const ALLOWED_TABLE_PRIVILEGES: readonly ["SELECT", "INSERT", "UPDATE", "DELETE", "TRUNCATE", "REFERENCES", "TRIGGER"];
+export type DataPlaneTablePrivilege = (typeof ALLOWED_TABLE_PRIVILEGES)[number];
+/**
+ * Validates a caller-supplied identifier and returns it unchanged.
+ *
+ * @param extraPattern additional convention the caller requires (e.g. a tenant
+ *   database prefix). Applied on top of the framework pattern, never instead of it.
+ */
+export declare function assertSafeIdentifier(value: unknown, field: string, extraPattern?: RegExp): string;
+/** Double-quotes an already-validated identifier. Defence in depth, not the defence. */
+export declare function quoteIdentifier(value: string): string;
+/** Admin credentials with cluster-level rights (CREATEDB + CREATEROLE, or superuser). */
+export type DataPlaneAdminConnection = DatabaseConfig | {
+    connectionString: string;
+};
+export type DataPlaneStepName = 'create-role' | 'alter-role-password' | 'grant-role-membership' | 'create-database' | 'revoke-database-from-public' | 'grant-database-connect' | 'create-schema' | 'revoke-schema-from-public' | 'grant-schema-usage' | 'grant-table-privileges' | 'grant-sequence-privileges' | 'set-default-table-privileges' | 'set-default-sequence-privileges' | 'terminate-connections' | 'drop-owned' | 'drop-database' | 'drop-role';
+export type DataPlaneStepOutcome = 'created' | 'already-present' | 'updated' | 'applied' | 'dropped' | 'absent' | 'skipped';
+export interface DataPlaneStep {
+    step: DataPlaneStepName;
+    /** The object the step acted on (database, role or schema name). */
+    target: string;
+    outcome: DataPlaneStepOutcome;
+    /** The SQL that ran, with any password literal redacted. Empty for no-op steps. */
+    statement: string;
+}
+export interface DataPlaneRoleSpec {
+    name: string;
+    /** Omit to create a role without a password (peer/trust or externally managed auth). */
+    password?: string;
+}
+export interface ProvisionDataPlaneOptions {
+    /** Credentials able to CREATE DATABASE and CREATE ROLE on the target cluster. */
+    adminConnection: DataPlaneAdminConnection;
+    /** Database to create. Validated and quoted; never interpolated raw. */
+    databaseName: string;
+    /** Owns the database and its schemas; the identity migrations run as. */
+    ownerRole: string | DataPlaneRoleSpec;
+    /** Least-privilege identity for request-time work: DML only, no DDL. */
+    runtimeRole: string | DataPlaneRoleSpec;
+    /** Extra schemas to create alongside `public`, owned by `ownerRole`. */
+    schemas?: readonly string[];
+    /** Table privileges granted to the runtime role. Default: SELECT/INSERT/UPDATE/DELETE. */
+    runtimeTablePrivileges?: readonly string[];
+    /** `CREATE DATABASE ... TEMPLATE`. */
+    template?: string;
+    /** `CREATE DATABASE ... ENCODING`. */
+    encoding?: string;
+    /** `CREATE DATABASE ... LC_COLLATE / LC_CTYPE`. */
+    locale?: string;
+    /** Reset the password of a role that already exists. Default false. */
+    updateExistingRolePasswords?: boolean;
+    /**
+     * Naming convention the database and role names must satisfy, on top of the
+     * framework identifier pattern. Schema names are deliberately outside it: they are
+     * structural names chosen by the caller's own code (`core_plumbus`, `pkg_*`), not
+     * names drawn from a tenant's naming space. They are still validated as identifiers.
+     */
+    namePattern?: RegExp;
+    /** Default 10. */
+    connectTimeoutSeconds?: number;
+}
+export interface DataPlaneProvisionResult {
+    databaseName: string;
+    ownerRole: string;
+    runtimeRole: string;
+    /** True when this call created the database, false when it was already present. */
+    databaseCreated: boolean;
+    rolesCreated: string[];
+    rolesAlreadyPresent: string[];
+    schemasCreated: string[];
+    schemasAlreadyPresent: string[];
+    /** Ordered log of every statement issued, for auditing and resumability. */
+    steps: DataPlaneStep[];
+}
+/**
+ * Creates a tenant's data plane, idempotently.
+ *
+ * Performs, in order: owner and runtime roles, admin membership of the owner role
+ * (required to set the database owner and default privileges when the admin is not
+ * a superuser), `CREATE DATABASE` outside a transaction, database-level revocation
+ * of PUBLIC, then per-schema grants and default privileges inside the new database.
+ *
+ * Safe to re-run after a partial failure: each step reports `created` or
+ * `already-present`, so a caller can resume without special-casing.
+ */
+export declare function provisionDataPlane(options: ProvisionDataPlaneOptions): Promise<DataPlaneProvisionResult>;
+export interface DropDataPlaneOptions {
+    adminConnection: DataPlaneAdminConnection;
+    databaseName: string;
+    /**
+     * Required guard. The database and every role named here must match this
+     * caller-supplied convention or nothing is dropped. There is no default: a
+     * teardown primitive without an explicit blast radius is not safe to ship.
+     */
+    allowedNamePattern: RegExp;
+    /** Roles to drop after the database. Each must match `allowedNamePattern`. */
+    roles?: readonly string[];
+    /** Terminate sessions still attached to the database. Default true. */
+    terminateConnections?: boolean;
+    /** Default 10. */
+    connectTimeoutSeconds?: number;
+}
+export interface DataPlaneDropResult {
+    databaseName: string;
+    /** True when this call dropped the database, false when it was already gone. */
+    databaseDropped: boolean;
+    rolesDropped: string[];
+    rolesAbsent: string[];
+    terminatedConnections: number;
+    steps: DataPlaneStep[];
+}
+/**
+ * Drops a tenant's data plane — intended for test and fixture tenants.
+ *
+ * Refuses any database or role name that does not match `allowedNamePattern`, and
+ * refuses to drop the database the admin connection is itself using. Idempotent:
+ * a second call reports `absent` rather than failing.
+ */
+export declare function dropDataPlane(options: DropDataPlaneOptions): Promise<DataPlaneDropResult>;
+export {};
+//# sourceMappingURL=data-plane-provisioning.d.ts.map

package/dist/tenancy/data-plane-provisioning.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-plane-provisioning.d.ts","sourceRoot":"","sources":["../../src/tenancy/data-plane-provisioning.ts"],"names":[],"mappings":"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"}