@supacloud/lite 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## [0.3.0](https://github.com/zuohuadong/supacloud/compare/supacloud-lite-v0.2.0...supacloud-lite-v0.3.0) (2026-07-28)
+
+
+### Features
+
+* extend Supabase-compatible platform capabilities ([adef019](https://github.com/zuohuadong/supacloud/commit/adef019261f82f123043ab4c7a047e6ad6956e56))
+* harden Supabase Cloud compatibility ([ab64374](https://github.com/zuohuadong/supacloud/commit/ab643743b058ad08a0d32c124d26bed0863db397))
+
+
+### Bug Fixes
+
+* use installed TypeScript in Lite smoke ([8a64050](https://github.com/zuohuadong/supacloud/commit/8a64050833c47778e931067f8f30e541141256bf))
+
+
+### Documentation
+
+* **lite:** document snapshot archive dependency ([1c0a8cc](https://github.com/zuohuadong/supacloud/commit/1c0a8cccc4e6cbb0804c7badf6573d6d986c2528))
+
 ## [0.2.0](https://github.com/zuohuadong/supacloud/compare/supacloud-lite-v0.1.0...supacloud-lite-v0.2.0) (2026-07-28)
 
 

package/README.md

@@ -59,6 +59,19 @@ supabase/
 
 `config.toml` 当前支持 Auth、API schema/max rows、Storage bucket/size limit、seed 和 function entrypoint 等常用配置。
 
+### Auth 运行方式
+
+Lite 不下载、安装或启动独立的 GoTrue 进程。`/auth/v1/*` 由同一个 Bun 进程中的内置 Auth 实现处理，并与该 Lite 项目的 PGlite `auth` schema 共享生命周期；这避免了 sidecar 的配置、端口和会话一致性负担。
+
+Auth 默认启用。如项目不需要客户端登录接口，可在 `supabase/config.toml` 中关闭该路由：
+
+```toml
+[auth]
+enabled = false
+```
+
+关闭后 `/auth/v1/*` 返回 `404`，但不会把 Lite 变成完整 GoTrue 运行时，也不会自动移除已有的 `auth` schema 或 API key。需要完整 GoTrue 行为、多项目鉴权或独立鉴权进程时，应使用完整 SupaCloud 平台。
+
 ## CLI
 
 ```text
@@ -70,6 +83,9 @@ supacloud-lite gen types [-o database.types.ts]
 supacloud-lite db reset
 supacloud-lite db diff [-f migration_name]
 supacloud-lite db pull [migration_name]
+supacloud-lite snapshot create [-o backup.tar.gz]
+supacloud-lite snapshot restore <backup.tar.gz> [--force]
+supacloud-lite upgrade [-o pre-upgrade.tar.gz]
 supacloud-lite inspect
 supacloud-lite version
 ```
@@ -107,12 +123,65 @@ S3 模式下 `db reset` 会被拒绝，因为 Lite 不能把数据库元数据
 
 网络暴露时必须提供足够强的 JWT secret 和独立 vault key。默认生成的密钥适合单机项目；不要把 `.supacloud-lite/secrets.json` 提交到版本库。
 
+## 升级、快照与恢复
+
+生产或持久化环境升级时，先更新项目锁定的 npm 依赖，再运行 Lite 的受控升级命令：
+
+```bash
+# 明确指定目标版本；不要在生产启动命令中隐式使用 @latest
+bun add @supacloud/lite@0.2.0
+
+# 自动创建升级前快照，然后执行尚未应用的 supabase/migrations
+bunx supacloud-lite upgrade
+```
+
+`upgrade` 不会自行修改 `package.json` 或联网更新 npm 包。它使用当前项目已经安装并锁定的 Lite 版本，默认把升级前快照写入 `.supacloud-lite/backups/pre-upgrade-<timestamp>.tar.gz`，快照成功后才执行 migrations。升级失败时，快照会保留，并打印恢复命令。
+
+也可以单独创建可移植快照：
+
+```bash
+# 使用默认文件名和目录
+bunx supacloud-lite snapshot create
+
+# 指定输出位置
+bunx supacloud-lite snapshot create -o ./backups/project-a.tar.gz
+```
+
+快照是一个 gzip 压缩的 tar 文件，包含：
+
+- PGlite 数据目录；
+- `fs` 模式的对象文件；
+- `secrets.json`，用于保持 JWT、会话和 Vault 解密兼容；
+- 快照格式、Lite 版本和 Storage backend 清单。
+
+快照包含敏感密钥，输出文件在 Unix 系统上会设置为 `0600`；仍应按数据库备份级别加密、限制访问并设置保留周期。创建快照前必须停止 Lite。若检测到数据目录锁，命令会拒绝继续；只有确认进程已退出后才能人工删除陈旧锁。
+
+恢复到新项目或空状态目录：
+
+```bash
+bunx supacloud-lite snapshot restore ./backups/project-a.tar.gz
+```
+
+目标状态目录非空时默认拒绝覆盖。确认要替换现有状态时显式使用：
+
+```bash
+bunx supacloud-lite snapshot restore ./backups/project-a.tar.gz --force
+```
+
+`--force` 不会直接删除旧数据，而是把旧状态目录重命名为 `.supacloud-lite.restore-<id>` 形式的回滚副本，并在输出中打印完整路径。验证新状态后再由运维人员清理该目录。
+
+使用自定义 `--state-dir`、`--data-dir` 或 `--storage-dir` 时，创建和恢复必须传入相同参数。数据库与 Storage 目录不得重叠，也不能指向文件系统根目录或符号链接。
+
+S3 模式的快照只包含数据库中的 Storage 元数据和密钥，不复制远端对象，也不会读取或保存 S3 凭据。恢复时必须传入 `--storage-backend s3`，并重新提供原 bucket/prefix 的环境变量；跨 bucket 迁移仍需使用对象存储自身的复制工具。
+
+内存数据库没有可持久化的数据，因此 `snapshot` 和 `upgrade` 会拒绝 `--memory`。
+
 ## 兼容范围
 
 | 能力 | V1 状态 | 说明 |
 | --- | --- | --- |
 | `supabase.from()` | 已验证核心 | 自动测试覆盖 CRUD、过滤、RLS；嵌套关系、RPC 和高级 PostgREST 语法属于实验性兼容 |
-| `supabase.auth` | 已验证核心 | 自动测试覆盖邮箱密码、会话和 bcrypt；OTP/Magic Link、匿名用户、OAuth、MFA 属于实验性兼容 |
+| `supabase.auth` | 已验证核心 | 由内置 Auth 实现而非独立 GoTrue 进程提供；自动测试覆盖邮箱密码、会话和 bcrypt；OTP/Magic Link、匿名用户、OAuth、MFA 属于实验性兼容 |
 | `supabase.storage` | 已验证核心 | 覆盖上传下载、列表、删除、TUS/RLS、远端 S3 驱动，以及 Bun.Image 的 `contain`/`fill`、格式和质量变换子集；`cover` 明确不支持 |
 | `supabase.channel()` | 已验证核心 | 自动测试覆盖 `postgres_changes`、DELETE RLS 隔离和事件快照校验；Broadcast、Presence 属于实验性兼容 |
 | `supabase.functions.invoke()` | 已验证核心 | 自动测试覆盖 Bun.build、`Deno.serve()`、公开函数和同进程重启 |

package/THIRD_PARTY_NOTICES.md

@@ -22,3 +22,11 @@ SupaCloud Lite 使用 ElectricSQL PGlite 作为嵌入式 PostgreSQL 引擎。
 ## Supabase JavaScript SDK
 
 `@supabase/supabase-js` 仅作为开发和兼容性测试依赖使用，没有 vendored 到发布产物中。
+
+## node-tar
+
+SupaCloud Lite 使用 `tar` 作为跨平台流式快照归档依赖，避免把完整 PGlite 数据目录加载到内存。
+
+- License: ISC
+- Upstream: `https://github.com/isaacs/node-tar`
+- Distribution: 作为独立 npm 依赖安装，许可证随依赖包分发

package/dist/cli.js

@@ -3,12 +3,12 @@
 var __require = import.meta.require;
 
 // src/cli.ts
-import { mkdir as mkdir6, rm as rm3, writeFile as writeFile5 } from "fs/promises";
-import { dirname as dirname4, join as join8, resolve as resolve3 } from "path";
+import { mkdir as mkdir7, rm as rm4, writeFile as writeFile6 } from "fs/promises";
+import { dirname as dirname5, join as join9, resolve as resolve4 } from "path";
 // package.json
 var package_default = {
   name: "@supacloud/lite",
-  version: "0.2.0",
+  version: "0.3.0",
   description: "Bun-native, single-project Supabase-compatible backend powered by PGlite",
   type: "module",
   license: "Apache-2.0",
@@ -32,7 +32,7 @@ var package_default = {
   ],
   scripts: {
     build: "bun run build:js && bun run build:types",
-    "build:js": "bun build src/index.ts --target=bun --format=esm --outdir=dist --external @electric-sql/pglite && bun build src/cli.ts --target=bun --format=esm --outdir=dist --external @electric-sql/pglite",
+    "build:js": "bun build src/index.ts --target=bun --format=esm --outdir=dist --external @electric-sql/pglite --external tar && bun build src/cli.ts --target=bun --format=esm --outdir=dist --external @electric-sql/pglite --external tar",
     "build:types": "bun x tsc --emitDeclarationOnly -p tsconfig.build.json",
     check: "bun run typecheck && bun run test && bun run build && bun run test:package",
     dev: "bun run src/cli.ts start",
@@ -43,10 +43,11 @@ var package_default = {
     typecheck: "bun x tsc --noEmit -p tsconfig.json"
   },
   dependencies: {
-    "@electric-sql/pglite": "0.5.4"
+    "@electric-sql/pglite": "0.5.4",
+    tar: "^7.5.22"
   },
   devDependencies: {
-    "@supabase/supabase-js": "^2.57.4",
+    "@supabase/supabase-js": "^2.110.9",
     "@types/bun": "^1.3.14",
     typescript: "^5.9.3"
   },
@@ -8736,6 +8737,392 @@ async function findEphemeralPort(host = "127.0.0.1") {
   return port;
 }
 
+// src/snapshot.ts
+import { chmod as chmod2, copyFile, link as link2, lstat as lstat2, mkdir as mkdir6, mkdtemp, readdir as readdir3, readFile as readFile7, rename as rename2, rm as rm3, writeFile as writeFile5 } from "fs/promises";
+import { dirname as dirname4, join as join8, parse as parse2, relative as relative2, resolve as resolve3, sep as sep2 } from "path";
+import { create as createTar, extract as extractTar } from "tar";
+var SNAPSHOT_FORMAT = "supacloud-lite-snapshot";
+var SNAPSHOT_VERSION = 1;
+async function createSnapshot(options) {
+  const paths = normalizePaths(options.paths);
+  await assertSnapshotPaths(paths);
+  await assertNoDataDirectoryLock(paths);
+  const manifest = {
+    format: SNAPSHOT_FORMAT,
+    version: SNAPSHOT_VERSION,
+    createdAt: new Date().toISOString(),
+    packageVersion: options.packageVersion,
+    storageBackend: options.storageBackend,
+    includesDatabase: Boolean(paths.dataDir),
+    includesLocalStorage: options.storageBackend === "fs",
+    includesSecrets: true
+  };
+  const output = resolve3(options.output);
+  if (await existingInfo(output))
+    throw new Error(`snapshot output already exists: ${output}`);
+  await mkdir6(dirname4(output), { recursive: true });
+  const stagingRoot = await mkdtemp(join8(dirname4(output), ".supacloud-lite-snapshot-"));
+  try {
+    await writeFile5(join8(stagingRoot, "manifest.json"), `${JSON.stringify(manifest, null, 2)}
+`);
+    await stageFile(paths.secretsFile, join8(stagingRoot, "secrets.json"));
+    if (paths.dataDir)
+      await stageDirectory(paths.dataDir, join8(stagingRoot, "database"));
+    if (options.storageBackend === "fs")
+      await stageDirectory(paths.storageDir, join8(stagingRoot, "storage"));
+    const entries = ["manifest.json", "secrets.json"];
+    if (paths.dataDir)
+      entries.push("database");
+    if (options.storageBackend === "fs")
+      entries.push("storage");
+    await createTar({ cwd: stagingRoot, file: output, gzip: true, portable: true }, entries);
+    if (process.platform !== "win32")
+      await chmod2(output, 384);
+    return manifest;
+  } catch (error) {
+    await rm3(output, { force: true });
+    throw error;
+  } finally {
+    await rm3(stagingRoot, { recursive: true, force: true });
+  }
+}
+async function restoreSnapshot(options) {
+  const paths = normalizePaths(options.paths);
+  await assertSnapshotPaths(paths, { requireSecrets: false, allowMissingState: true });
+  await assertNoDataDirectoryLock(paths);
+  const stagingRoot = await mkdtemp(join8(dirname4(paths.stateDir), ".supacloud-lite-restore-"));
+  const payloadRoot = join8(stagingRoot, "payload");
+  const rollbackId = crypto.randomUUID();
+  const rollbackPaths = [];
+  try {
+    await mkdir6(payloadRoot, { recursive: true });
+    await extractTar({
+      cwd: payloadRoot,
+      file: resolve3(options.input),
+      preserveOwner: false,
+      preservePaths: false,
+      strict: true,
+      unlink: true,
+      filter: (path, entry) => {
+        const normalized = path.replaceAll("\\", "/");
+        const allowedPath = normalized === "manifest.json" || normalized === "secrets.json" || normalized === "database" || normalized.startsWith("database/") || normalized === "storage" || normalized.startsWith("storage/");
+        if (!allowedPath || normalized.startsWith("/") || normalized.split("/").includes("..")) {
+          throw new Error(`snapshot contains an unsafe path: ${path}`);
+        }
+        const entryType = "type" in entry ? entry.type : undefined;
+        if (entryType !== "File" && entryType !== "Directory") {
+          throw new Error(`snapshot contains an unsupported entry type: ${entryType ?? "unknown"}`);
+        }
+        return true;
+      }
+    });
+    await assertNoSymlinks(payloadRoot);
+    const manifest = await readManifest(payloadRoot);
+    if (manifest.storageBackend !== options.storageBackend) {
+      throw new Error(`snapshot storage backend is ${manifest.storageBackend}, but the target uses ${options.storageBackend}; ` + "restore with the matching --storage-backend value");
+    }
+    if (manifest.includesDatabase !== Boolean(paths.dataDir)) {
+      throw new Error("snapshot database mode does not match the target; do not restore a persistent snapshot into --memory");
+    }
+    if (manifest.includesLocalStorage !== (options.storageBackend === "fs")) {
+      throw new Error("snapshot storage payload does not match the target storage backend");
+    }
+    await assertSnapshotPayload(payloadRoot, manifest);
+    if (manifest.includesDatabase)
+      await mkdir6(join8(payloadRoot, "database"), { recursive: true });
+    if (manifest.includesLocalStorage)
+      await mkdir6(join8(payloadRoot, "storage"), { recursive: true });
+    await assertRestoreTargets(paths, manifest, options.force === true);
+    const stateStage = join8(stagingRoot, "state");
+    await mkdir6(stateStage, { recursive: true });
+    await copyEntry(join8(payloadRoot, "secrets.json"), join8(stateStage, "secrets.json"));
+    if (paths.dataDir && isWithin(paths.stateDir, paths.dataDir)) {
+      await copyEntry(join8(payloadRoot, "database"), join8(stateStage, relative2(paths.stateDir, paths.dataDir)));
+    }
+    if (options.storageBackend === "fs" && isWithin(paths.stateDir, paths.storageDir)) {
+      await copyEntry(join8(payloadRoot, "storage"), join8(stateStage, relative2(paths.stateDir, paths.storageDir)));
+    }
+    const swaps = [];
+    try {
+      await applyDirectorySwap(stateStage, paths.stateDir, options.force === true, rollbackId, swaps);
+      if (paths.dataDir && !isWithin(paths.stateDir, paths.dataDir)) {
+        await applyDirectorySwap(join8(payloadRoot, "database"), paths.dataDir, options.force === true, rollbackId, swaps);
+      }
+      if (options.storageBackend === "fs" && !isWithin(paths.stateDir, paths.storageDir)) {
+        await applyDirectorySwap(join8(payloadRoot, "storage"), paths.storageDir, options.force === true, rollbackId, swaps);
+      }
+    } catch (error) {
+      await rollbackDirectorySwaps(swaps);
+      throw error;
+    }
+    rollbackPaths.push(...swaps.flatMap((swap) => swap.rollbackPath ? [swap.rollbackPath] : []));
+    if (process.platform !== "win32") {
+      await hardenRestoredTree(paths.stateDir);
+      if (paths.dataDir && !isWithin(paths.stateDir, paths.dataDir))
+        await hardenRestoredTree(paths.dataDir);
+      if (options.storageBackend === "fs" && !isWithin(paths.stateDir, paths.storageDir)) {
+        await hardenRestoredTree(paths.storageDir);
+      }
+    }
+    return { manifest, rollbackPaths };
+  } catch (error) {
+    throw error instanceof Error ? error : new Error(String(error));
+  } finally {
+    await rm3(stagingRoot, { recursive: true, force: true });
+  }
+}
+function normalizePaths(paths) {
+  return {
+    ...paths,
+    projectDir: resolve3(paths.projectDir),
+    stateDir: resolve3(paths.stateDir),
+    dataDir: paths.dataDir ? resolve3(paths.dataDir) : undefined,
+    storageDir: resolve3(paths.storageDir),
+    secretsFile: resolve3(paths.secretsFile)
+  };
+}
+async function assertSnapshotPaths(paths, options = {}) {
+  try {
+    if (paths.stateDir === parse2(paths.stateDir).root)
+      throw new Error("snapshot state directory must not be the filesystem root");
+    if (paths.secretsFile !== join8(paths.stateDir, "secrets.json"))
+      throw new Error("snapshot secrets path must be inside the state directory");
+    const stateInfo = await lstat2(paths.stateDir);
+    if (!stateInfo.isDirectory() || stateInfo.isSymbolicLink())
+      throw new Error(`state directory must be a real directory: ${paths.stateDir}`);
+  } catch (error) {
+    if (error.code !== "ENOENT" || options.allowMissingState !== true)
+      throw error;
+  }
+  if (paths.dataDir && paths.storageDir && pathsOverlap(paths.dataDir, paths.storageDir)) {
+    throw new Error("database and storage directories must not overlap");
+  }
+  await assertDirectoryOrMissing(paths.dataDir);
+  await assertDirectoryOrMissing(paths.storageDir);
+  if (options.requireSecrets !== false) {
+    const secretInfo = await lstat2(paths.secretsFile);
+    if (!secretInfo.isFile() || secretInfo.isSymbolicLink())
+      throw new Error(`secrets file must be a regular file: ${paths.secretsFile}`);
+  }
+}
+async function assertDirectoryOrMissing(path) {
+  if (!path)
+    return;
+  if (resolve3(path) === parse2(resolve3(path)).root)
+    throw new Error(`snapshot path must not be the filesystem root: ${path}`);
+  try {
+    const info = await lstat2(path);
+    if (!info.isDirectory() || info.isSymbolicLink())
+      throw new Error(`snapshot path must be a real directory: ${path}`);
+  } catch (error) {
+    if (error.code !== "ENOENT")
+      throw error;
+  }
+}
+async function assertNoDataDirectoryLock(paths) {
+  if (!paths.dataDir)
+    return;
+  const lockPath = `${paths.dataDir}.supacloud-lite.lock`;
+  try {
+    await lstat2(lockPath);
+    throw new Error(`data directory is in use or has a stale lock: ${lockPath}; stop Lite and remove the lock manually if it is stale`);
+  } catch (error) {
+    if (error.code !== "ENOENT")
+      throw error;
+  }
+}
+async function stageDirectory(root, destination) {
+  try {
+    const info = await lstat2(root);
+    if (!info.isDirectory() || info.isSymbolicLink())
+      throw new Error(`snapshot path must be a real directory: ${root}`);
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      await mkdir6(destination, { recursive: true });
+      return;
+    }
+    throw error;
+  }
+  await mkdir6(destination, { recursive: true });
+  const walk = async (current, target) => {
+    for (const entry of await readdir3(current, { withFileTypes: true })) {
+      const fullPath = join8(current, entry.name);
+      const targetPath = join8(target, entry.name);
+      if (entry.isSymbolicLink())
+        throw new Error(`snapshot refuses symbolic link: ${fullPath}`);
+      if (entry.isDirectory()) {
+        await mkdir6(targetPath, { recursive: true });
+        await walk(fullPath, targetPath);
+      } else if (entry.isFile()) {
+        await stageFile(fullPath, targetPath);
+      } else {
+        throw new Error(`snapshot refuses unsupported filesystem entry: ${fullPath}`);
+      }
+    }
+  };
+  await walk(root, destination);
+}
+async function stageFile(source, target) {
+  await mkdir6(dirname4(target), { recursive: true });
+  try {
+    await link2(source, target);
+  } catch (error) {
+    const code = error.code;
+    if (code !== "EXDEV" && code !== "EPERM" && code !== "EACCES")
+      throw error;
+    await copyFile(source, target);
+  }
+}
+async function readManifest(payloadRoot) {
+  let parsed;
+  try {
+    parsed = JSON.parse(await readFile7(join8(payloadRoot, "manifest.json"), "utf8"));
+  } catch (error) {
+    throw new Error(`invalid snapshot manifest: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  if (!isSnapshotManifest(parsed))
+    throw new Error("unsupported or invalid SupaCloud Lite snapshot manifest");
+  return parsed;
+}
+function isSnapshotManifest(value) {
+  if (!value || typeof value !== "object")
+    return false;
+  const candidate = value;
+  return candidate.format === SNAPSHOT_FORMAT && candidate.version === SNAPSHOT_VERSION && typeof candidate.createdAt === "string" && typeof candidate.packageVersion === "string" && (candidate.storageBackend === "fs" || candidate.storageBackend === "s3" || candidate.storageBackend === "memory") && typeof candidate.includesDatabase === "boolean" && typeof candidate.includesLocalStorage === "boolean" && candidate.includesSecrets === true;
+}
+async function assertSnapshotPayload(payloadRoot, manifest) {
+  const required = ["manifest.json", "secrets.json"];
+  for (const path of required) {
+    try {
+      await lstat2(join8(payloadRoot, path));
+    } catch {
+      throw new Error(`snapshot is missing required payload: ${path}`);
+    }
+  }
+  const allowed = [...required];
+  if (manifest.includesDatabase)
+    allowed.push("database");
+  if (manifest.includesLocalStorage)
+    allowed.push("storage");
+  for (const entry of await readdir3(payloadRoot)) {
+    if (!allowed.includes(entry)) {
+      throw new Error(`snapshot contains an unexpected payload entry: ${entry}`);
+    }
+  }
+}
+async function assertRestoreTargets(paths, manifest, force) {
+  const targets = [paths.stateDir];
+  if (paths.dataDir && !isWithin(paths.stateDir, paths.dataDir))
+    targets.push(paths.dataDir);
+  if (manifest.includesLocalStorage && !isWithin(paths.stateDir, paths.storageDir))
+    targets.push(paths.storageDir);
+  if (!force) {
+    for (const target of targets) {
+      if (await directoryHasEntries(target))
+        throw new Error(`restore target is not empty: ${target}; pass --force to replace it`);
+    }
+  }
+}
+async function directoryHasEntries(path) {
+  try {
+    return (await readdir3(path)).length > 0;
+  } catch (error) {
+    if (error.code === "ENOENT")
+      return false;
+    throw error;
+  }
+}
+async function applyDirectorySwap(source, target, force, rollbackId, swaps) {
+  const targetInfo = await existingInfo(target);
+  if (targetInfo && !targetInfo.isDirectory())
+    throw new Error(`restore target is not a directory: ${target}`);
+  const swap = { target };
+  if (targetInfo) {
+    if (!force) {
+      if (await directoryHasEntries(target))
+        throw new Error(`restore target is not empty: ${target}; pass --force to replace it`);
+      await rm3(target, { recursive: true, force: true });
+    } else {
+      swap.rollbackPath = join8(dirname4(target), `.${target.split(sep2).pop() ?? "state"}.restore-${rollbackId}`);
+      await rename2(target, swap.rollbackPath);
+    }
+  }
+  try {
+    await mkdir6(dirname4(target), { recursive: true });
+    await rename2(source, target);
+    swaps.push(swap);
+  } catch (error) {
+    if (swap.rollbackPath)
+      await rename2(swap.rollbackPath, target).catch(() => {});
+    throw error;
+  }
+}
+async function rollbackDirectorySwaps(swaps) {
+  for (const swap of [...swaps].reverse()) {
+    await rm3(swap.target, { recursive: true, force: true });
+    if (swap.rollbackPath)
+      await rename2(swap.rollbackPath, swap.target);
+  }
+}
+async function existingInfo(path) {
+  try {
+    return await lstat2(path);
+  } catch (error) {
+    if (error.code === "ENOENT")
+      return null;
+    throw error;
+  }
+}
+async function copyEntry(source, target) {
+  const info = await lstat2(source);
+  if (info.isSymbolicLink())
+    throw new Error(`snapshot refuses symbolic link: ${source}`);
+  if (info.isDirectory()) {
+    await mkdir6(target, { recursive: true });
+    for (const entry of await readdir3(source))
+      await copyEntry(join8(source, entry), join8(target, entry));
+  } else if (info.isFile()) {
+    await mkdir6(dirname4(target), { recursive: true });
+    await Bun.write(target, Bun.file(source));
+  } else
+    throw new Error(`snapshot refuses unsupported filesystem entry: ${source}`);
+}
+async function hardenRestoredTree(root) {
+  const info = await lstat2(root);
+  if (info.isSymbolicLink())
+    throw new Error(`snapshot refuses symbolic link: ${root}`);
+  if (info.isDirectory()) {
+    await chmod2(root, 448);
+    for (const entry of await readdir3(root))
+      await hardenRestoredTree(join8(root, entry));
+    return;
+  }
+  if (info.isFile()) {
+    await chmod2(root, 384);
+    return;
+  }
+  throw new Error(`snapshot refuses unsupported filesystem entry: ${root}`);
+}
+async function assertNoSymlinks(root) {
+  for (const entry of await readdir3(root, { withFileTypes: true })) {
+    const fullPath = join8(root, entry.name);
+    if (entry.isSymbolicLink())
+      throw new Error(`snapshot refuses symbolic link in archive: ${fullPath}`);
+    if (entry.isDirectory())
+      await assertNoSymlinks(fullPath);
+  }
+}
+function isWithin(parent, child) {
+  const normalizedParent = resolve3(parent);
+  const normalizedChild = resolve3(child);
+  return normalizedChild !== normalizedParent && normalizedChild.startsWith(`${normalizedParent}${sep2}`);
+}
+function pathsOverlap(left, right) {
+  const normalizedLeft = resolve3(left);
+  const normalizedRight = resolve3(right);
+  return normalizedLeft === normalizedRight || isWithin(normalizedLeft, normalizedRight) || isWithin(normalizedRight, normalizedLeft);
+}
+
 // src/cli.ts
 function parseArgs(argv) {
   const args = [...argv];
@@ -8746,7 +9133,8 @@ function parseArgs(argv) {
     projectDir: process.cwd(),
     host: process.env.SUPACLOUD_LITE_HOST ?? "127.0.0.1",
     port: process.env.SUPACLOUD_LITE_PORT || process.env.PORT ? Number.parseInt(process.env.SUPACLOUD_LITE_PORT ?? process.env.PORT, 10) : 54321,
-    serviceRole: false
+    serviceRole: false,
+    force: false
   };
   for (let index = 0;index < args.length; index++) {
     const argument = args[index];
@@ -8765,13 +9153,13 @@ function parseArgs(argv) {
     else if (argument === "--site-url")
       options.siteUrl = next();
     else if (argument === "--project-dir" || argument === "--dir")
-      options.projectDir = resolve3(next());
+      options.projectDir = resolve4(next());
     else if (argument === "--state-dir")
-      options.stateDir = resolve3(next());
+      options.stateDir = resolve4(next());
     else if (argument === "--data-dir")
-      options.dataDir = resolve3(next());
+      options.dataDir = resolve4(next());
     else if (argument === "--storage-dir")
-      options.storageDir = resolve3(next());
+      options.storageDir = resolve4(next());
     else if (argument === "--storage-backend")
       options.storageBackend = next();
     else if (argument === "--s3-prefix")
@@ -8779,11 +9167,13 @@ function parseArgs(argv) {
     else if (argument === "--memory")
       options.memory = true;
     else if (argument === "--output" || argument === "-o")
-      options.output = resolve3(next());
+      options.output = resolve4(next());
     else if (argument === "--file" || argument === "-f")
       options.diffFile = next();
     else if (argument === "--service-role")
       options.serviceRole = true;
+    else if (argument === "--force")
+      options.force = true;
     else if (argument === "--version") {
       console.log(package_default.version);
       process.exit(0);
@@ -8822,6 +9212,14 @@ Use --service-role to print the privileged key.`);
     await runDbCommand(options);
     return;
   }
+  if (options.command === "snapshot") {
+    await runSnapshotCommand(options);
+    return;
+  }
+  if (options.command === "upgrade") {
+    await runUpgradeCommand(options);
+    return;
+  }
   if (options.command === "gen") {
     if (options.positionals[0] && options.positionals[0] !== "types" && options.positionals[0] !== "typescript") {
       throw new Error(`unknown gen subcommand: ${options.positionals[0]}`);
@@ -8830,8 +9228,8 @@ Use --service-role to print the privileged key.`);
     try {
       const source = await generateTypes(project2.backend.db, "public");
       if (options.output) {
-        await mkdir6(dirname4(options.output), { recursive: true });
-        await writeFile5(options.output, source);
+        await mkdir7(dirname5(options.output), { recursive: true });
+        await writeFile6(options.output, source);
         console.log(`Wrote ${options.output}`);
       } else
         process.stdout.write(source);
@@ -8901,8 +9299,8 @@ async function runDbCommand(options) {
     }
     await assertResetPathsSafe(paths);
     if (paths.dataDir)
-      await rm3(paths.dataDir, { recursive: true, force: true });
-    await rm3(paths.storageDir, { recursive: true, force: true });
+      await rm4(paths.dataDir, { recursive: true, force: true });
+    await rm4(paths.storageDir, { recursive: true, force: true });
     const project2 = await createProjectBackend({ ...options, includeFunctions: false, includeWebhooks: false, log: quietLog });
     try {
       const applied = await project2.backend.db.listAppliedMigrations();
@@ -8912,7 +9310,7 @@ async function runDbCommand(options) {
     }
     return;
   }
-  const project = await loadSupabaseProject(resolve3(options.projectDir ?? process.cwd()));
+  const project = await loadSupabaseProject(resolve4(options.projectDir ?? process.cwd()));
   if (subcommand === "diff") {
     const ddl = await computeDbDiff({ liveDataDir: paths.dataDir, migrations: project.migrations });
     if (ddl.length === 0) {
@@ -8925,9 +9323,9 @@ async function runDbCommand(options) {
 `;
     if (options.diffFile) {
       const stamp = timestamp();
-      const output = join8(paths.projectDir, "supabase", "migrations", `${stamp}_${options.diffFile}.sql`);
-      await mkdir6(join8(paths.projectDir, "supabase", "migrations"), { recursive: true });
-      await writeFile5(output, source);
+      const output = join9(paths.projectDir, "supabase", "migrations", `${stamp}_${options.diffFile}.sql`);
+      await mkdir7(join9(paths.projectDir, "supabase", "migrations"), { recursive: true });
+      await writeFile6(output, source);
       console.log(`Wrote ${output}`);
     } else
       process.stdout.write(source);
@@ -8937,7 +9335,7 @@ async function runDbCommand(options) {
     const result = await pullSchema({
       liveDataDir: paths.dataDir,
       migrations: project.migrations,
-      migrationsDir: join8(paths.projectDir, "supabase", "migrations"),
+      migrationsDir: join9(paths.projectDir, "supabase", "migrations"),
       name: options.positionals[1] ?? "remote_schema"
     });
     if (!result.path)
@@ -8948,6 +9346,63 @@ async function runDbCommand(options) {
   }
   throw new Error(`unknown db subcommand: ${subcommand ?? "(none)"}`);
 }
+async function runSnapshotCommand(options) {
+  const subcommand = options.positionals[0];
+  const paths = resolveProjectPaths(options);
+  const storageBackend = resolveStorageBackend(options.storageBackend);
+  if (options.memory)
+    throw new Error("snapshot does not support --memory because the database is not durable");
+  if (subcommand === "create") {
+    await ensureProjectSecrets(paths);
+    const output = options.output ?? join9(paths.stateDir, "backups", `snapshot-${timestamp()}.tar.gz`);
+    const manifest = await createSnapshot({ paths, packageVersion: package_default.version, storageBackend, output });
+    console.log(`Snapshot created: ${output}`);
+    if (manifest.storageBackend === "s3")
+      console.log("S3 objects were not copied; the snapshot contains database metadata and secrets only.");
+    return;
+  }
+  if (subcommand === "restore") {
+    const input = options.positionals[1];
+    if (!input)
+      throw new Error("snapshot restore requires a snapshot file");
+    const result = await restoreSnapshot({ paths, storageBackend, input, force: options.force });
+    console.log(`Snapshot restored from ${resolve4(input)}`);
+    for (const rollbackPath of result.rollbackPaths)
+      console.log(`Previous state retained at ${rollbackPath}`);
+    if (result.manifest.storageBackend === "s3")
+      console.log("Reconnect the original S3 bucket/prefix before starting Lite.");
+    return;
+  }
+  throw new Error(`unknown snapshot subcommand: ${subcommand ?? "(none)"}`);
+}
+async function runUpgradeCommand(options) {
+  if (options.memory)
+    throw new Error("upgrade does not support --memory because there is no durable database to back up");
+  const paths = resolveProjectPaths(options);
+  const storageBackend = resolveStorageBackend(options.storageBackend);
+  await ensureProjectSecrets(paths);
+  const output = options.output ?? join9(paths.stateDir, "backups", `pre-upgrade-${timestamp()}.tar.gz`);
+  await createSnapshot({ paths, packageVersion: package_default.version, storageBackend, output });
+  console.log(`Pre-upgrade snapshot: ${output}`);
+  try {
+    const project = await createProjectBackend({
+      ...options,
+      applyMigrations: true,
+      includeFunctions: false,
+      includeWebhooks: false,
+      includeSeed: true,
+      log: quietLog
+    });
+    try {
+      const applied = await project.backend.db.listAppliedMigrations();
+      console.log(`Upgrade complete on @supacloud/lite ${package_default.version}: ${applied.length} migration(s) recorded.`);
+    } finally {
+      await project.backend.close();
+    }
+  } catch (error) {
+    throw new Error(`upgrade failed; snapshot retained at ${output}. Restore it with ` + `"supacloud-lite snapshot restore ${output} --force". ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
 function printInspection(rows) {
   if (rows.length === 0) {
     console.log('No tables in schema "public".');
@@ -8984,6 +9439,9 @@ Commands:
   db reset              wipe database and storage, then re-run migrations
   db diff               print schema changes outside migrations
   db pull [name]        write live schema changes as an applied migration
+  snapshot create       create a compressed database/storage/secrets snapshot
+  snapshot restore <f>  restore a snapshot into an empty target
+  upgrade               snapshot first, then apply pending migrations
   inspect               show table rows and sizes
   version               print the package version
 
@@ -9001,6 +9459,7 @@ Options:
       --memory            use an in-memory PGlite database
   -o, --output <p>        output file for gen types
   -f, --file <name>       migration suffix for db diff
+      --force             replace non-empty restore targets and retain rollback copies
 `);
 }
 function formatStorage(backend, storageDir) {

package/dist/index.d.ts

@@ -9,5 +9,6 @@ export { FsStorageDriver } from './vendor/tinbase/node/fs-driver.js';
 export { serveBun } from './vendor/tinbase/node/bun-server.js';
 export type { RunningServer, ServerHandle, ServeOptions } from './vendor/tinbase/node/bun-server.js';
 export { createProjectBackend, ensureProjectSecrets, mintProjectKeys, resolveStorageBackend, resolveProjectPaths, startProjectServer, } from './project-runtime.js';
+export { createSnapshot, restoreSnapshot, type CreateSnapshotOptions, type RestoreSnapshotOptions, type RestoreSnapshotResult, type SnapshotManifest, } from './snapshot.js';
 export type { ConfiguredStorageBackend, ProjectBackend, ProjectPaths, ProjectRuntimeOptions, ProjectSecrets, RunningProjectServer, StorageBackend, } from './project-runtime.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,IAAI,iBAAiB,EAClC,kBAAkB,EAClB,SAAS,EACT,aAAa,EACb,SAAS,EACT,OAAO,EACP,SAAS,GACV,MAAM,2BAA2B,CAAA;AAClC,YAAY,EACV,aAAa,IAAI,mBAAmB,EACpC,cAAc,IAAI,oBAAoB,GACvC,MAAM,2BAA2B,CAAA;AAClC,YAAY,EACV,UAAU,EACV,MAAM,EACN,WAAW,EACX,aAAa,EACb,cAAc,EACd,aAAa,GACd,MAAM,2BAA2B,CAAA;AAClC,OAAO,EAAE,mBAAmB,EAAE,MAAM,oCAAoC,CAAA;AACxE,OAAO,EACL,eAAe,EACf,KAAK,mBAAmB,EACxB,KAAK,sBAAsB,EAC3B,KAAK,iBAAiB,GACvB,MAAM,uCAAuC,CAAA;AAC9C,YAAY,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,uCAAuC,CAAA;AAC1F,OAAO,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAA;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,oCAAoC,CAAA;AACpE,OAAO,EAAE,QAAQ,EAAE,MAAM,qCAAqC,CAAA;AAC9D,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,qCAAqC,CAAA;AACpG,OAAO,EACL,oBAAoB,EACpB,oBAAoB,EACpB,eAAe,EACf,qBAAqB,EACrB,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,sBAAsB,CAAA;AAC7B,YAAY,EACV,wBAAwB,EACxB,cAAc,EACd,YAAY,EACZ,qBAAqB,EACrB,cAAc,EACd,oBAAoB,EACpB,cAAc,GACf,MAAM,sBAAsB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,IAAI,iBAAiB,EAClC,kBAAkB,EAClB,SAAS,EACT,aAAa,EACb,SAAS,EACT,OAAO,EACP,SAAS,GACV,MAAM,2BAA2B,CAAA;AAClC,YAAY,EACV,aAAa,IAAI,mBAAmB,EACpC,cAAc,IAAI,oBAAoB,GACvC,MAAM,2BAA2B,CAAA;AAClC,YAAY,EACV,UAAU,EACV,MAAM,EACN,WAAW,EACX,aAAa,EACb,cAAc,EACd,aAAa,GACd,MAAM,2BAA2B,CAAA;AAClC,OAAO,EAAE,mBAAmB,EAAE,MAAM,oCAAoC,CAAA;AACxE,OAAO,EACL,eAAe,EACf,KAAK,mBAAmB,EACxB,KAAK,sBAAsB,EAC3B,KAAK,iBAAiB,GACvB,MAAM,uCAAuC,CAAA;AAC9C,YAAY,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,uCAAuC,CAAA;AAC1F,OAAO,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAA;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,oCAAoC,CAAA;AACpE,OAAO,EAAE,QAAQ,EAAE,MAAM,qCAAqC,CAAA;AAC9D,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,qCAAqC,CAAA;AACpG,OAAO,EACL,oBAAoB,EACpB,oBAAoB,EACpB,eAAe,EACf,qBAAqB,EACrB,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EACL,cAAc,EACd,eAAe,EACf,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAC1B,KAAK,gBAAgB,GACtB,MAAM,eAAe,CAAA;AACtB,YAAY,EACV,wBAAwB,EACxB,cAAc,EACd,YAAY,EACZ,qBAAqB,EACrB,cAAc,EACd,oBAAoB,EACpB,cAAc,GACf,MAAM,sBAAsB,CAAA"}

package/dist/index.js

@@ -71,7 +71,7 @@ function randomToken(bytes = 32) {
 // package.json
 var package_default = {
   name: "@supacloud/lite",
-  version: "0.2.0",
+  version: "0.3.0",
   description: "Bun-native, single-project Supabase-compatible backend powered by PGlite",
   type: "module",
   license: "Apache-2.0",
@@ -95,7 +95,7 @@ var package_default = {
   ],
   scripts: {
     build: "bun run build:js && bun run build:types",
-    "build:js": "bun build src/index.ts --target=bun --format=esm --outdir=dist --external @electric-sql/pglite && bun build src/cli.ts --target=bun --format=esm --outdir=dist --external @electric-sql/pglite",
+    "build:js": "bun build src/index.ts --target=bun --format=esm --outdir=dist --external @electric-sql/pglite --external tar && bun build src/cli.ts --target=bun --format=esm --outdir=dist --external @electric-sql/pglite --external tar",
     "build:types": "bun x tsc --emitDeclarationOnly -p tsconfig.build.json",
     check: "bun run typecheck && bun run test && bun run build && bun run test:package",
     dev: "bun run src/cli.ts start",
@@ -106,10 +106,11 @@ var package_default = {
     typecheck: "bun x tsc --noEmit -p tsconfig.json"
   },
   dependencies: {
-    "@electric-sql/pglite": "0.5.4"
+    "@electric-sql/pglite": "0.5.4",
+    tar: "^7.5.22"
   },
   devDependencies: {
-    "@supabase/supabase-js": "^2.57.4",
+    "@supabase/supabase-js": "^2.110.9",
     "@types/bun": "^1.3.14",
     typescript: "^5.9.3"
   },
@@ -8447,11 +8448,397 @@ async function findEphemeralPort(host = "127.0.0.1") {
     throw new Error("Bun did not allocate an ephemeral port");
   return port;
 }
+// src/snapshot.ts
+import { chmod as chmod2, copyFile, link as link2, lstat as lstat2, mkdir as mkdir5, mkdtemp, readdir as readdir3, readFile as readFile7, rename as rename2, rm as rm3, writeFile as writeFile4 } from "fs/promises";
+import { dirname as dirname4, join as join7, parse as parse2, relative as relative2, resolve as resolve3, sep as sep2 } from "path";
+import { create as createTar, extract as extractTar } from "tar";
+var SNAPSHOT_FORMAT = "supacloud-lite-snapshot";
+var SNAPSHOT_VERSION = 1;
+async function createSnapshot(options) {
+  const paths = normalizePaths(options.paths);
+  await assertSnapshotPaths(paths);
+  await assertNoDataDirectoryLock(paths);
+  const manifest = {
+    format: SNAPSHOT_FORMAT,
+    version: SNAPSHOT_VERSION,
+    createdAt: new Date().toISOString(),
+    packageVersion: options.packageVersion,
+    storageBackend: options.storageBackend,
+    includesDatabase: Boolean(paths.dataDir),
+    includesLocalStorage: options.storageBackend === "fs",
+    includesSecrets: true
+  };
+  const output = resolve3(options.output);
+  if (await existingInfo(output))
+    throw new Error(`snapshot output already exists: ${output}`);
+  await mkdir5(dirname4(output), { recursive: true });
+  const stagingRoot = await mkdtemp(join7(dirname4(output), ".supacloud-lite-snapshot-"));
+  try {
+    await writeFile4(join7(stagingRoot, "manifest.json"), `${JSON.stringify(manifest, null, 2)}
+`);
+    await stageFile(paths.secretsFile, join7(stagingRoot, "secrets.json"));
+    if (paths.dataDir)
+      await stageDirectory(paths.dataDir, join7(stagingRoot, "database"));
+    if (options.storageBackend === "fs")
+      await stageDirectory(paths.storageDir, join7(stagingRoot, "storage"));
+    const entries = ["manifest.json", "secrets.json"];
+    if (paths.dataDir)
+      entries.push("database");
+    if (options.storageBackend === "fs")
+      entries.push("storage");
+    await createTar({ cwd: stagingRoot, file: output, gzip: true, portable: true }, entries);
+    if (process.platform !== "win32")
+      await chmod2(output, 384);
+    return manifest;
+  } catch (error) {
+    await rm3(output, { force: true });
+    throw error;
+  } finally {
+    await rm3(stagingRoot, { recursive: true, force: true });
+  }
+}
+async function restoreSnapshot(options) {
+  const paths = normalizePaths(options.paths);
+  await assertSnapshotPaths(paths, { requireSecrets: false, allowMissingState: true });
+  await assertNoDataDirectoryLock(paths);
+  const stagingRoot = await mkdtemp(join7(dirname4(paths.stateDir), ".supacloud-lite-restore-"));
+  const payloadRoot = join7(stagingRoot, "payload");
+  const rollbackId = crypto.randomUUID();
+  const rollbackPaths = [];
+  try {
+    await mkdir5(payloadRoot, { recursive: true });
+    await extractTar({
+      cwd: payloadRoot,
+      file: resolve3(options.input),
+      preserveOwner: false,
+      preservePaths: false,
+      strict: true,
+      unlink: true,
+      filter: (path, entry) => {
+        const normalized = path.replaceAll("\\", "/");
+        const allowedPath = normalized === "manifest.json" || normalized === "secrets.json" || normalized === "database" || normalized.startsWith("database/") || normalized === "storage" || normalized.startsWith("storage/");
+        if (!allowedPath || normalized.startsWith("/") || normalized.split("/").includes("..")) {
+          throw new Error(`snapshot contains an unsafe path: ${path}`);
+        }
+        const entryType = "type" in entry ? entry.type : undefined;
+        if (entryType !== "File" && entryType !== "Directory") {
+          throw new Error(`snapshot contains an unsupported entry type: ${entryType ?? "unknown"}`);
+        }
+        return true;
+      }
+    });
+    await assertNoSymlinks(payloadRoot);
+    const manifest = await readManifest(payloadRoot);
+    if (manifest.storageBackend !== options.storageBackend) {
+      throw new Error(`snapshot storage backend is ${manifest.storageBackend}, but the target uses ${options.storageBackend}; ` + "restore with the matching --storage-backend value");
+    }
+    if (manifest.includesDatabase !== Boolean(paths.dataDir)) {
+      throw new Error("snapshot database mode does not match the target; do not restore a persistent snapshot into --memory");
+    }
+    if (manifest.includesLocalStorage !== (options.storageBackend === "fs")) {
+      throw new Error("snapshot storage payload does not match the target storage backend");
+    }
+    await assertSnapshotPayload(payloadRoot, manifest);
+    if (manifest.includesDatabase)
+      await mkdir5(join7(payloadRoot, "database"), { recursive: true });
+    if (manifest.includesLocalStorage)
+      await mkdir5(join7(payloadRoot, "storage"), { recursive: true });
+    await assertRestoreTargets(paths, manifest, options.force === true);
+    const stateStage = join7(stagingRoot, "state");
+    await mkdir5(stateStage, { recursive: true });
+    await copyEntry(join7(payloadRoot, "secrets.json"), join7(stateStage, "secrets.json"));
+    if (paths.dataDir && isWithin(paths.stateDir, paths.dataDir)) {
+      await copyEntry(join7(payloadRoot, "database"), join7(stateStage, relative2(paths.stateDir, paths.dataDir)));
+    }
+    if (options.storageBackend === "fs" && isWithin(paths.stateDir, paths.storageDir)) {
+      await copyEntry(join7(payloadRoot, "storage"), join7(stateStage, relative2(paths.stateDir, paths.storageDir)));
+    }
+    const swaps = [];
+    try {
+      await applyDirectorySwap(stateStage, paths.stateDir, options.force === true, rollbackId, swaps);
+      if (paths.dataDir && !isWithin(paths.stateDir, paths.dataDir)) {
+        await applyDirectorySwap(join7(payloadRoot, "database"), paths.dataDir, options.force === true, rollbackId, swaps);
+      }
+      if (options.storageBackend === "fs" && !isWithin(paths.stateDir, paths.storageDir)) {
+        await applyDirectorySwap(join7(payloadRoot, "storage"), paths.storageDir, options.force === true, rollbackId, swaps);
+      }
+    } catch (error) {
+      await rollbackDirectorySwaps(swaps);
+      throw error;
+    }
+    rollbackPaths.push(...swaps.flatMap((swap) => swap.rollbackPath ? [swap.rollbackPath] : []));
+    if (process.platform !== "win32") {
+      await hardenRestoredTree(paths.stateDir);
+      if (paths.dataDir && !isWithin(paths.stateDir, paths.dataDir))
+        await hardenRestoredTree(paths.dataDir);
+      if (options.storageBackend === "fs" && !isWithin(paths.stateDir, paths.storageDir)) {
+        await hardenRestoredTree(paths.storageDir);
+      }
+    }
+    return { manifest, rollbackPaths };
+  } catch (error) {
+    throw error instanceof Error ? error : new Error(String(error));
+  } finally {
+    await rm3(stagingRoot, { recursive: true, force: true });
+  }
+}
+function normalizePaths(paths) {
+  return {
+    ...paths,
+    projectDir: resolve3(paths.projectDir),
+    stateDir: resolve3(paths.stateDir),
+    dataDir: paths.dataDir ? resolve3(paths.dataDir) : undefined,
+    storageDir: resolve3(paths.storageDir),
+    secretsFile: resolve3(paths.secretsFile)
+  };
+}
+async function assertSnapshotPaths(paths, options = {}) {
+  try {
+    if (paths.stateDir === parse2(paths.stateDir).root)
+      throw new Error("snapshot state directory must not be the filesystem root");
+    if (paths.secretsFile !== join7(paths.stateDir, "secrets.json"))
+      throw new Error("snapshot secrets path must be inside the state directory");
+    const stateInfo = await lstat2(paths.stateDir);
+    if (!stateInfo.isDirectory() || stateInfo.isSymbolicLink())
+      throw new Error(`state directory must be a real directory: ${paths.stateDir}`);
+  } catch (error) {
+    if (error.code !== "ENOENT" || options.allowMissingState !== true)
+      throw error;
+  }
+  if (paths.dataDir && paths.storageDir && pathsOverlap(paths.dataDir, paths.storageDir)) {
+    throw new Error("database and storage directories must not overlap");
+  }
+  await assertDirectoryOrMissing(paths.dataDir);
+  await assertDirectoryOrMissing(paths.storageDir);
+  if (options.requireSecrets !== false) {
+    const secretInfo = await lstat2(paths.secretsFile);
+    if (!secretInfo.isFile() || secretInfo.isSymbolicLink())
+      throw new Error(`secrets file must be a regular file: ${paths.secretsFile}`);
+  }
+}
+async function assertDirectoryOrMissing(path) {
+  if (!path)
+    return;
+  if (resolve3(path) === parse2(resolve3(path)).root)
+    throw new Error(`snapshot path must not be the filesystem root: ${path}`);
+  try {
+    const info = await lstat2(path);
+    if (!info.isDirectory() || info.isSymbolicLink())
+      throw new Error(`snapshot path must be a real directory: ${path}`);
+  } catch (error) {
+    if (error.code !== "ENOENT")
+      throw error;
+  }
+}
+async function assertNoDataDirectoryLock(paths) {
+  if (!paths.dataDir)
+    return;
+  const lockPath = `${paths.dataDir}.supacloud-lite.lock`;
+  try {
+    await lstat2(lockPath);
+    throw new Error(`data directory is in use or has a stale lock: ${lockPath}; stop Lite and remove the lock manually if it is stale`);
+  } catch (error) {
+    if (error.code !== "ENOENT")
+      throw error;
+  }
+}
+async function stageDirectory(root, destination) {
+  try {
+    const info = await lstat2(root);
+    if (!info.isDirectory() || info.isSymbolicLink())
+      throw new Error(`snapshot path must be a real directory: ${root}`);
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      await mkdir5(destination, { recursive: true });
+      return;
+    }
+    throw error;
+  }
+  await mkdir5(destination, { recursive: true });
+  const walk = async (current, target) => {
+    for (const entry of await readdir3(current, { withFileTypes: true })) {
+      const fullPath = join7(current, entry.name);
+      const targetPath = join7(target, entry.name);
+      if (entry.isSymbolicLink())
+        throw new Error(`snapshot refuses symbolic link: ${fullPath}`);
+      if (entry.isDirectory()) {
+        await mkdir5(targetPath, { recursive: true });
+        await walk(fullPath, targetPath);
+      } else if (entry.isFile()) {
+        await stageFile(fullPath, targetPath);
+      } else {
+        throw new Error(`snapshot refuses unsupported filesystem entry: ${fullPath}`);
+      }
+    }
+  };
+  await walk(root, destination);
+}
+async function stageFile(source, target) {
+  await mkdir5(dirname4(target), { recursive: true });
+  try {
+    await link2(source, target);
+  } catch (error) {
+    const code = error.code;
+    if (code !== "EXDEV" && code !== "EPERM" && code !== "EACCES")
+      throw error;
+    await copyFile(source, target);
+  }
+}
+async function readManifest(payloadRoot) {
+  let parsed;
+  try {
+    parsed = JSON.parse(await readFile7(join7(payloadRoot, "manifest.json"), "utf8"));
+  } catch (error) {
+    throw new Error(`invalid snapshot manifest: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  if (!isSnapshotManifest(parsed))
+    throw new Error("unsupported or invalid SupaCloud Lite snapshot manifest");
+  return parsed;
+}
+function isSnapshotManifest(value) {
+  if (!value || typeof value !== "object")
+    return false;
+  const candidate = value;
+  return candidate.format === SNAPSHOT_FORMAT && candidate.version === SNAPSHOT_VERSION && typeof candidate.createdAt === "string" && typeof candidate.packageVersion === "string" && (candidate.storageBackend === "fs" || candidate.storageBackend === "s3" || candidate.storageBackend === "memory") && typeof candidate.includesDatabase === "boolean" && typeof candidate.includesLocalStorage === "boolean" && candidate.includesSecrets === true;
+}
+async function assertSnapshotPayload(payloadRoot, manifest) {
+  const required = ["manifest.json", "secrets.json"];
+  for (const path of required) {
+    try {
+      await lstat2(join7(payloadRoot, path));
+    } catch {
+      throw new Error(`snapshot is missing required payload: ${path}`);
+    }
+  }
+  const allowed = [...required];
+  if (manifest.includesDatabase)
+    allowed.push("database");
+  if (manifest.includesLocalStorage)
+    allowed.push("storage");
+  for (const entry of await readdir3(payloadRoot)) {
+    if (!allowed.includes(entry)) {
+      throw new Error(`snapshot contains an unexpected payload entry: ${entry}`);
+    }
+  }
+}
+async function assertRestoreTargets(paths, manifest, force) {
+  const targets = [paths.stateDir];
+  if (paths.dataDir && !isWithin(paths.stateDir, paths.dataDir))
+    targets.push(paths.dataDir);
+  if (manifest.includesLocalStorage && !isWithin(paths.stateDir, paths.storageDir))
+    targets.push(paths.storageDir);
+  if (!force) {
+    for (const target of targets) {
+      if (await directoryHasEntries(target))
+        throw new Error(`restore target is not empty: ${target}; pass --force to replace it`);
+    }
+  }
+}
+async function directoryHasEntries(path) {
+  try {
+    return (await readdir3(path)).length > 0;
+  } catch (error) {
+    if (error.code === "ENOENT")
+      return false;
+    throw error;
+  }
+}
+async function applyDirectorySwap(source, target, force, rollbackId, swaps) {
+  const targetInfo = await existingInfo(target);
+  if (targetInfo && !targetInfo.isDirectory())
+    throw new Error(`restore target is not a directory: ${target}`);
+  const swap = { target };
+  if (targetInfo) {
+    if (!force) {
+      if (await directoryHasEntries(target))
+        throw new Error(`restore target is not empty: ${target}; pass --force to replace it`);
+      await rm3(target, { recursive: true, force: true });
+    } else {
+      swap.rollbackPath = join7(dirname4(target), `.${target.split(sep2).pop() ?? "state"}.restore-${rollbackId}`);
+      await rename2(target, swap.rollbackPath);
+    }
+  }
+  try {
+    await mkdir5(dirname4(target), { recursive: true });
+    await rename2(source, target);
+    swaps.push(swap);
+  } catch (error) {
+    if (swap.rollbackPath)
+      await rename2(swap.rollbackPath, target).catch(() => {});
+    throw error;
+  }
+}
+async function rollbackDirectorySwaps(swaps) {
+  for (const swap of [...swaps].reverse()) {
+    await rm3(swap.target, { recursive: true, force: true });
+    if (swap.rollbackPath)
+      await rename2(swap.rollbackPath, swap.target);
+  }
+}
+async function existingInfo(path) {
+  try {
+    return await lstat2(path);
+  } catch (error) {
+    if (error.code === "ENOENT")
+      return null;
+    throw error;
+  }
+}
+async function copyEntry(source, target) {
+  const info = await lstat2(source);
+  if (info.isSymbolicLink())
+    throw new Error(`snapshot refuses symbolic link: ${source}`);
+  if (info.isDirectory()) {
+    await mkdir5(target, { recursive: true });
+    for (const entry of await readdir3(source))
+      await copyEntry(join7(source, entry), join7(target, entry));
+  } else if (info.isFile()) {
+    await mkdir5(dirname4(target), { recursive: true });
+    await Bun.write(target, Bun.file(source));
+  } else
+    throw new Error(`snapshot refuses unsupported filesystem entry: ${source}`);
+}
+async function hardenRestoredTree(root) {
+  const info = await lstat2(root);
+  if (info.isSymbolicLink())
+    throw new Error(`snapshot refuses symbolic link: ${root}`);
+  if (info.isDirectory()) {
+    await chmod2(root, 448);
+    for (const entry of await readdir3(root))
+      await hardenRestoredTree(join7(root, entry));
+    return;
+  }
+  if (info.isFile()) {
+    await chmod2(root, 384);
+    return;
+  }
+  throw new Error(`snapshot refuses unsupported filesystem entry: ${root}`);
+}
+async function assertNoSymlinks(root) {
+  for (const entry of await readdir3(root, { withFileTypes: true })) {
+    const fullPath = join7(root, entry.name);
+    if (entry.isSymbolicLink())
+      throw new Error(`snapshot refuses symbolic link in archive: ${fullPath}`);
+    if (entry.isDirectory())
+      await assertNoSymlinks(fullPath);
+  }
+}
+function isWithin(parent, child) {
+  const normalizedParent = resolve3(parent);
+  const normalizedChild = resolve3(child);
+  return normalizedChild !== normalizedParent && normalizedChild.startsWith(`${normalizedParent}${sep2}`);
+}
+function pathsOverlap(left, right) {
+  const normalizedLeft = resolve3(left);
+  const normalizedRight = resolve3(right);
+  return normalizedLeft === normalizedRight || isWithin(normalizedLeft, normalizedRight) || isWithin(normalizedRight, normalizedLeft);
+}
 export {
   verifyJwt,
   startProjectServer,
   signJwt,
   serveBun,
+  restoreSnapshot,
   resolveStorageBackend,
   resolveProjectPaths,
   mintProjectKeys,
@@ -8459,6 +8846,7 @@ export {
   generateTypes,
   ensureProjectSecrets,
   decodeJwt,
+  createSnapshot,
   createProjectBackend,
   createPgliteEngine,
   createBackend as createLiteBackend,

package/dist/snapshot.d.ts

@@ -0,0 +1,41 @@
+import type { ConfiguredStorageBackend, ProjectPaths } from './project-runtime.js';
+declare const SNAPSHOT_FORMAT = "supacloud-lite-snapshot";
+declare const SNAPSHOT_VERSION = 1;
+export interface SnapshotManifest {
+    format: typeof SNAPSHOT_FORMAT;
+    version: typeof SNAPSHOT_VERSION;
+    createdAt: string;
+    packageVersion: string;
+    storageBackend: ConfiguredStorageBackend;
+    includesDatabase: boolean;
+    includesLocalStorage: boolean;
+    includesSecrets: true;
+}
+export interface CreateSnapshotOptions {
+    paths: ProjectPaths;
+    packageVersion: string;
+    storageBackend: ConfiguredStorageBackend;
+    output: string;
+}
+export interface RestoreSnapshotOptions {
+    paths: ProjectPaths;
+    storageBackend: ConfiguredStorageBackend;
+    input: string;
+    force?: boolean;
+}
+export interface RestoreSnapshotResult {
+    manifest: SnapshotManifest;
+    rollbackPaths: string[];
+}
+/**
+ * Create a portable, compressed snapshot of the durable Lite state.
+ * The caller must stop Lite first; the data-directory lock is checked here.
+ */
+export declare function createSnapshot(options: CreateSnapshotOptions): Promise<SnapshotManifest>;
+/**
+ * Restore a snapshot without touching an existing non-empty target unless
+ * `force` is explicitly set. Existing targets are renamed aside for rollback.
+ */
+export declare function restoreSnapshot(options: RestoreSnapshotOptions): Promise<RestoreSnapshotResult>;
+export {};
+//# sourceMappingURL=snapshot.d.ts.map

package/dist/snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.d.ts","sourceRoot":"","sources":["../src/snapshot.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,wBAAwB,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAA;AAElF,QAAA,MAAM,eAAe,4BAA4B,CAAA;AACjD,QAAA,MAAM,gBAAgB,IAAI,CAAA;AAE1B,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,OAAO,eAAe,CAAA;IAC9B,OAAO,EAAE,OAAO,gBAAgB,CAAA;IAChC,SAAS,EAAE,MAAM,CAAA;IACjB,cAAc,EAAE,MAAM,CAAA;IACtB,cAAc,EAAE,wBAAwB,CAAA;IACxC,gBAAgB,EAAE,OAAO,CAAA;IACzB,oBAAoB,EAAE,OAAO,CAAA;IAC7B,eAAe,EAAE,IAAI,CAAA;CACtB;AAED,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,YAAY,CAAA;IACnB,cAAc,EAAE,MAAM,CAAA;IACtB,cAAc,EAAE,wBAAwB,CAAA;IACxC,MAAM,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,YAAY,CAAA;IACnB,cAAc,EAAE,wBAAwB,CAAA;IACxC,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,OAAO,CAAA;CAChB;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,gBAAgB,CAAA;IAC1B,aAAa,EAAE,MAAM,EAAE,CAAA;CACxB;AAED;;;GAGG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAqC9F;AAED;;;GAGG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,qBAAqB,CAAC,CA0FrG"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supacloud/lite",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Bun-native, single-project Supabase-compatible backend powered by PGlite",
   "type": "module",
   "license": "Apache-2.0",
@@ -24,7 +24,7 @@
   ],
   "scripts": {
     "build": "bun run build:js && bun run build:types",
-    "build:js": "bun build src/index.ts --target=bun --format=esm --outdir=dist --external @electric-sql/pglite && bun build src/cli.ts --target=bun --format=esm --outdir=dist --external @electric-sql/pglite",
+    "build:js": "bun build src/index.ts --target=bun --format=esm --outdir=dist --external @electric-sql/pglite --external tar && bun build src/cli.ts --target=bun --format=esm --outdir=dist --external @electric-sql/pglite --external tar",
     "build:types": "bun x tsc --emitDeclarationOnly -p tsconfig.build.json",
     "check": "bun run typecheck && bun run test && bun run build && bun run test:package",
     "dev": "bun run src/cli.ts start",
@@ -35,10 +35,11 @@
     "typecheck": "bun x tsc --noEmit -p tsconfig.json"
   },
   "dependencies": {
-    "@electric-sql/pglite": "0.5.4"
+    "@electric-sql/pglite": "0.5.4",
+    "tar": "^7.5.22"
   },
   "devDependencies": {
-    "@supabase/supabase-js": "^2.57.4",
+    "@supabase/supabase-js": "^2.110.9",
     "@types/bun": "^1.3.14",
     "typescript": "^5.9.3"
   },