@databricks-solutions/lakebase-scm-utils 0.3.8 → 0.3.10

package/dist/scripts/lakebase/snapshot.cli.js

@@ -0,0 +1,395 @@
+#!/usr/bin/env node
+
+// scripts/lakebase/databricks-cli.ts
+import { execFile, execFileSync as execFileSync2 } from "child_process";
+import { promisify } from "util";
+import { join as join2 } from "path";
+
+// scripts/lakebase/kit-config.ts
+function intFromEnv(name, fallback) {
+  const raw = process.env[name];
+  if (!raw) return fallback;
+  const parsed = Number.parseInt(raw, 10);
+  if (!Number.isFinite(parsed) || parsed <= 0) return fallback;
+  return parsed;
+}
+var DAY_MS = 24 * 60 * 60 * 1e3;
+var KIT_TIMEOUTS = {
+  cliDefault: intFromEnv("LAKEBASE_KIT_TIMEOUT_CLI_DEFAULT_MS", 3e4),
+  cliCreateProject: intFromEnv("LAKEBASE_KIT_TIMEOUT_CLI_CREATE_PROJECT_MS", 18e4),
+  cliCreateBranch: intFromEnv("LAKEBASE_KIT_TIMEOUT_CLI_CREATE_BRANCH_MS", 6e4),
+  cliCreateEndpoint: intFromEnv("LAKEBASE_KIT_TIMEOUT_CLI_CREATE_ENDPOINT_MS", 6e4),
+  readyWait: intFromEnv("LAKEBASE_KIT_TIMEOUT_READY_WAIT_MS", 12e4),
+  readyPoll: intFromEnv("LAKEBASE_KIT_TIMEOUT_READY_POLL_MS", 5e3),
+  pgConnect: intFromEnv("LAKEBASE_KIT_TIMEOUT_PG_CONNECT_MS", 1e4),
+  pgStatement: intFromEnv("LAKEBASE_KIT_TIMEOUT_PG_STATEMENT_MS", 15e3),
+  gitDefault: intFromEnv("LAKEBASE_KIT_TIMEOUT_GIT_DEFAULT_MS", 5e3),
+  gitCheckout: intFromEnv("LAKEBASE_KIT_TIMEOUT_GIT_CHECKOUT_MS", 1e4),
+  gitNetwork: intFromEnv("LAKEBASE_KIT_TIMEOUT_GIT_NETWORK_MS", 15e3),
+  gitPush: intFromEnv("LAKEBASE_KIT_TIMEOUT_GIT_PUSH_MS", 3e4),
+  cliLong: intFromEnv("LAKEBASE_KIT_TIMEOUT_CLI_LONG_MS", 6e4),
+  cmdShort: intFromEnv("LAKEBASE_KIT_TIMEOUT_CMD_SHORT_MS", 5e3),
+  initializrCacheTtl: intFromEnv("LAKEBASE_KIT_INITIALIZR_CACHE_TTL_MS", 10 * 60 * 1e3),
+  featureBranchTtlMs: intFromEnv("LAKEBASE_KIT_FEATURE_BRANCH_TTL_MS", 30 * DAY_MS),
+  testBranchTtlMs: intFromEnv("LAKEBASE_KIT_TEST_BRANCH_TTL_MS", 14 * DAY_MS),
+  uatBranchTtlMs: intFromEnv("LAKEBASE_KIT_UAT_BRANCH_TTL_MS", 14 * DAY_MS),
+  perfBranchTtlMs: intFromEnv("LAKEBASE_KIT_PERF_BRANCH_TTL_MS", 7 * DAY_MS)
+};
+function urlFromEnv(name, fallback) {
+  const raw = process.env[name];
+  if (!raw) return fallback;
+  return raw.replace(/\/+$/, "");
+}
+var KIT_REGISTRIES = {
+  mavenCentral: urlFromEnv("LAKEBASE_KIT_REGISTRY_MAVEN_CENTRAL", "https://repo1.maven.org/maven2"),
+  springInitializr: urlFromEnv("LAKEBASE_KIT_REGISTRY_SPRING_INITIALIZR", "https://start.spring.io")
+};
+
+// scripts/lakebase/databricks-profile.ts
+import * as fs from "fs";
+import { execFileSync } from "child_process";
+
+// scripts/util/exec.ts
+import * as cp from "child_process";
+
+// scripts/lakebase/databricks-profile.ts
+function normalizeHost(host) {
+  return host.trim().replace(/\/+$/, "").toLowerCase();
+}
+function selectProfileForHost(profilesJson, host) {
+  const target = normalizeHost(host);
+  if (!target) return void 0;
+  const start = profilesJson.indexOf("{");
+  if (start < 0) return void 0;
+  let parsed;
+  try {
+    parsed = JSON.parse(profilesJson.slice(start));
+  } catch {
+    return void 0;
+  }
+  const profiles = parsed.profiles;
+  if (!Array.isArray(profiles)) return void 0;
+  const names = profiles.filter((p) => {
+    if (!p || typeof p !== "object") return false;
+    const rec = p;
+    return typeof rec.name === "string" && typeof rec.host === "string" && rec.valid === true && normalizeHost(rec.host) === target;
+  }).map((p) => p.name);
+  const distinct = Array.from(new Set(names));
+  return distinct.length === 1 ? distinct[0] : void 0;
+}
+function resolveProfileForHostSync(host, timeoutMs = KIT_TIMEOUTS.cliDefault) {
+  if (!normalizeHost(host)) return void 0;
+  let out2;
+  try {
+    out2 = execFileSync("databricks", ["auth", "profiles", "-o", "json"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+      timeout: timeoutMs
+    });
+  } catch {
+    return void 0;
+  }
+  return selectProfileForHost(out2, host);
+}
+
+// scripts/lakebase/env-file.ts
+import * as fs2 from "fs";
+import * as path from "path";
+function readEnvVar(envPath, key) {
+  if (!fs2.existsSync(envPath)) return void 0;
+  let value;
+  for (const line of fs2.readFileSync(envPath, "utf-8").split("\n")) {
+    const trimmed = line.trimStart();
+    if (trimmed.startsWith("#") || !trimmed.startsWith(`${key}=`)) continue;
+    value = trimmed.slice(key.length + 1).trim().replace(/^["']|["']$/g, "");
+  }
+  return value && value.length > 0 ? value : void 0;
+}
+
+// scripts/lakebase/databricks-cli.ts
+var execFileP = promisify(execFile);
+var DatabricksCliError = class extends Error {
+  constructor(message, profile, stderr) {
+    super(message);
+    this.profile = profile;
+    this.stderr = stderr;
+    this.name = "DatabricksCliError";
+  }
+  profile;
+  stderr;
+};
+var DatabricksAuthError = class extends DatabricksCliError {
+  constructor(profile, detail) {
+    const login = `databricks auth login${profile ? ` --profile ${profile}` : ""}`;
+    super(
+      `Databricks authentication failed${profile ? ` for profile "${profile}"` : ""}: the cached token is missing or expired. Re-authenticate, then re-run:
+  ${login}
+${detail}`,
+      profile,
+      detail
+    );
+    this.name = "DatabricksAuthError";
+  }
+};
+var profileByHost = /* @__PURE__ */ new Map();
+var profileByEnvFile = /* @__PURE__ */ new Map();
+var hostByEnvFile = /* @__PURE__ */ new Map();
+function envFileHost(cwd) {
+  if (hostByEnvFile.has(cwd)) return hostByEnvFile.get(cwd);
+  const v = readEnvVar(join2(cwd, ".env"), "DATABRICKS_HOST");
+  hostByEnvFile.set(cwd, v);
+  return v;
+}
+function effectiveHost(opts) {
+  const base = opts.env ?? process.env;
+  const cwd = opts.cwd ?? process.cwd();
+  const h = opts.host ?? base.DATABRICKS_HOST ?? envFileHost(cwd);
+  return h?.trim() || void 0;
+}
+function isAuthFailure(text) {
+  return /refresh token is invalid|auth login|could not be retrieved because|not authenticated|no valid.*(credential|token)|invalid.*(access token|credential)|\b401\b|unauthorized/i.test(
+    text
+  );
+}
+function resolveProfile(opts) {
+  const base = opts.env ?? process.env;
+  if (opts.profile) return opts.profile;
+  const envProfile = base.DATABRICKS_CONFIG_PROFILE?.trim();
+  if (envProfile) return envProfile;
+  const cwd = opts.cwd ?? process.cwd();
+  let fromEnvFile;
+  if (profileByEnvFile.has(cwd)) {
+    fromEnvFile = profileByEnvFile.get(cwd);
+  } else {
+    fromEnvFile = readEnvVar(join2(cwd, ".env"), "DATABRICKS_CONFIG_PROFILE");
+    profileByEnvFile.set(cwd, fromEnvFile);
+  }
+  if (fromEnvFile) return fromEnvFile;
+  const host = effectiveHost(opts);
+  if (!host) return void 0;
+  if (profileByHost.has(host)) return profileByHost.get(host);
+  const resolved = resolveProfileForHostSync(host, opts.timeout);
+  profileByHost.set(host, resolved);
+  return resolved;
+}
+function buildInvocation(args, opts) {
+  const base = opts.env ?? process.env;
+  const trimmedHost = effectiveHost(opts)?.replace(/\/+$/, "");
+  const env = { ...base };
+  if (trimmedHost) env.DATABRICKS_HOST = trimmedHost;
+  delete env.DATABRICKS_WORKSPACE_ID;
+  const profile = resolveProfile(opts);
+  const argv = profile && !opts.noProfile && !args.includes("--profile") ? [...args, "--profile", profile] : args;
+  return { argv, env, profile };
+}
+function classifyDatabricksError(err, argv, profile) {
+  const e = err;
+  const asText = (v) => typeof v === "string" ? v : Buffer.isBuffer(v) ? v.toString("utf8") : "";
+  const stderr = asText(e.stderr).trim();
+  const stdout = asText(e.stdout).trim();
+  const haystack = `${e.message ?? ""}
+${stderr}
+${stdout}`;
+  if (isAuthFailure(haystack)) {
+    return new DatabricksAuthError(profile, stderr || stdout || (e.message ?? ""));
+  }
+  const killed = e.killed === true;
+  const signal = e.signal ?? void 0;
+  const detail = stderr ? `
+stderr: ${stderr}` : stdout ? `
+stdout: ${stdout}` : killed || signal ? `
+(no output; the CLI was killed${signal ? ` by ${signal}` : ""}, likely a TIMEOUT; raise the budget via the matching LAKEBASE_KIT_TIMEOUT_* env var)` : e.code !== void 0 ? `
+(no stderr/stdout; exit ${e.code})` : "";
+  return new DatabricksCliError(
+    `databricks ${argv.join(" ")} failed: ${e.message}${detail}`,
+    profile,
+    stderr || stdout
+  );
+}
+async function runDatabricks(args, opts = {}) {
+  const { argv, env, profile } = buildInvocation(args, opts);
+  const timeout = opts.timeout ?? KIT_TIMEOUTS.cliDefault;
+  try {
+    if (opts.input !== void 0) {
+      return await execDatabricksWithStdin(argv, opts.input, env, timeout);
+    }
+    const { stdout } = await execFileP("databricks", argv, { env, timeout });
+    return stdout.toString();
+  } catch (err) {
+    throw classifyDatabricksError(err, argv, profile);
+  }
+}
+function execDatabricksWithStdin(argv, input, env, timeout) {
+  return new Promise((resolve, reject) => {
+    const child = execFile("databricks", argv, { env, timeout }, (err, stdout, stderr) => {
+      if (err) {
+        err.stdout = String(stdout ?? "");
+        err.stderr = String(stderr ?? "");
+        reject(err);
+        return;
+      }
+      resolve(String(stdout ?? ""));
+    });
+    child.stdin?.on("error", () => {
+    });
+    child.stdin?.end(input);
+  });
+}
+
+// scripts/lakebase/branch-utils.ts
+function projectPath(instance) {
+  return `projects/${instance}`;
+}
+
+// scripts/lakebase/snapshot.ts
+function branchResource(instance, branch) {
+  return branch.includes("/") ? branch : `${projectPath(instance)}/branches/${branch}`;
+}
+function snapshotResource(instance, snapshot) {
+  return snapshot.includes("/") ? snapshot : `${projectPath(instance)}/snapshots/${snapshot}`;
+}
+function buildSnapshotSpec(args) {
+  if (args.sourceBranchTime && args.sourceBranchLsn) {
+    throw new Error("sourceBranchTime and sourceBranchLsn are mutually exclusive \u2014 pass at most one point-in-time.");
+  }
+  if (args.ttl && args.noExpiry === true) {
+    throw new Error(`Cannot set both ttl ("${args.ttl}") and noExpiry: true \u2014 they are mutually exclusive.`);
+  }
+  const spec = { source_branch: branchResource(args.instance, args.sourceBranch) };
+  if (args.sourceBranchTime) spec.source_branch_time = args.sourceBranchTime;
+  else if (args.sourceBranchLsn) spec.source_branch_lsn = args.sourceBranchLsn;
+  if (args.ttl) spec.ttl = args.ttl;
+  else if (args.noExpiry ?? true) spec.no_expiry = true;
+  return spec;
+}
+async function createSnapshot(args) {
+  const spec = buildSnapshotSpec(args);
+  return runDatabricks(
+    ["postgres", "create-snapshot", projectPath(args.instance), args.snapshot, "--json", JSON.stringify({ spec })],
+    { host: args.host, timeout: KIT_TIMEOUTS.cliCreateBranch }
+  );
+}
+async function deleteSnapshot(args) {
+  return runDatabricks(["postgres", "delete-snapshot", snapshotResource(args.instance, args.snapshot)], {
+    host: args.host
+  });
+}
+async function listSnapshots(args) {
+  return runDatabricks(["postgres", "list-snapshots", projectPath(args.instance), "-o", "json"], { host: args.host });
+}
+
+// scripts/lakebase/snapshot.cli.ts
+function parseArgs(argv) {
+  const out2 = {};
+  let i = 0;
+  if (argv[0] && !argv[0].startsWith("-")) {
+    out2.subcommand = argv[0];
+    i = 1;
+  }
+  for (; i < argv.length; i++) {
+    switch (argv[i]) {
+      case "--instance":
+        out2.instance = argv[++i];
+        break;
+      case "--snapshot":
+        out2.snapshot = argv[++i];
+        break;
+      case "--branch":
+        out2.branch = argv[++i];
+        break;
+      case "--at-time":
+        out2.atTime = argv[++i];
+        break;
+      case "--at-lsn":
+        out2.atLsn = argv[++i];
+        break;
+      case "--ttl":
+        out2.ttl = argv[++i];
+        break;
+      case "--no-expiry":
+        out2.noExpiry = true;
+        break;
+      case "--host":
+        out2.host = argv[++i];
+        break;
+      case "--pretty":
+        out2.pretty = true;
+        break;
+      case "--help":
+      case "-h":
+        out2.help = true;
+        break;
+    }
+  }
+  return out2;
+}
+var USAGE = `usage: lakebase-snapshot <create|delete|list> --instance <project> [flags]
+  create  --snapshot <id> --branch <src> [--at-time <iso> | --at-lsn <lsn>] [--ttl <s> | --no-expiry]
+  delete  --snapshot <id>
+  list
+Then branch from it: lakebase-branch create --branch <v> --from-snapshot <id> --instance <project>`;
+function out(result, pretty) {
+  process.stdout.write(JSON.stringify(result, null, pretty ? 2 : void 0) + "\n");
+}
+function need(a, keys) {
+  const missing = keys.filter((k) => a[k] === void 0 || a[k] === "");
+  if (missing.length) {
+    process.stderr.write(`missing ${missing.map((k) => "--" + String(k)).join(", ")}
+${USAGE}
+`);
+    return false;
+  }
+  return true;
+}
+async function main() {
+  const a = parseArgs(process.argv.slice(2));
+  if (a.help || !a.subcommand) {
+    process.stderr.write(USAGE + "\n");
+    return a.help ? 0 : 2;
+  }
+  switch (a.subcommand) {
+    case "create": {
+      if (!need(a, ["instance", "snapshot", "branch"])) return 2;
+      const raw = await createSnapshot({
+        instance: a.instance,
+        snapshot: a.snapshot,
+        sourceBranch: a.branch,
+        sourceBranchTime: a.atTime,
+        sourceBranchLsn: a.atLsn,
+        ttl: a.ttl,
+        noExpiry: a.noExpiry,
+        host: a.host
+      });
+      out({ created: a.snapshot, raw: raw.trim() || void 0 }, !!a.pretty);
+      return 0;
+    }
+    case "delete": {
+      if (!need(a, ["instance", "snapshot"])) return 2;
+      await deleteSnapshot({ instance: a.instance, snapshot: a.snapshot, host: a.host });
+      out({ deleted: a.snapshot }, !!a.pretty);
+      return 0;
+    }
+    case "list": {
+      if (!need(a, ["instance"])) return 2;
+      const raw = await listSnapshots({ instance: a.instance, host: a.host });
+      try {
+        out(JSON.parse(raw), !!a.pretty);
+      } catch {
+        process.stdout.write(raw);
+      }
+      return 0;
+    }
+    default:
+      process.stderr.write(`unknown subcommand '${a.subcommand}'
+${USAGE}
+`);
+      return 2;
+  }
+}
+main().then(
+  (code) => process.exit(code),
+  (err) => {
+    process.stderr.write(String(err instanceof Error ? err.message : err) + "\n");
+    process.exit(1);
+  }
+);

package/dist/scripts/util/index.cjs

@@ -1667,8 +1667,8 @@ var PKG_NAME = "@databricks-solutions/lakebase-scm-utils";
 var cached;
 function substrateSelfVersion() {
   if (cached !== void 0) return cached;
-  if ("0.3.8".length > 0) {
-    cached = "0.3.8";
+  if ("0.3.10".length > 0) {
+    cached = "0.3.10";
     return cached;
   }
   cached = "unknown";

package/dist/scripts/util/index.js

@@ -1630,8 +1630,8 @@ var PKG_NAME = "@databricks-solutions/lakebase-scm-utils";
 var cached;
 function substrateSelfVersion() {
   if (cached !== void 0) return cached;
-  if ("0.3.8".length > 0) {
-    cached = "0.3.8";
+  if ("0.3.10".length > 0) {
+    cached = "0.3.10";
     return cached;
   }
   cached = "unknown";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@databricks-solutions/lakebase-scm-utils",
-  "version": "0.3.8",
+  "version": "0.3.10",
   "description": "Lakebase SCM + substrate engine: database branching, paired-branch SCM workflows, connection/credential minting, schema migration, project scaffold + deploy primitives, and the git/github utility layer. Extracted from consort for portable, standalone consumption by lakebase-scm-extension and the SFTDD orchestration.",
   "type": "module",
   "private": false,
@@ -107,6 +107,7 @@
     "lakebase-scm-recover-orphans": "./dist/scripts/lakebase/scm-recover-orphans.cli.js",
     "lakebase-scm-state": "./dist/scripts/lakebase/scm-state.cli.js",
     "lakebase-scm-wait-ci": "./dist/scripts/lakebase/scm-wait-ci.cli.js",
+    "lakebase-snapshot": "./dist/scripts/lakebase/snapshot.cli.js",
     "lakebase-sync-ci-secrets": "./dist/scripts/lakebase/sync-ci-secrets.cli.js"
   },
   "scripts": {

package/scripts/lakebase/branch-create.ts

@@ -87,6 +87,57 @@ export interface CreateBranchArgs extends BranchLookupOpts {
    * caller's expectation. Default: false (fallback enabled).
    */
   strictParent?: boolean;
+  /**
+   * Branch from an immutable SNAPSHOT instead of a source branch (the kit's
+   * fast verify-branch provisioning: snapshot the committed schema once, then
+   * branch copy-on-write from it per cycle — no `alembic upgrade head` rebuild,
+   * and a FIXED point so the fork never goes stale). Accepts a bare snapshot id
+   * or a full `projects/<p>/snapshots/<id>` path. Maps to `spec.source_snapshot`,
+   * which the Lakebase API treats as mutually exclusive with source_branch /
+   * source_branch_time / source_branch_lsn — so when set, the parentBranch
+   * resolution below is skipped entirely.
+   */
+  fromSnapshot?: string;
+  /**
+   * Point-in-time for a branch-from-branch create: an ISO-8601 timestamp.
+   * Maps to `spec.source_branch_time` — branch the source branch AS OF this
+   * time (PITR). Mutually exclusive with sourceBranchLsn and with fromSnapshot.
+   */
+  sourceBranchTime?: string;
+  /**
+   * Point-in-time for a branch-from-branch create: an LSN (e.g. "0/16B3748").
+   * Maps to `spec.source_branch_lsn`. Mutually exclusive with sourceBranchTime
+   * and with fromSnapshot.
+   */
+  sourceBranchLsn?: string;
+}
+
+/** The create-branch request `spec` — one source group (source_branch [+time|+lsn]
+ *  OR source_snapshot) plus exactly one expiration (no_expiry | ttl). */
+interface BranchSpec {
+  source_branch?: string;
+  source_snapshot?: string;
+  source_branch_time?: string;
+  source_branch_lsn?: string;
+  no_expiry?: boolean;
+  ttl?: string;
+}
+
+/** Resolve a snapshot arg (bare id or full path) to the full snapshot resource path. */
+function snapshotPath(instance: string, snapshot: string): string {
+  return snapshot.includes("/") ? snapshot : `${projectPath(instance)}/snapshots/${snapshot}`;
+}
+
+/** Apply the expiration policy (ttl wins; else default no_expiry: true) onto a spec,
+ *  refusing the inconsistent ttl + noExpiry:true combination. */
+function applyExpiration(spec: BranchSpec, ttl: string | undefined, noExpiry: boolean | undefined): void {
+  if (ttl && noExpiry === true) {
+    throw new LakebaseBranchError(
+      `Cannot set both ttl ("${ttl}") and noExpiry: true on the same branch – they are mutually exclusive. Pass one or the other.`,
+    );
+  }
+  if (ttl) spec.ttl = ttl;
+  else if (noExpiry ?? true) spec.no_expiry = true;
 }
 
 /**
@@ -104,6 +155,38 @@ export async function createBranch(args: CreateBranchArgs): Promise<LakebaseBran
   const sanitized = sanitizeBranchName(args.branch);
   const lookup: BranchLookupOpts = { instance: args.instance, host: args.host };
 
+  // SNAPSHOT SOURCE (fast verify-branch provisioning): branch copy-on-write from an
+  // immutable snapshot. source_snapshot is mutually exclusive with the source_branch
+  // family, so this path skips parentBranch resolution entirely. Idempotent: a branch
+  // that already exists under this name is returned as-is (the ephemeral verify branches
+  // this serves are single-use; we don't re-assert the snapshot lineage of a survivor).
+  if (args.fromSnapshot) {
+    if (args.parentBranch || args.sourceBranchTime || args.sourceBranchLsn) {
+      throw new LakebaseBranchError(
+        `fromSnapshot is mutually exclusive with parentBranch / sourceBranchTime / sourceBranchLsn ` +
+          `(the Lakebase API rejects source_snapshot combined with any source_branch field).`,
+      );
+    }
+    const existing = await getBranchByName(sanitized, lookup);
+    if (existing) return existing;
+    const spec: BranchSpec = { source_snapshot: snapshotPath(args.instance, args.fromSnapshot) };
+    applyExpiration(spec, args.ttl, args.noExpiry);
+    try {
+      await createWithTtlRecovery(args.instance, sanitized, spec, args.host);
+    } catch (err) {
+      if (err instanceof LakebaseBranchTtlTooLongError) throw err;
+      const landed = await getBranchByName(sanitized, lookup);
+      if (!landed) throw err;
+    }
+    return waitForBranchReady({
+      instance: args.instance,
+      host: args.host,
+      branch: sanitized,
+      timeoutMs: args.readyTimeoutMs ?? KIT_TIMEOUTS.readyWait,
+      pollIntervalMs: args.pollIntervalMs ?? KIT_TIMEOUTS.readyPoll,
+    });
+  }
+
   // Resolve the source (parent) branch full path first – needed both for
   // create AND for the idempotency-vs-conflict comparison below.
   let sourceBranchPath: string | undefined;
@@ -182,22 +265,18 @@ export async function createBranch(args: CreateBranchArgs): Promise<LakebaseBran
     return existing;
   }
 
-  // Expiration policy: ttl wins if set; otherwise default to no_expiry: true.
-  // Refuse the inconsistent combination (ttl + noExpiry: true both set).
-  if (args.ttl && args.noExpiry === true) {
+  if (args.sourceBranchTime && args.sourceBranchLsn) {
     throw new LakebaseBranchError(
-      `Cannot set both ttl ("${args.ttl}") and noExpiry: true on the same ` +
-        `branch – they are mutually exclusive. Pass one or the other.`,
+      `sourceBranchTime and sourceBranchLsn are mutually exclusive – pass at most one point-in-time.`,
     );
   }
-  const specObj: { source_branch: string; no_expiry?: boolean; ttl?: string } = {
-    source_branch: sourceBranchPath,
-  };
-  if (args.ttl) {
-    specObj.ttl = args.ttl;
-  } else if (args.noExpiry ?? true) {
-    specObj.no_expiry = true;
-  }
+  const specObj: BranchSpec = { source_branch: sourceBranchPath };
+  // PITR: pin the source branch at a timestamp or LSN (source_branch_time /
+  // source_branch_lsn) — e.g. branch the higher env AS OF the committed-schema point.
+  if (args.sourceBranchTime) specObj.source_branch_time = args.sourceBranchTime;
+  else if (args.sourceBranchLsn) specObj.source_branch_lsn = args.sourceBranchLsn;
+  // Expiration policy: ttl wins if set; otherwise default to no_expiry: true.
+  applyExpiration(specObj, args.ttl, args.noExpiry);
   try {
     await createWithTtlRecovery(args.instance, sanitized, specObj, args.host);
   } catch (err) {
@@ -299,7 +378,7 @@ function assertSourceMatches(
 async function createWithTtlRecovery(
   instance: string,
   sanitized: string,
-  specObj: { source_branch: string; no_expiry?: boolean; ttl?: string },
+  specObj: BranchSpec,
   host: string | undefined,
 ): Promise<void> {
   const originalTtl = specObj.ttl;

package/scripts/lakebase/branch.cli.ts

@@ -39,6 +39,9 @@ interface ParsedArgs {
   instance?: string;
   branch?: string;
   parentBranch?: string;
+  fromSnapshot?: string;
+  atTime?: string;
+  atLsn?: string;
   ttl?: string;
   noExpiry?: boolean;
   cwd?: string;
@@ -85,6 +88,15 @@ function parseArgs(argv: string[]): ParsedArgs {
       case "--parent-branch":
         out.parentBranch = argv[++i];
         break;
+      case "--from-snapshot":
+        out.fromSnapshot = argv[++i];
+        break;
+      case "--at-time":
+        out.atTime = argv[++i];
+        break;
+      case "--at-lsn":
+        out.atLsn = argv[++i];
+        break;
       case "--ttl":
         out.ttl = argv[++i];
         break;
@@ -259,6 +271,9 @@ async function main(): Promise<number> {
           host: args.host,
           branch: args.branch!,
           parentBranch: args.parentBranch,
+          fromSnapshot: args.fromSnapshot,
+          sourceBranchTime: args.atTime,
+          sourceBranchLsn: args.atLsn,
           ttl: args.ttl,
           noExpiry: args.noExpiry,
         });

package/scripts/lakebase/get-connection.ts

@@ -136,7 +136,6 @@ export async function getConnection(args: ConnectionArgs): Promise<DsnResult | P
 
   // output === "pool"
   const host = await resolveEndpointHost(args.instance, branchId);
-  const email = await resolveCurrentUser();
   // Label the POOLED path too , it is the PRIMARY one (schema-diff, reconcile-tier). Passing
   // application_name in createLakebasePool's config does NOT work: it builds its own pg
   // PoolConfig and drops the field (verified live , the pooled connection came back with an
@@ -145,17 +144,35 @@ export async function getConnection(args: ConnectionArgs): Promise<DsnResult | P
   // call time (not import) so CONSORT_VERSION , which Consort exports at its entry point , is
   // already in the env when connectionApplicationName() reads it.
   process.env.PGAPPNAME = connectionApplicationName();
-  return createLakebasePool({
-    endpoint: endpointPath,
-    host,
-    database,
-    user: email,
-    // workspaceClient is passed through verbatim. createLakebasePool falls
-    // back to environment / ServiceContext when omitted.
-    ...(args.workspaceClient !== undefined
-      ? { workspaceClient: args.workspaceClient as never }
-      : {}),
-  });
+
+  // AppKit OBO: an explicit workspaceClient is a pre-authenticated caller , keep the
+  // OAuth/token-rotation path with it verbatim.
+  if (args.workspaceClient !== undefined) {
+    const email = await resolveCurrentUser();
+    return createLakebasePool({
+      endpoint: endpointPath,
+      host,
+      database,
+      user: email,
+      workspaceClient: args.workspaceClient as never,
+    });
+  }
+
+  // CLI/kit path (no workspaceClient): DO NOT let createLakebasePool self-authenticate
+  // via the SDK default chain. That runs `databricks auth token --host <workspace-host>`
+  // WITHOUT a profile, so when several ~/.databrickscfg profiles match that host (e.g.
+  // DEFAULT + an adb-* + logfood all pointing at the same workspace) the CLI refuses
+  // ("Use --profile to specify which profile to use") and the pool connection fails
+  // ("default auth: databricks-cli: cannot get access token"). That silently broke
+  // schema-diff at deploy-verify (the diff came back empty, failing the schema-diff
+  // test) whenever the host was ambiguous. Instead MINT the credential through the
+  // kit's profile-threaded CLI wrapper (mintCredential -> runDatabricksSync -> the
+  // resolved `--profile`, the same unambiguous path the DSN output uses) and pass it as
+  // `password`: LakebasePoolConfig skips OAuth entirely when a password is supplied. The
+  // kit's pool consumers (schema-diff, reconcile-tier) are short batch reads, well inside
+  // the credential TTL, so forgoing token rotation here is safe.
+  const { token, email } = await mintCredential(endpointPath);
+  return createLakebasePool({ host, database, user: email, password: token });
 }
 
 /**