@microagi/alchemy-gcp 0.3.0 → 0.5.0

package/lib/Sqladmin/Operations.js

@@ -0,0 +1,42 @@
+import { ConfigError } from "@distilled.cloud/gcp";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Schedule from "effect/Schedule";
+/**
+ * Build the Cloud SQL Admin long-running-operation polling helper.
+ *
+ * Sqladmin `Operation`s carry `.status: "PENDING" | "RUNNING" | "DONE"`
+ * (NOT `.done: boolean` like Cloud Resource Manager / Cloud Run, and
+ * NOT `.status === "DONE"` against a different enum). Verified at
+ * `vendor/distilled/packages/gcp/src/services/sqladmin-v1.ts:606–612`.
+ *
+ * Unlike Cloud Run, Sqladmin operations are NOT fully-qualified path
+ * names — the API returns a bare operation id (e.g. `e9e88dca-...`),
+ * and `getOperations` takes `{ project, operation }`. Callers therefore
+ * pass the bare id alongside the parent project context.
+ *
+ * Schedule: exponential 1s → 1.5× growth, capped via the count cap of
+ * 60 retries → roughly a few minutes wall ceiling. Most Cloud SQL
+ * operations (CREATE_USER, CREATE_DATABASE, UPDATE settings) finish
+ * in 1–30 s; instance CREATE / patch involving a restart are the long
+ * pole at 4–10 min, so callers running those should be aware that
+ * recurs(60) may bottom out and surface as a retry budget exhaustion.
+ *
+ * @see https://cloud.google.com/sql/docs/postgres/admin-api/rest/v1/operations
+ */
+export const makeAwaitOperation = (getOperations) => Effect.fn(function* (project, operationName, session) {
+    const op = yield* getOperations({ project, operation: operationName }).pipe(Effect.flatMap((current) => current.status === "DONE"
+        ? Effect.succeed(current)
+        : Effect.fail({ _tag: "OperationPending" })), Effect.retry({
+        while: (e) => e?._tag === "OperationPending",
+        schedule: Schedule.exponential(Duration.seconds(1), 1.5).pipe(Schedule.either(Schedule.spaced(Duration.seconds(10))), Schedule.both(Schedule.recurs(60)), Schedule.tapOutput(() => session.note(`Waiting for Cloud SQL operation ${operationName}…`))),
+    }));
+    if (op.error) {
+        const firstErr = op.error.errors?.[0];
+        return yield* new ConfigError({
+            message: `Cloud SQL operation ${operationName} failed: ${firstErr?.message ?? JSON.stringify(op.error)}`,
+        });
+    }
+    return op;
+});
+//# sourceMappingURL=Operations.js.map

package/lib/Sqladmin/Operations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Operations.js","sourceRoot":"","sources":["../../src/Sqladmin/Operations.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAGnD,OAAO,KAAK,QAAQ,MAAM,iBAAiB,CAAC;AAC5C,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,QAAQ,MAAM,iBAAiB,CAAC;AAa5C;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,aAA4B,EAAE,EAAE,CACjE,MAAM,CAAC,EAAE,CAAC,QAAQ,CAAC,EACjB,OAAe,EACf,aAAqB,EACrB,OAAgC;IAEhC,MAAM,EAAE,GAAG,KAAK,CAAC,CAAC,aAAa,CAAC,EAAE,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,CAAC,CAAC,IAAI,CACzE,MAAM,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CACzB,OAAO,CAAC,MAAM,KAAK,MAAM;QACvB,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC;QACzB,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,kBAA2B,EAAE,CAAC,CACvD,EACD,MAAM,CAAC,KAAK,CAAC;QACX,KAAK,EAAE,CAAC,CAAoB,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,KAAK,kBAAkB;QAC/D,QAAQ,EAAE,QAAQ,CAAC,WAAW,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,IAAI,CAC3D,QAAQ,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,EACtD,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,EAClC,QAAQ,CAAC,SAAS,CAAC,GAAG,EAAE,CACtB,OAAO,CAAC,IAAI,CAAC,mCAAmC,aAAa,GAAG,CAAC,CAClE,CACF;KACF,CAAC,CACH,CAAC;IACF,IAAI,EAAE,CAAC,KAAK,EAAE,CAAC;QACb,MAAM,QAAQ,GAAG,EAAE,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC;QACtC,OAAO,KAAK,CAAC,CAAC,IAAI,WAAW,CAAC;YAC5B,OAAO,EAAE,uBAAuB,aAAa,YAC3C,QAAQ,EAAE,OAAO,IAAI,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,KAAK,CAC9C,EAAE;SACH,CAAC,CAAC;IACL,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC,CAAC,CAAC"}

package/lib/Sqladmin/Types.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Branded literal-union types for Cloud SQL props.
+ *
+ * Distilled's generated `databaseVersion` field is an open-tailed union
+ * (`"POSTGRES_15" | … | (string & {})`) so the GCP server can ship new
+ * versions without breaking SDK consumers. For our props we narrow to
+ * the subset we actually support — at the moment, the supported
+ * Postgres versions for greenfield instances. This gives consumers
+ * compile-time autocomplete and rejects typos like `"POSTGES_15"`.
+ *
+ * MySQL / SQL Server enum members are intentionally omitted — we only
+ * provision Postgres. Add a sibling `MySqlVersion` / `SqlServerVersion`
+ * type if/when those land as targets.
+ */
+/**
+ * Supported Postgres major versions for new Cloud SQL instances.
+ *
+ * Cloud SQL only allows creating instances on currently-supported
+ * majors. As of 2026-06, that's 13–17 for greenfield; we expose 15+
+ * since that's what new MicroAGI stacks target. Older versions can be
+ * read/managed but should be migrated.
+ *
+ * @see https://cloud.google.com/sql/docs/postgres/db-versions
+ */
+export type PostgresVersion = "POSTGRES_15" | "POSTGRES_16" | "POSTGRES_17";
+/**
+ * Cloud SQL edition. `ENTERPRISE_PLUS` unlocks Data Cache, near-zero
+ * downtime planned maintenance, and longer log retention; `ENTERPRISE`
+ * is the standard tier.
+ *
+ * @see https://cloud.google.com/sql/docs/postgres/editions-intro
+ */
+export type SqlEdition = "ENTERPRISE" | "ENTERPRISE_PLUS";
+/**
+ * Data-disk type. PD_SSD is the default and what any new workload
+ * should pick. PD_HDD is legacy and slower; only useful for archival
+ * read replicas.
+ *
+ * @see https://cloud.google.com/sql/docs/postgres/instance-settings#storage-type-2ndgen
+ */
+export type SqlDataDiskType = "PD_SSD" | "PD_HDD";
+/**
+ * Availability type. `ZONAL` runs in one zone; `REGIONAL` runs a
+ * standby in a second zone for HA at ~2× the cost.
+ *
+ * @see https://cloud.google.com/sql/docs/postgres/high-availability
+ */
+export type SqlAvailabilityType = "ZONAL" | "REGIONAL";
+/**
+ * Activation policy. `ALWAYS` keeps the instance on; `NEVER` parks
+ * it (useful for occasional dev databases).
+ *
+ * @see https://cloud.google.com/sql/docs/postgres/start-stop-restart-instance
+ */
+export type SqlActivationPolicy = "ALWAYS" | "NEVER";
+/**
+ * Cloud SQL user auth type.
+ *
+ * - `BUILT_IN` — classic username + password Postgres role. The
+ *   provider requires a `password` Redacted for this type.
+ * - `CLOUD_IAM_USER` — a human IAM principal authenticated via the
+ *   Cloud SQL Auth Proxy / IAM database authn token exchange.
+ * - `CLOUD_IAM_SERVICE_ACCOUNT` — a GCP service-account principal,
+ *   same auth mechanism as `CLOUD_IAM_USER`. The Postgres role name
+ *   is the SA email **with the trailing `.gserviceaccount.com`
+ *   stripped** (Cloud SQL caps role names at 63 chars; SA emails are
+ *   longer than that).
+ * - Open tail `(string & {})` keeps forward compatibility for
+ *   `CLOUD_IAM_GROUP`, `CLOUD_IAM_GROUP_SERVICE_ACCOUNT`, etc.
+ *
+ * @see https://cloud.google.com/sql/docs/postgres/iam-authentication
+ */
+export type SqlUserType = "BUILT_IN" | "CLOUD_IAM_USER" | "CLOUD_IAM_SERVICE_ACCOUNT" | "CLOUD_IAM_GROUP" | (string & {});
+/**
+ * Convenience predicate: `true` for any IAM-backed user type, where
+ * passwords are forbidden and the principal is a GCP identity.
+ *
+ * Used by `Validation.ts` and `User.ts` to fan out between the
+ * built-in password path and the IAM token-exchange path.
+ */
+export declare const isIamUserType: (type: SqlUserType | undefined) => boolean;
+//# sourceMappingURL=Types.d.ts.map

package/lib/Sqladmin/Types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Types.d.ts","sourceRoot":"","sources":["../../src/Sqladmin/Types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH;;;;;;;;;GASG;AACH,MAAM,MAAM,eAAe,GAAG,aAAa,GAAG,aAAa,GAAG,aAAa,CAAC;AAE5E;;;;;;GAMG;AACH,MAAM,MAAM,UAAU,GAAG,YAAY,GAAG,iBAAiB,CAAC;AAE1D;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAElD;;;;;GAKG;AACH,MAAM,MAAM,mBAAmB,GAAG,OAAO,GAAG,UAAU,CAAC;AAEvD;;;;;GAKG;AACH,MAAM,MAAM,mBAAmB,GAAG,QAAQ,GAAG,OAAO,CAAC;AAErD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,WAAW,GACnB,UAAU,GACV,gBAAgB,GAChB,2BAA2B,GAC3B,iBAAiB,GACjB,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAElB;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,GACxB,MAAM,WAAW,GAAG,SAAS,KAC5B,OAMsB,CAAC"}

package/lib/Sqladmin/Types.js

@@ -0,0 +1,28 @@
+/**
+ * Branded literal-union types for Cloud SQL props.
+ *
+ * Distilled's generated `databaseVersion` field is an open-tailed union
+ * (`"POSTGRES_15" | … | (string & {})`) so the GCP server can ship new
+ * versions without breaking SDK consumers. For our props we narrow to
+ * the subset we actually support — at the moment, the supported
+ * Postgres versions for greenfield instances. This gives consumers
+ * compile-time autocomplete and rejects typos like `"POSTGES_15"`.
+ *
+ * MySQL / SQL Server enum members are intentionally omitted — we only
+ * provision Postgres. Add a sibling `MySqlVersion` / `SqlServerVersion`
+ * type if/when those land as targets.
+ */
+/**
+ * Convenience predicate: `true` for any IAM-backed user type, where
+ * passwords are forbidden and the principal is a GCP identity.
+ *
+ * Used by `Validation.ts` and `User.ts` to fan out between the
+ * built-in password path and the IAM token-exchange path.
+ */
+export const isIamUserType = (type) => type === "CLOUD_IAM_USER" ||
+    type === "CLOUD_IAM_SERVICE_ACCOUNT" ||
+    type === "CLOUD_IAM_GROUP" ||
+    type === "CLOUD_IAM_GROUP_USER" ||
+    type === "CLOUD_IAM_GROUP_SERVICE_ACCOUNT" ||
+    type === "ENTRAID_USER";
+//# sourceMappingURL=Types.js.map

package/lib/Sqladmin/Types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Types.js","sourceRoot":"","sources":["../../src/Sqladmin/Types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAwEH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAC3B,IAA6B,EACpB,EAAE,CACX,IAAI,KAAK,gBAAgB;IACzB,IAAI,KAAK,2BAA2B;IACpC,IAAI,KAAK,iBAAiB;IAC1B,IAAI,KAAK,sBAAsB;IAC/B,IAAI,KAAK,iCAAiC;IAC1C,IAAI,KAAK,cAAc,CAAC"}

package/lib/Sqladmin/User.d.ts

@@ -0,0 +1,110 @@
+import { Resource } from "alchemy";
+import * as Provider from "alchemy/Provider";
+import * as Redacted from "effect/Redacted";
+import type * as GCP from "../Providers.ts";
+import { type SqlUserType } from "./Types.ts";
+/**
+ * A Cloud SQL user (database role + auth binding).
+ *
+ * **Three auth modes:**
+ *
+ * - `BUILT_IN` — classic Postgres username/password. Requires
+ *   `password`. The role exists only inside Postgres.
+ * - `CLOUD_IAM_USER` — a human IAM principal. `name` is the user's
+ *   email. Authenticates via the Cloud SQL Auth Proxy / IAM token
+ *   exchange; no password.
+ * - `CLOUD_IAM_SERVICE_ACCOUNT` — a GCP service account principal.
+ *   `name` is the SA email with the trailing `.gserviceaccount.com`
+ *   stripped (Postgres role names cap at 63 chars; full SA emails
+ *   often exceed that). No password.
+ *
+ * The Postgres role itself is granted no privileges by default — wire
+ * up grants via SQL (psql / migrations) once the user exists. Cloud
+ * SQL IAM authn is independent of grant management.
+ *
+ * **Adoption.** Users carry no labels and no useful comparable shape
+ * beyond `(name, host, type)`. `read` returns the observed user if it
+ * exists at this address, `undefined` otherwise. No `Unowned` wrapper
+ * — adoption is implicit; the worst case is alchemy issuing a no-op
+ * patch / a delete on what it thinks is its own.
+ *
+ * **Replace triggers.** `project`, `instance`, `name`, `host`, `type`.
+ * Type changes need a drop/recreate because Cloud SQL stores the auth
+ * shape immutably; we surface that via replace.
+ *
+ * @example IAM service-account user (workload identity → DB role)
+ * ```typescript
+ * yield* GCP.SqlUser("AppSaUser", {
+ *   project: instance.project,
+ *   instance: instance.name,
+ *   // App SA email is `app@my-project.iam.gserviceaccount.com` — strip
+ *   // `.gserviceaccount.com` so the Postgres role name fits in 63 chars.
+ *   name: "app@my-project.iam",
+ *   type: "CLOUD_IAM_SERVICE_ACCOUNT",
+ * });
+ * ```
+ *
+ * @example Built-in user with a Redacted password
+ * ```typescript
+ * yield* GCP.SqlUser("MigratorUser", {
+ *   project: instance.project,
+ *   instance: instance.name,
+ *   name: "migrator",
+ *   password: Redacted.make(process.env.MIGRATOR_PASSWORD!),
+ * });
+ * ```
+ *
+ * @see https://cloud.google.com/sql/docs/postgres/admin-api/rest/v1/users
+ * @see https://cloud.google.com/sql/docs/postgres/iam-authentication
+ */
+export type SqlUserProps = {
+    /**
+     * GCP project ID hosting the parent instance. Immutable — replace.
+     * @see https://cloud.google.com/sql/docs/postgres/admin-api/rest/v1/users#User
+     */
+    project: string;
+    /**
+     * Parent Cloud SQL instance name. Immutable — replace.
+     */
+    instance: string;
+    /**
+     * User/role name. For `BUILT_IN`, any valid Postgres identifier.
+     * For `CLOUD_IAM_USER`, the principal's email. For
+     * `CLOUD_IAM_SERVICE_ACCOUNT`, the SA email **with the trailing
+     * `.gserviceaccount.com` stripped** — Postgres role names cap at
+     * 63 chars; full SA emails are typically 70+. Immutable — replace.
+     */
+    name: string;
+    /**
+     * Host the user can connect from. PostgreSQL ignores this and
+     * defaults to `%` (any host). For MySQL it's load-bearing.
+     * Immutable — replace.
+     */
+    host?: string;
+    /**
+     * Auth backend. Defaults to `BUILT_IN` if unset.
+     * @see https://cloud.google.com/sql/docs/postgres/iam-authentication
+     */
+    type?: SqlUserType;
+    /**
+     * Password for `BUILT_IN` users. Required for that type; forbidden
+     * for any IAM type (validated at plan time).
+     */
+    password?: Redacted.Redacted<string>;
+};
+export type SqlUserAttributes = {
+    /** User name. */
+    name: string;
+    /** Parent instance name. */
+    instance: string;
+    /** Project ID. */
+    project: string;
+    /** Connecting host (defaults to `%` for Postgres). */
+    host: string;
+    /** Auth backend in effect. */
+    type: string;
+};
+export type SqlUser = Resource<"GCP.SqlUser", SqlUserProps, SqlUserAttributes, never, GCP.Providers>;
+export declare const SqlUser: import("alchemy").ResourceClass<SqlUser>;
+export declare const SqlUserProvider: () => import("effect/Layer").Layer<Provider.Provider<SqlUser>, never, import("effect/unstable/http/HttpClient").HttpClient | import("@distilled.cloud/gcp").Credentials>;
+//# sourceMappingURL=User.d.ts.map

package/lib/Sqladmin/User.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"User.d.ts","sourceRoot":"","sources":["../../src/Sqladmin/User.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAEnC,OAAO,KAAK,QAAQ,MAAM,kBAAkB,CAAC;AAE7C,OAAO,KAAK,QAAQ,MAAM,iBAAiB,CAAC;AAC5C,OAAO,KAAK,KAAK,GAAG,MAAM,iBAAiB,CAAC;AAE5C,OAAO,EAAiB,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AAG7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;;OAMG;IACH,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB;;;OAGG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;CACtC,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,iBAAiB;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,4BAA4B;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,kBAAkB;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,sDAAsD;IACtD,IAAI,EAAE,MAAM,CAAC;IACb,8BAA8B;IAC9B,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,OAAO,GAAG,QAAQ,CAC5B,aAAa,EACb,YAAY,EACZ,iBAAiB,EACjB,KAAK,EACL,GAAG,CAAC,SAAS,CACd,CAAC;AACF,eAAO,MAAM,OAAO,0CAAmC,CAAC;AAaxD,eAAO,MAAM,eAAe,0KAsMzB,CAAC"}

package/lib/Sqladmin/User.js

@@ -0,0 +1,156 @@
+import * as sql from "@distilled.cloud/gcp/sqladmin-v1";
+import { Resource } from "alchemy";
+import { isResolved, somePropsAreDifferent } from "alchemy/Diff";
+import * as Provider from "alchemy/Provider";
+import * as Effect from "effect/Effect";
+import * as Redacted from "effect/Redacted";
+import { makeAwaitOperation } from "./Operations.js";
+import { isIamUserType } from "./Types.js";
+import { reshapeBadRequest, validateUser } from "./Validation.js";
+export const SqlUser = Resource("GCP.SqlUser");
+const toAttributes = (u, parent) => ({
+    name: parent.name,
+    instance: parent.instance,
+    project: parent.project,
+    host: u.host ?? parent.host,
+    type: u.type ?? "BUILT_IN",
+});
+export const SqlUserProvider = () => Provider.effect(SqlUser, Effect.gen(function* () {
+    const getUsers = yield* sql.getUsers;
+    const listUsers = yield* sql.listUsers;
+    const insertUsers = yield* sql.insertUsers;
+    const updateUsers = yield* sql.updateUsers;
+    const deleteUsers = yield* sql.deleteUsers;
+    const getOperations = yield* sql.getOperations;
+    const awaitOperation = makeAwaitOperation(getOperations);
+    /**
+     * Observe a user. Cloud SQL's `getUsers` endpoint returns 404
+     * for IAM-typed users in some Postgres minor versions — those
+     * are listable but not directly addressable by `name`. Fall
+     * back to a list filter on 404 to be safe.
+     */
+    const observe = (project, instance, name, host) => getUsers({
+        project,
+        instance,
+        name,
+        ...(host ? { host } : {}),
+    }).pipe(Effect.catchTag("NotFound", () => listUsers({ project, instance }).pipe(Effect.map((res) => (res.items ?? []).find((u) => u.name === name && (host ? u.host === host : true))), Effect.catchTag("NotFound", () => Effect.succeed(undefined)), Effect.catchTag("Forbidden", () => Effect.succeed(undefined)))), Effect.catchTag("Forbidden", () => Effect.succeed(undefined)));
+    return {
+        stables: ["name", "instance", "project", "host", "type"],
+        diff: Effect.fn(function* ({ news, olds = {} }) {
+            if (!isResolved(news))
+                return undefined;
+            if (somePropsAreDifferent(olds, news, [
+                "project",
+                "instance",
+                "name",
+                "host",
+                "type",
+            ])) {
+                return { action: "replace" };
+            }
+            return undefined;
+        }),
+        reconcile: Effect.fn(function* ({ news, session }) {
+            const desiredType = news.type ?? "BUILT_IN";
+            const desiredHost = news.host ?? "%";
+            yield* validateUser({
+                name: news.name,
+                type: desiredType,
+                hasPassword: news.password !== undefined,
+            });
+            let observed = yield* observe(news.project, news.instance, news.name, news.host);
+            if (!observed) {
+                const body = {
+                    name: news.name,
+                    ...(news.host !== undefined ? { host: news.host } : {}),
+                    type: desiredType,
+                    ...(news.password
+                        ? { password: Redacted.value(news.password) }
+                        : {}),
+                };
+                const op = yield* insertUsers({
+                    project: news.project,
+                    instance: news.instance,
+                    body,
+                }).pipe(Effect.catchTag("Conflict", () => Effect.succeed(undefined)), Effect.catchTag("BadRequest", reshapeBadRequest("User", "insert")));
+                if (op?.name)
+                    yield* awaitOperation(news.project, op.name, session);
+                observed = yield* observe(news.project, news.instance, news.name, news.host);
+            }
+            else if (
+            // Only BUILT_IN users have a rotatable password. For IAM
+            // users the type is fixed at insert and there's nothing
+            // mutable to sync. We don't store/compare BUILT_IN
+            // passwords (they're write-only on the API side) — if the
+            // user explicitly supplies one we re-issue the update so
+            // a rotated `Redacted` propagates, but we can't detect
+            // drift here so this is a deliberate "user is source of
+            // truth" path.
+            !isIamUserType(desiredType) &&
+                news.password) {
+                const op = yield* updateUsers({
+                    project: news.project,
+                    instance: news.instance,
+                    name: news.name,
+                    ...(news.host !== undefined ? { host: news.host } : {}),
+                    body: {
+                        name: news.name,
+                        ...(news.host !== undefined ? { host: news.host } : {}),
+                        type: desiredType,
+                        password: Redacted.value(news.password),
+                    },
+                }).pipe(Effect.catchTag("BadRequest", reshapeBadRequest("User", "update")));
+                if (op.name)
+                    yield* awaitOperation(news.project, op.name, session);
+            }
+            // observed is non-undefined here: either we just created it
+            // and re-observed, or we found it pre-existing. If somehow
+            // listUsers still returns nothing (eventual consistency
+            // window), synthesise a minimal attribute set from inputs.
+            if (!observed) {
+                return {
+                    name: news.name,
+                    instance: news.instance,
+                    project: news.project,
+                    host: desiredHost,
+                    type: desiredType,
+                };
+            }
+            return toAttributes(observed, {
+                project: news.project,
+                instance: news.instance,
+                name: news.name,
+                host: desiredHost,
+            });
+        }),
+        delete: Effect.fn(function* ({ output, session }) {
+            yield* deleteUsers({
+                project: output.project,
+                instance: output.instance,
+                name: output.name,
+                ...(output.host && output.host !== "%" ? { host: output.host } : {}),
+            }).pipe(Effect.flatMap((op) => op.name
+                ? awaitOperation(output.project, op.name, session)
+                : Effect.succeed(op)), Effect.catchTag("NotFound", () => Effect.void), Effect.catchTag("BadRequest", reshapeBadRequest("User", "delete")));
+        }),
+        read: Effect.fn(function* ({ output, olds }) {
+            const project = output?.project ?? olds?.project;
+            const instance = output?.instance ?? olds?.instance;
+            const name = output?.name ?? olds?.name;
+            if (!project || !instance || !name)
+                return undefined;
+            const host = output?.host ?? olds?.host;
+            const observed = yield* observe(project, instance, name, host);
+            if (!observed)
+                return undefined;
+            return toAttributes(observed, {
+                project,
+                instance,
+                name,
+                host: host ?? "%",
+            });
+        }),
+    };
+}));
+//# sourceMappingURL=User.js.map

package/lib/Sqladmin/User.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"User.js","sourceRoot":"","sources":["../../src/Sqladmin/User.ts"],"names":[],"mappings":"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"}

package/lib/Sqladmin/Validation.d.ts

@@ -0,0 +1,60 @@
+import { ConfigError } from "@distilled.cloud/gcp";
+import * as Effect from "effect/Effect";
+import { type SqlUserType } from "./Types.ts";
+/**
+ * Validate a Cloud SQL instance name. Returns a `ConfigError` on the
+ * failure channel if the name is invalid, otherwise succeeds.
+ *
+ * @see https://cloud.google.com/sql/docs/postgres/admin-api/rest/v1/instances#SqlInstance
+ */
+export declare const validateInstanceName: (name: string) => Effect.Effect<void, ConfigError>;
+/**
+ * Validate a Cloud SQL database name (1–64 chars, non-empty).
+ *
+ * @see https://cloud.google.com/sql/docs/postgres/admin-api/rest/v1/databases#Database
+ */
+export declare const validateDatabaseName: (name: string) => Effect.Effect<void, ConfigError>;
+/**
+ * Validate a Cloud SQL user shape — primarily that the password/type
+ * combination is consistent:
+ *
+ * - `BUILT_IN` users MUST carry a password.
+ * - Any IAM user type (`CLOUD_IAM_USER`, `CLOUD_IAM_SERVICE_ACCOUNT`,
+ *   `CLOUD_IAM_GROUP*`, `ENTRAID_USER`) MUST NOT carry a password —
+ *   the IAM principal is authenticated by token exchange.
+ *
+ * Other types from the open tail of the enum (forward-compat) skip
+ * the password check.
+ *
+ * @see https://cloud.google.com/sql/docs/postgres/users
+ * @see https://cloud.google.com/sql/docs/postgres/iam-authentication
+ */
+export declare const validateUser: (args: {
+    name: string;
+    type: SqlUserType | undefined;
+    hasPassword: boolean;
+}) => Effect.Effect<void, ConfigError>;
+/**
+ * Reshape a `BadRequest` from a Cloud SQL Admin create/patch/delete
+ * into a `ConfigError` with a remediation hint for the top failure
+ * modes:
+ *
+ * 1. **Billing not enabled** — Cloud SQL refuses to provision against
+ *    a project without billing. Common right after `ApiEnable` lands
+ *    but before billing reconciles in a fresh project.
+ * 2. **Private network not set up** — `privateNetwork` references a
+ *    VPC that has no PSA peering for `servicenetworking.googleapis.com`.
+ *    Surface the precondition.
+ * 3. **Invalid tier** — typo'd `db-custom-…` or one outside the
+ *    project's allow-list. Pass the underlying message through with
+ *    a pointer to the tier catalogue.
+ *
+ * Anything else propagates verbatim — the underlying GCP message is
+ * usually clear enough.
+ *
+ * @see https://cloud.google.com/sql/docs/postgres/instance-settings
+ */
+export declare const reshapeBadRequest: (kind: "Instance" | "Database" | "User", op: "insert" | "patch" | "update" | "delete") => (e: {
+    message?: string;
+}) => Effect.Effect<never, ConfigError>;
+//# sourceMappingURL=Validation.d.ts.map

package/lib/Sqladmin/Validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Validation.d.ts","sourceRoot":"","sources":["../../src/Sqladmin/Validation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACnD,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,EAAiB,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AAgC7D;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,GAC/B,MAAM,MAAM,KACX,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,WAAW,CASjC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,GAC/B,MAAM,MAAM,KACX,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,WAAW,CAOjC,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,YAAY,GAAI,MAAM;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,WAAW,GAAG,SAAS,CAAC;IAC9B,WAAW,EAAE,OAAO,CAAC;CACtB,KAAG,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,WAAW,CAiBlC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,iBAAiB,GAC3B,MAAM,UAAU,GAAG,UAAU,GAAG,MAAM,EAAE,IAAI,QAAQ,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,MACpF,GAAG;IAAE,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,KAAG,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,WAAW,CAkB1D,CAAC"}

package/lib/Sqladmin/Validation.js

@@ -0,0 +1,125 @@
+import { ConfigError } from "@distilled.cloud/gcp";
+import * as Effect from "effect/Effect";
+import { isIamUserType } from "./Types.js";
+/**
+ * Plan-time validation for Cloud SQL resource props. Failing fast with
+ * a typed `ConfigError` is friendlier than letting the user wait for
+ * Cloud SQL to reject the request, and unlike server-side errors these
+ * surface before any state mutation happens.
+ *
+ * @see https://cloud.google.com/sql/docs/postgres/admin-api/rest/v1/instances
+ */
+/**
+ * Instance name regex per
+ * <https://cloud.google.com/sql/docs/postgres/admin-api/rest/v1/instances#SqlInstance>:
+ * 1–98 lowercase letters/digits/hyphens, must begin with a letter and
+ * not end with a hyphen.
+ *
+ * @internal
+ */
+const INSTANCE_NAME_RE = /^[a-z]([-a-z0-9]*[a-z0-9])?$/;
+/**
+ * Database name length cap per
+ * <https://cloud.google.com/sql/docs/postgres/admin-api/rest/v1/databases#Database>:
+ * 1–64 chars. Postgres has additional character constraints (no NUL,
+ * no embedded quotes) but the API rejects those, and they'd require
+ * dialect-specific parsing here.
+ *
+ * @internal
+ */
+const DATABASE_NAME_MAX = 64;
+/**
+ * Validate a Cloud SQL instance name. Returns a `ConfigError` on the
+ * failure channel if the name is invalid, otherwise succeeds.
+ *
+ * @see https://cloud.google.com/sql/docs/postgres/admin-api/rest/v1/instances#SqlInstance
+ */
+export const validateInstanceName = (name) => {
+    if (INSTANCE_NAME_RE.test(name) && name.length >= 1 && name.length <= 98) {
+        return Effect.void;
+    }
+    return Effect.fail(new ConfigError({
+        message: `Cloud SQL instance name ${JSON.stringify(name)} is invalid: must match /^[a-z]([-a-z0-9]*[a-z0-9])?$/ (1–98 lowercase letters/digits/hyphens, start with letter, no trailing hyphen).`,
+    }));
+};
+/**
+ * Validate a Cloud SQL database name (1–64 chars, non-empty).
+ *
+ * @see https://cloud.google.com/sql/docs/postgres/admin-api/rest/v1/databases#Database
+ */
+export const validateDatabaseName = (name) => {
+    if (name.length >= 1 && name.length <= DATABASE_NAME_MAX)
+        return Effect.void;
+    return Effect.fail(new ConfigError({
+        message: `Cloud SQL database name ${JSON.stringify(name)} is invalid: must be 1–${DATABASE_NAME_MAX} characters.`,
+    }));
+};
+/**
+ * Validate a Cloud SQL user shape — primarily that the password/type
+ * combination is consistent:
+ *
+ * - `BUILT_IN` users MUST carry a password.
+ * - Any IAM user type (`CLOUD_IAM_USER`, `CLOUD_IAM_SERVICE_ACCOUNT`,
+ *   `CLOUD_IAM_GROUP*`, `ENTRAID_USER`) MUST NOT carry a password —
+ *   the IAM principal is authenticated by token exchange.
+ *
+ * Other types from the open tail of the enum (forward-compat) skip
+ * the password check.
+ *
+ * @see https://cloud.google.com/sql/docs/postgres/users
+ * @see https://cloud.google.com/sql/docs/postgres/iam-authentication
+ */
+export const validateUser = (args) => {
+    const type = args.type ?? "BUILT_IN";
+    if (isIamUserType(type) && args.hasPassword) {
+        return Effect.fail(new ConfigError({
+            message: `Cloud SQL user ${JSON.stringify(args.name)} has type ${JSON.stringify(type)} (IAM-backed) but a password was supplied. IAM users authenticate via the Cloud SQL Auth Proxy / IAM token exchange — drop the \`password\` field.`,
+        }));
+    }
+    if (type === "BUILT_IN" && !args.hasPassword) {
+        return Effect.fail(new ConfigError({
+            message: `Cloud SQL user ${JSON.stringify(args.name)} has type "BUILT_IN" but no password was supplied. BUILT_IN users require a password — pass \`password: Redacted.make("...")\` or switch to an IAM type.`,
+        }));
+    }
+    return Effect.void;
+};
+/**
+ * Reshape a `BadRequest` from a Cloud SQL Admin create/patch/delete
+ * into a `ConfigError` with a remediation hint for the top failure
+ * modes:
+ *
+ * 1. **Billing not enabled** — Cloud SQL refuses to provision against
+ *    a project without billing. Common right after `ApiEnable` lands
+ *    but before billing reconciles in a fresh project.
+ * 2. **Private network not set up** — `privateNetwork` references a
+ *    VPC that has no PSA peering for `servicenetworking.googleapis.com`.
+ *    Surface the precondition.
+ * 3. **Invalid tier** — typo'd `db-custom-…` or one outside the
+ *    project's allow-list. Pass the underlying message through with
+ *    a pointer to the tier catalogue.
+ *
+ * Anything else propagates verbatim — the underlying GCP message is
+ * usually clear enough.
+ *
+ * @see https://cloud.google.com/sql/docs/postgres/instance-settings
+ */
+export const reshapeBadRequest = (kind, op) => (e) => {
+    const underlying = e.message ?? `unknown 400 from ${kind} ${op}`;
+    let hint = "";
+    if (/billing/i.test(underlying)) {
+        hint =
+            " Cloud SQL requires billing to be enabled on the project. Attach a billing account (see `GCP.Project({ billingAccount })`) and retry.";
+    }
+    else if (/private.*service.*access|servicenetworking|peering/i.test(underlying)) {
+        hint =
+            " The host VPC needs a Private Services Access (PSA) peering with `servicenetworking.googleapis.com` before a private-IP Cloud SQL instance can attach. Provision a `GCP.GlobalAddress` (purpose=VPC_PEERING) and a `GCP.PsaConnection` on the VPC first.";
+    }
+    else if (/tier|machine.*type/i.test(underlying)) {
+        hint =
+            " Check the tier identifier against https://cloud.google.com/sql/docs/postgres/instance-settings — and remember that Enterprise Plus tiers (`db-perf-optimized-*`) require `edition: \"ENTERPRISE_PLUS\"`.";
+    }
+    return Effect.fail(new ConfigError({
+        message: `Cloud SQL ${kind} ${op} rejected: ${underlying}.${hint}`,
+    }));
+};
+//# sourceMappingURL=Validation.js.map

package/lib/Sqladmin/Validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Validation.js","sourceRoot":"","sources":["../../src/Sqladmin/Validation.ts"],"names":[],"mappings":"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"}