@dbx-tools/appkit-autopg 0.1.0

package/README.md

@@ -0,0 +1,113 @@
+# @dbx-tools/appkit-autopg
+
+`autopg()` is a one-line helper that fills in every Lakebase Postgres
+env var the AppKit `lakebase` plugin needs from whatever fragments your
+deployment actually carries. Run it once before `createApp(...)` and stop
+hand-rolling connection strings:
+
+```ts
+import { createApp, lakebase, server } from "@databricks/appkit";
+import { autopg } from "@dbx-tools/appkit-autopg";
+
+await autopg();
+await createApp({ plugins: [server(), lakebase()] });
+```
+
+## Why a top-level helper instead of an AppKit plugin
+
+AppKit's `static phase` field orders plugin `setup()` _invocation_, not
+async _completion_. `lakebase.setup()` synchronously throws on a missing
+`PGHOST` after its first `await`, so a sibling plugin that performs REST
+discovery during `setup()` races and loses every time. Awaiting
+`autopg()` before `createApp(...)` sidesteps the race - by the time any
+plugin runs, `process.env` is fully populated.
+
+## What it accepts
+
+`autopg()` looks at, in priority order:
+
+1. Explicit `autopg({ project, branch, endpoint, database, host, port, sslMode, autoCreate })`
+2. Env vars - the same ones `lakebase` already reads:
+   - `LAKEBASE_PROJECT`, `LAKEBASE_BRANCH`, `LAKEBASE_ENDPOINT`
+   - `PGHOST`, `PGDATABASE`, `PGPORT`, `PGSSLMODE`
+3. Whatever the address parser can recover from
+   `LAKEBASE_ENDPOINT` / `config.endpoint`
+
+The address input is permissive - any of these work:
+
+```bash
+# Canonical resource path
+LAKEBASE_ENDPOINT="projects/dbx-tools/branches/main/endpoints/primary"
+
+# Full Postgres URI (auth, host, db, sslmode all extracted)
+LAKEBASE_ENDPOINT="postgresql://me%40databricks.com@ep-foo.database.azuredatabricks.net/databricks_postgres?sslmode=require"
+
+# Bare Lakebase hostname (resolver reverse-looks-up the project)
+LAKEBASE_ENDPOINT="ep-steep-forest-e199v43w.database.eastus2.azuredatabricks.net"
+
+# Bare project id (resolver picks the default branch + endpoint + db)
+LAKEBASE_ENDPOINT="dbx-tools"
+```
+
+## Three resolution modes
+
+After parsing, the resolver fills gaps in this order:
+
+1. **Reverse-lookup** - given just a host, scan
+   `projects` -> `branches` -> `endpoints` for a matching
+   `status.hosts.host` and recover the owning resource path.
+2. **Pick default** - given a `project` (and optionally a `branch`),
+   prefer the server-marked default child (`status.default`,
+   `ENDPOINT_TYPE_READ_WRITE`, `databricks_postgres`) and fall back to
+   "the only one" when a listing returns a single result.
+3. **Auto-create** - when no projects exist at all, create one whose id
+   defaults to a slugified `projectUtils.name()` (override with
+   `autoCreate: "my-id"` or disable with `autoCreate: false`). The
+   create call is idempotent: an `ALREADY_EXISTS` response from a
+   concurrent boot is treated as success. Then poll the default
+   endpoint until `current_state` is `READY` or `IDLE`.
+
+## Options
+
+```ts
+await autopg({
+  // Skip writing process.env (just inspect the returned record).
+  exportEnv: false,
+  // Pin individual fields - any of these short-circuit the resolver.
+  project: "dbx-tools",
+  branch: "main",
+  endpoint: "projects/dbx-tools/branches/main/endpoints/primary",
+  database: "databricks_postgres",
+  // Auto-create behavior.
+  autoCreate: false, // throw if no project exists
+  // autoCreate: "my-custom-id", // create with this id
+});
+```
+
+`autopg()` returns a `Resolved` record (`project`, `branch`, `endpoint`,
+`database`, `host`, `port`, `sslMode`). When `exportEnv: true` (the
+default) it also writes the same values to `process.env`, only filling
+gaps - existing values are preserved.
+
+## Address parser
+
+The address parser is exported as well if you want it without the
+resolver wrapper:
+
+```ts
+import { parseAddress } from "@dbx-tools/appkit-autopg";
+
+parseAddress("postgresql://user@ep-foo.database.azuredatabricks.net/dbpg");
+// { user, host, database, port?, sslMode?, project?, branch?, endpointId? }
+```
+
+## Required permissions
+
+The Databricks user / SP behind `getWorkspaceClient()` needs
+`postgres.projects.{list,create}`, `postgres.branches.list`,
+`postgres.endpoints.{list,get}`, and `postgres.databases.list` on the
+account.
+
+## License
+
+Apache-2.0

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * `@dbx-tools/appkit-autopg` - top-level Lakebase Postgres auto-
+ * discovery helper. Resolves project / branch / endpoint / database /
+ * host from env vars and the Databricks REST API, then writes the
+ * standard `PGHOST` / `PGDATABASE` / `LAKEBASE_ENDPOINT` env vars so
+ * the AppKit `lakebase` plugin can connect without manual wiring.
+ *
+ * ```ts
+ * import { autopg } from "@dbx-tools/appkit-autopg";
+ * import { createApp, lakebase, server } from "@databricks/appkit";
+ *
+ * await autopg();
+ * await createApp({ plugins: [lakebase(), server()] });
+ * ```
+ */
+export * from "./src/address.js";
+export * from "./src/autopg.js";
+export * from "./src/resolver.js";

package/dist/index.js

@@ -0,0 +1,18 @@
+/**
+ * `@dbx-tools/appkit-autopg` - top-level Lakebase Postgres auto-
+ * discovery helper. Resolves project / branch / endpoint / database /
+ * host from env vars and the Databricks REST API, then writes the
+ * standard `PGHOST` / `PGDATABASE` / `LAKEBASE_ENDPOINT` env vars so
+ * the AppKit `lakebase` plugin can connect without manual wiring.
+ *
+ * ```ts
+ * import { autopg } from "@dbx-tools/appkit-autopg";
+ * import { createApp, lakebase, server } from "@databricks/appkit";
+ *
+ * await autopg();
+ * await createApp({ plugins: [lakebase(), server()] });
+ * ```
+ */
+export * from "./src/address.js";
+export * from "./src/autopg.js";
+export * from "./src/resolver.js";

package/dist/src/address.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Flexible address parser for Lakebase Postgres connection inputs.
+ *
+ * Accepts whatever shape a user is likely to paste into
+ * `LAKEBASE_ENDPOINT` (or the matching config field) and extracts
+ * every recognizable piece. Whatever it can't recover is left for the
+ * REST resolver to discover.
+ *
+ * Recognized formats:
+ *
+ * - **Postgres URI** -
+ *   `postgresql://user@host:port/db?sslmode=require` (also `postgres://`).
+ *   Yields `user`, `host`, `port`, `database`, `sslMode`.
+ *
+ * - **Canonical endpoint resource path** -
+ *   `projects/{p}/branches/{b}/endpoints/{e}` -
+ *   yields `project`, `branch`, `endpointId`, and the original string as
+ *   `endpoint` (already in lakebase's expected form).
+ *
+ * - **Database resource path** -
+ *   `projects/{p}/branches/{b}/databases/{d}` -
+ *   yields `project`, `branch`. The database leaf isn't surfaced because
+ *   it's a resource id, not the Postgres database name; the resolver
+ *   will look up the real `status.postgres_database` value via REST.
+ *
+ * - **Branch resource path** -
+ *   `projects/{p}/branches/{b}` - yields `project`, `branch`.
+ *
+ * - **Project resource path** -
+ *   `projects/{p}` - yields `project`.
+ *
+ * - **Bare hostname** -
+ *   `ep-steep-forest-e199v43w.database.eastus2.azuredatabricks.net` -
+ *   yields `host` only; the resolver reverse-looks up the owning
+ *   endpoint to recover the resource path.
+ *
+ * - **Bare project id** -
+ *   `dbx-tools-demo` (1-63 chars, lowercase letters/digits/hyphens) -
+ *   yields `project`.
+ *
+ * Returns an empty object for inputs it doesn't recognize.
+ */
+import type { SslMode } from "./resolver.js";
+export interface ParsedAddress {
+    /** Lakebase project id. */
+    project?: string;
+    /** Branch id within the project. */
+    branch?: string;
+    /** Endpoint leaf id (last segment of an endpoint resource path). */
+    endpointId?: string;
+    /** Canonical endpoint resource path; only set for matching inputs. */
+    endpoint?: string;
+    /** Postgres database name (PGDATABASE) when parsed from a URI path. */
+    database?: string;
+    /** Postgres hostname. */
+    host?: string;
+    /** Postgres port. */
+    port?: number;
+    /** Postgres user (URI-decoded if encoded). */
+    user?: string;
+    /** Postgres TLS mode. */
+    sslMode?: SslMode;
+}
+/**
+ * Parse a Lakebase connection input into whatever pieces it carries.
+ * See module docstring for the supported formats. Returns `{}` for
+ * `undefined`, empty strings, and unrecognized inputs.
+ */
+export declare function parseAddress(input: string | undefined | null): ParsedAddress;

package/dist/src/address.js

@@ -0,0 +1,132 @@
+/**
+ * Flexible address parser for Lakebase Postgres connection inputs.
+ *
+ * Accepts whatever shape a user is likely to paste into
+ * `LAKEBASE_ENDPOINT` (or the matching config field) and extracts
+ * every recognizable piece. Whatever it can't recover is left for the
+ * REST resolver to discover.
+ *
+ * Recognized formats:
+ *
+ * - **Postgres URI** -
+ *   `postgresql://user@host:port/db?sslmode=require` (also `postgres://`).
+ *   Yields `user`, `host`, `port`, `database`, `sslMode`.
+ *
+ * - **Canonical endpoint resource path** -
+ *   `projects/{p}/branches/{b}/endpoints/{e}` -
+ *   yields `project`, `branch`, `endpointId`, and the original string as
+ *   `endpoint` (already in lakebase's expected form).
+ *
+ * - **Database resource path** -
+ *   `projects/{p}/branches/{b}/databases/{d}` -
+ *   yields `project`, `branch`. The database leaf isn't surfaced because
+ *   it's a resource id, not the Postgres database name; the resolver
+ *   will look up the real `status.postgres_database` value via REST.
+ *
+ * - **Branch resource path** -
+ *   `projects/{p}/branches/{b}` - yields `project`, `branch`.
+ *
+ * - **Project resource path** -
+ *   `projects/{p}` - yields `project`.
+ *
+ * - **Bare hostname** -
+ *   `ep-steep-forest-e199v43w.database.eastus2.azuredatabricks.net` -
+ *   yields `host` only; the resolver reverse-looks up the owning
+ *   endpoint to recover the resource path.
+ *
+ * - **Bare project id** -
+ *   `dbx-tools-demo` (1-63 chars, lowercase letters/digits/hyphens) -
+ *   yields `project`.
+ *
+ * Returns an empty object for inputs it doesn't recognize.
+ */
+const URL_SCHEME_RE = /^(postgres|postgresql):\/\//i;
+const RESOURCE_ENDPOINT_RE = /^projects\/([^/]+)\/branches\/([^/]+)\/endpoints\/([^/]+)$/;
+const RESOURCE_DATABASE_RE = /^projects\/([^/]+)\/branches\/([^/]+)\/databases\/([^/]+)$/;
+const RESOURCE_BRANCH_RE = /^projects\/([^/]+)\/branches\/([^/]+)$/;
+const RESOURCE_PROJECT_RE = /^projects\/([^/]+)$/;
+const PROJECT_ID_RE = /^[a-z][a-z0-9-]{0,61}[a-z0-9]$|^[a-z]$/;
+const HOSTNAME_HINT_RE = /^[a-z0-9][a-z0-9-]*(\.[a-z0-9][a-z0-9-]*)+$/i;
+/**
+ * Parse a Lakebase connection input into whatever pieces it carries.
+ * See module docstring for the supported formats. Returns `{}` for
+ * `undefined`, empty strings, and unrecognized inputs.
+ */
+export function parseAddress(input) {
+    if (!input)
+        return {};
+    const s = input.trim();
+    if (!s)
+        return {};
+    if (URL_SCHEME_RE.test(s))
+        return parseUri(s);
+    if (s.startsWith("projects/"))
+        return parseResourcePath(s);
+    // Resource ids never contain dots; a dotted input must be a hostname.
+    if (HOSTNAME_HINT_RE.test(s) && s.includes("."))
+        return { host: s };
+    if (PROJECT_ID_RE.test(s))
+        return { project: s };
+    return {};
+}
+function parseUri(s) {
+    let url;
+    try {
+        url = new URL(s);
+    }
+    catch {
+        return {};
+    }
+    const result = {};
+    if (url.hostname)
+        result.host = url.hostname;
+    if (url.port) {
+        const port = Number.parseInt(url.port, 10);
+        if (!Number.isNaN(port))
+            result.port = port;
+    }
+    if (url.username) {
+        try {
+            result.user = decodeURIComponent(url.username);
+        }
+        catch {
+            // Malformed percent-escape; keep the raw form.
+            result.user = url.username;
+        }
+    }
+    const db = url.pathname.replace(/^\//, "");
+    if (db)
+        result.database = decodeURIComponent(db);
+    // Postgres clients accept `sslmode`; URL params are case-sensitive but
+    // we tolerate either since users paste both.
+    const sslmodeRaw = url.searchParams.get("sslmode") ?? url.searchParams.get("sslMode");
+    const sslmode = sslmodeRaw?.toLowerCase();
+    if (sslmode === "require" || sslmode === "disable" || sslmode === "prefer") {
+        result.sslMode = sslmode;
+    }
+    return result;
+}
+function parseResourcePath(s) {
+    const ep = RESOURCE_ENDPOINT_RE.exec(s);
+    if (ep) {
+        return {
+            project: ep[1],
+            branch: ep[2],
+            endpointId: ep[3],
+            endpoint: s,
+        };
+    }
+    // databases/{d} is a resource id (often kebab-case), not the actual
+    // Postgres database name. Surface project + branch only; the resolver
+    // will fetch the real `postgres_database` value.
+    const db = RESOURCE_DATABASE_RE.exec(s);
+    if (db)
+        return { project: db[1], branch: db[2] };
+    const br = RESOURCE_BRANCH_RE.exec(s);
+    if (br)
+        return { project: br[1], branch: br[2] };
+    const pr = RESOURCE_PROJECT_RE.exec(s);
+    if (pr)
+        return { project: pr[1] };
+    return {};
+}

package/dist/src/autopg.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Top-level Lakebase auto-discovery helper.
+ *
+ * Read this once at process startup BEFORE `createApp(...)` so the
+ * `lakebase` plugin (and anyone else who reads `process.env` during
+ * `setup()`) sees a fully-populated environment:
+ *
+ * ```ts
+ * import { autopg } from "@dbx-tools/appkit-autopg";
+ * import { createApp, lakebase, server } from "@databricks/appkit";
+ *
+ * await autopg();              // resolves + writes process.env
+ * await createApp({ plugins: [lakebase(), server()] });
+ * ```
+ *
+ * `autopg` is intentionally NOT an AppKit plugin. AppKit's `static phase`
+ * field only orders plugin `setup()` invocation, not async completion -
+ * `lakebase.setup()` calls `parsePoolConfig` synchronously after its
+ * first `await` and would throw on `PGHOST` before any sibling plugin's
+ * REST resolution could finish. Awaiting `autopg()` upfront sidesteps
+ * the race entirely.
+ *
+ * Inputs flow in this priority order:
+ *   1. Explicit `config.<field>` argument
+ *   2. Matching env var (`LAKEBASE_PROJECT`, `LAKEBASE_BRANCH`,
+ *      `LAKEBASE_ENDPOINT`, `PGHOST`, `PGDATABASE`, `PGPORT`, `PGSSLMODE`)
+ *   3. Derived from the Lakebase Autoscaling REST API under
+ *      `/api/2.0/postgres/` via the Databricks workspace client
+ *
+ * Resolved values are written back to `process.env` (only filling gaps;
+ * existing values are preserved) so the downstream `lakebase` plugin
+ * picks them up. Pass `{ exportEnv: false }` to keep `process.env`
+ * untouched and just inspect the returned record.
+ */
+import { type Resolved, type ResolverInputs } from "./resolver.js";
+/** Options accepted by {@link autopg}. */
+export interface AutopgOptions extends ResolverInputs {
+    /**
+     * When `true` (the default), resolved values are written to
+     * `process.env` so the `lakebase` plugin sees them at startup.
+     * Set to `false` to leave `process.env` untouched and just receive
+     * the resolved record back.
+     */
+    exportEnv?: boolean;
+}
+/**
+ * Resolve Lakebase Postgres connection info from config + env (and the
+ * Databricks REST API when needed), write the resolved values to
+ * `process.env`, and return the fully-populated record.
+ *
+ * Always safe to call: when env already provides every field, it
+ * returns immediately without any network traffic.
+ *
+ * @throws when a `project` is set (directly or via env) but the
+ *   Databricks API returns no branches / endpoints / databases to
+ *   choose from. The error message lists the available candidates so
+ *   the caller can pin the right one via env or config.
+ */
+export declare function autopg(opts?: AutopgOptions): Promise<Resolved>;

package/dist/src/autopg.js

@@ -0,0 +1,74 @@
+/**
+ * Top-level Lakebase auto-discovery helper.
+ *
+ * Read this once at process startup BEFORE `createApp(...)` so the
+ * `lakebase` plugin (and anyone else who reads `process.env` during
+ * `setup()`) sees a fully-populated environment:
+ *
+ * ```ts
+ * import { autopg } from "@dbx-tools/appkit-autopg";
+ * import { createApp, lakebase, server } from "@databricks/appkit";
+ *
+ * await autopg();              // resolves + writes process.env
+ * await createApp({ plugins: [lakebase(), server()] });
+ * ```
+ *
+ * `autopg` is intentionally NOT an AppKit plugin. AppKit's `static phase`
+ * field only orders plugin `setup()` invocation, not async completion -
+ * `lakebase.setup()` calls `parsePoolConfig` synchronously after its
+ * first `await` and would throw on `PGHOST` before any sibling plugin's
+ * REST resolution could finish. Awaiting `autopg()` upfront sidesteps
+ * the race entirely.
+ *
+ * Inputs flow in this priority order:
+ *   1. Explicit `config.<field>` argument
+ *   2. Matching env var (`LAKEBASE_PROJECT`, `LAKEBASE_BRANCH`,
+ *      `LAKEBASE_ENDPOINT`, `PGHOST`, `PGDATABASE`, `PGPORT`, `PGSSLMODE`)
+ *   3. Derived from the Lakebase Autoscaling REST API under
+ *      `/api/2.0/postgres/` via the Databricks workspace client
+ *
+ * Resolved values are written back to `process.env` (only filling gaps;
+ * existing values are preserved) so the downstream `lakebase` plugin
+ * picks them up. Pass `{ exportEnv: false }` to keep `process.env`
+ * untouched and just inspect the returned record.
+ */
+import { logUtils } from "@dbx-tools/appkit-shared";
+import { applyToEnv, resolveConnection, } from "./resolver.js";
+/**
+ * Resolve Lakebase Postgres connection info from config + env (and the
+ * Databricks REST API when needed), write the resolved values to
+ * `process.env`, and return the fully-populated record.
+ *
+ * Always safe to call: when env already provides every field, it
+ * returns immediately without any network traffic.
+ *
+ * @throws when a `project` is set (directly or via env) but the
+ *   Databricks API returns no branches / endpoints / databases to
+ *   choose from. The error message lists the available candidates so
+ *   the caller can pin the right one via env or config.
+ */
+export async function autopg(opts = {}) {
+    const { exportEnv = true, ...inputs } = opts;
+    const log = logUtils.logger("autopg");
+    const resolved = await resolveConnection(inputs, log);
+    if (exportEnv) {
+        applyToEnv(resolved);
+        log.info("env updated", redactForLog(resolved));
+    }
+    else {
+        log.info("resolved (env untouched)", redactForLog(resolved));
+    }
+    return resolved;
+}
+/** Strip resolved record to log-safe primitive fields. */
+function redactForLog(resolved) {
+    return {
+        project: resolved.project,
+        branch: resolved.branch,
+        endpoint: resolved.endpoint,
+        database: resolved.database,
+        host: resolved.host,
+        port: resolved.port,
+        sslMode: resolved.sslMode,
+    };
+}

package/dist/src/resolver.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Lakebase Postgres connection resolver.
+ *
+ * Reads the same env vars the `lakebase` plugin consumes (`PGHOST`,
+ * `PGDATABASE`, `PGPORT`, `PGSSLMODE`, `LAKEBASE_ENDPOINT`) and fills in
+ * whichever pieces are missing using the Lakebase Autoscaling REST API
+ * under `/api/2.0/postgres/` via the Databricks workspace client.
+ *
+ * `LAKEBASE_ENDPOINT` (and `config.endpoint`) accept anything
+ * {@link parseAddress} understands - canonical resource paths, Postgres
+ * URIs, bare hostnames, or bare project ids. The resolver layers
+ * whatever pieces fall out of parsing under explicit config / env
+ * values, then fills the remaining gaps via the API:
+ *
+ *   1. Reverse-lookup: when a host is known but no resource path is,
+ *      scan projects -> branches -> endpoints for a matching
+ *      `status.hosts.host` and recover the owning project/branch/endpoint.
+ *   2. Pick: when a project is known but child resources aren't, prefer
+ *      the server-side default (`status.default`, `ENDPOINT_TYPE_READ_WRITE`,
+ *      `databricks_postgres`) and fall back to "the only one" when a
+ *      listing returns a single result.
+ *   3. Auto-create: when no projects exist at all, create one whose
+ *      id defaults to `projectUtils.name()` slugified (override
+ *      with `config.autoCreate: "my-id"` or disable with
+ *      `config.autoCreate: false`). The create call is idempotent - an
+ *      `ALREADY_EXISTS` response from a concurrent boot is treated as
+ *      success. Then poll the default endpoint until it reports
+ *      `current_state` `READY` or `IDLE`.
+ *
+ * The {@link autopg} helper then writes the resolved values back to
+ * `process.env` so the downstream `lakebase` plugin picks them up.
+ *
+ * @see https://docs.databricks.com/api/workspace/postgres
+ */
+import { type logUtils } from "@dbx-tools/appkit-shared";
+/** Postgres TLS mode passed through to `pg`. */
+export type SslMode = "require" | "disable" | "prefer";
+/**
+ * User-supplied inputs (config or env) before any API resolution. Every
+ * field is optional - the resolver tries to fill in missing pieces from
+ * the Lakebase API when it has enough context (typically a `project`).
+ */
+export interface ResolverInputs {
+    /** Lakebase project id, e.g. `my-app`. Triggers API discovery when set. */
+    project?: string;
+    /** Branch id within the project. Defaults to the server-marked default. */
+    branch?: string;
+    /**
+     * Lakebase address - accepts a canonical endpoint/branch/project
+     * resource path, a Postgres URI (`postgresql://user@host/db?...`),
+     * a bare Lakebase hostname, or a bare project id. Whatever pieces it
+     * carries seed the resolver before REST lookups happen. Reads from
+     * `LAKEBASE_ENDPOINT` when not set.
+     */
+    endpoint?: string;
+    /** Postgres database name (e.g. `databricks_postgres`). */
+    database?: string;
+    /** Postgres hostname; auto-derived from the endpoint when missing. */
+    host?: string;
+    /** Postgres port. Defaults to 5432. */
+    port?: number;
+    /** TLS mode. Defaults to `require`. */
+    sslMode?: SslMode;
+    /**
+     * What to do when no project exists in the workspace at all.
+     * - `undefined` (default): derive a project id from
+     *   {@link projectUtils.name} (the host repo's `package.json`
+     *   name) slugified to Lakebase id constraints, then create it.
+     * - `string`: create a new project with this exact id.
+     * - `false`: skip creation and throw with a clear error message.
+     */
+    autoCreate?: string | false;
+}
+/** Fully-resolved connection. `port` and `sslMode` always have a value. */
+export interface Resolved {
+    project?: string;
+    branch?: string;
+    endpoint?: string;
+    database?: string;
+    host?: string;
+    port: number;
+    sslMode: SslMode;
+}
+/**
+ * Pull resolver inputs from `process.env`, parse the address blob, and
+ * layer explicit config on top with this precedence:
+ *
+ *   `config.<field>` > matching env var > whatever {@link parseAddress}
+ *   recovered from the `endpoint` / `LAKEBASE_ENDPOINT` blob.
+ */
+export declare function readInputs(config: ResolverInputs): ResolverInputs;
+/**
+ * Resolve a fully-populated Postgres connection record from config + env.
+ *
+ * Returns immediately without network traffic when env already supplies
+ * `endpoint`, `host`, and `database`. Otherwise issues REST calls and
+ * may auto-create a project (see module docstring).
+ */
+export declare function resolveConnection(config: ResolverInputs, log: logUtils.Logger): Promise<Resolved>;
+/**
+ * Write resolved values back to `process.env` so the `lakebase` plugin
+ * (which reads env directly) picks them up during its own `setup()`.
+ * Existing env values are preserved; only missing keys are filled in,
+ * which keeps explicit overrides authoritative.
+ */
+export declare function applyToEnv(resolved: Resolved): void;
+/** Parse `projects/{p}/branches/{b}/endpoints/{e}` into its components. */
+export declare function parseEndpointName(endpoint: string): {
+    project: string;
+    branch: string;
+    endpointId: string;
+} | null;
+/** Parse `projects/{p}/branches/{b}/databases/{d}` into its components. */
+export declare function parseDatabaseName(database: string): {
+    project: string;
+    branch: string;
+    databaseId: string;
+} | null;