@supacloud/lite 0.2.0 → 0.5.0

package/dist/cli.js

@@ -3,17 +3,17 @@
 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.5.0",
   description: "Bun-native, single-project Supabase-compatible backend powered by PGlite",
   type: "module",
   license: "Apache-2.0",
   bin: {
-    "supacloud-lite": "dist/cli.js"
+    "supacloud-lite": "dist/launcher.cjs"
   },
   exports: {
     ".": {
@@ -24,6 +24,7 @@ var package_default = {
   },
   files: [
     "dist",
+    "!dist/standalone",
     "README.md",
     "CHANGELOG.md",
     "RELEASING.md",
@@ -32,21 +33,28 @@ 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 && bun run scripts/build-launcher.ts",
+    "build:standalone:host": "bun run scripts/build-standalone.ts host",
+    "build:standalone:linux": "bun run scripts/build-standalone.ts linux-x64 linux-arm64",
+    "build:standalone:macos": "bun run scripts/build-standalone.ts macos-x64 macos-arm64",
+    "build:standalone:windows": "bun run scripts/build-standalone.ts windows-x64",
+    "build:standalone:release": "bun run scripts/build-standalone.ts linux-x64 linux-arm64 macos-x64 macos-arm64 windows-x64",
     "build:types": "bun x tsc --emitDeclarationOnly -p tsconfig.build.json",
-    check: "bun run typecheck && bun run test && bun run build && bun run test:package",
+    check: "bun run typecheck && bun run test && bun run build && bun run test:package && bun run build:standalone:host && bun run test:standalone",
     dev: "bun run src/cli.ts start",
     start: "bun run src/cli.ts start",
     test: "bun test --timeout 20000",
     "test:package": "bun run scripts/package-smoke.ts",
+    "test:standalone": "bun run scripts/standalone-smoke.ts",
     prepack: "bun run build",
     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"
   },
@@ -1257,30 +1265,7 @@ class AuthHandler {
       const token = body.refresh_token;
       if (!token)
         return authError(400, "validation_failed", "refresh_token required");
-      const res = await this.db.query(`select rt.*, u.id as uid from auth.refresh_tokens rt
-         join auth.users u on u.id = rt.user_id
-         where rt.token = $1`, [token]);
-      const row = res.rows[0];
-      if (!row || row.revoked) {
-        return authError(400, "refresh_token_not_found", "Invalid Refresh Token: Refresh Token Not Found");
-      }
-      const now = Date.now();
-      const lastActivity = timestampMs(row.created_at);
-      if (this.config.sessionInactivitySeconds && lastActivity !== null && now - lastActivity >= this.config.sessionInactivitySeconds * 1000) {
-        await this.db.query(`update auth.refresh_tokens set revoked = true, updated_at = now() where token = $1`, [token]);
-        return authError(400, "session_expired", "Session expired due to inactivity");
-      }
-      const sessionStartedAt = row.session_id ? timestampMs((await this.db.query(`select min(created_at) as started_at from auth.refresh_tokens where session_id = $1`, [row.session_id])).rows[0]?.started_at ?? null) : lastActivity;
-      if (this.config.sessionTimeboxSeconds && sessionStartedAt !== null && now - sessionStartedAt >= this.config.sessionTimeboxSeconds * 1000) {
-        await this.db.query(`update auth.refresh_tokens set revoked = true, updated_at = now() where token = $1`, [token]);
-        return authError(400, "session_expired", "Session expired");
-      }
-      await this.db.query(`update auth.refresh_tokens set revoked = true, updated_at = now() where token = $1`, [token]);
-      const ures = await this.db.query(`select * from auth.users where id = $1`, [row.user_id]);
-      return json(200, await this.sessionFor(ures.rows[0], token, {
-        sessionId: row.session_id ?? undefined,
-        sessionStartedAt: sessionStartedAt === null ? undefined : Math.floor(sessionStartedAt / 1000)
-      }));
+      return this.rotateRefreshToken(token);
     }
     if (grantType === "pkce") {
       const authCode = body.auth_code;
@@ -1704,8 +1689,8 @@ Or sign in with this link: ${link}`
       return authError(404, "mfa_factor_not_found", "MFA factor not found");
     return json(200, { id: factorId });
   }
-  async getUserFactors(userId) {
-    const res = await this.db.query(`select id, friendly_name, factor_type, status, created_at, updated_at
+  async getUserFactors(userId, query = (sql, params) => this.db.query(sql, params)) {
+    const res = await query(`select id, friendly_name, factor_type, status, created_at, updated_at
        from auth.mfa_factors where user_id = $1 order by created_at`, [userId]);
     return res.rows.map((f) => ({
       id: f.id,
@@ -1716,8 +1701,8 @@ Or sign in with this link: ${link}`
       updated_at: iso(f.updated_at)
     }));
   }
-  async getUserIdentities(userId) {
-    const res = await this.db.query(`select id, provider_id, user_id, identity_data, provider, created_at, updated_at, last_sign_in_at
+  async getUserIdentities(userId, query = (sql, params) => this.db.query(sql, params)) {
+    const res = await query(`select id, provider_id, user_id, identity_data, provider, created_at, updated_at, last_sign_in_at
        from auth.identities where user_id = $1 order by created_at`, [userId]);
     return res.rows.map((r) => ({
       identity_id: r.id,
@@ -1730,6 +1715,46 @@ Or sign in with this link: ${link}`
       updated_at: iso(r.updated_at)
     }));
   }
+  async rotateRefreshToken(token) {
+    return this.db.transaction(async (query) => {
+      const claimedToken = await this.claimRefreshToken(query, token);
+      if (!claimedToken)
+        return authError(400, "refresh_token_not_found", "Invalid Refresh Token: Refresh Token Not Found");
+      const sessionStartedAt = await this.refreshSessionStartedAt(query, claimedToken);
+      const expiryError = this.refreshExpiryError(claimedToken, sessionStartedAt);
+      if (expiryError)
+        return expiryError;
+      const userResult = await query(`select * from auth.users where id = $1`, [claimedToken.user_id]);
+      const session = await this.sessionFor(userResult.rows[0], token, {
+        sessionId: claimedToken.session_id ?? undefined,
+        sessionStartedAt: sessionStartedAt === null ? undefined : Math.floor(sessionStartedAt / 1000)
+      }, query);
+      return json(200, session);
+    });
+  }
+  async claimRefreshToken(query, token) {
+    const claimed = await query(`update auth.refresh_tokens set revoked = true, updated_at = now()
+       where token = $1 and revoked is not true
+       returning user_id, session_id, created_at`, [token]);
+    return claimed.rows[0];
+  }
+  async refreshSessionStartedAt(query, refreshToken) {
+    if (!refreshToken.session_id)
+      return timestampMs(refreshToken.created_at);
+    const sessionStart = await query(`select min(created_at) as started_at from auth.refresh_tokens where session_id = $1`, [refreshToken.session_id]);
+    return timestampMs(sessionStart.rows[0]?.started_at ?? null);
+  }
+  refreshExpiryError(refreshToken, sessionStartedAt) {
+    const now = Date.now();
+    const lastActivity = timestampMs(refreshToken.created_at);
+    if (this.config.sessionInactivitySeconds && lastActivity !== null && now - lastActivity >= this.config.sessionInactivitySeconds * 1000) {
+      return authError(400, "session_expired", "Session expired due to inactivity");
+    }
+    if (this.config.sessionTimeboxSeconds && sessionStartedAt !== null && now - sessionStartedAt >= this.config.sessionTimeboxSeconds * 1000) {
+      return authError(400, "session_expired", "Session expired");
+    }
+    return null;
+  }
   async userFromBearer(req) {
     const claims = await this.claimsFromBearer(req);
     if (!claims?.sub)
@@ -1767,7 +1792,7 @@ Or sign in with this link: ${link}`
     const session = await this.sessionFor(res.rows[0]);
     return { access_token: session.access_token, refresh_token: session.refresh_token, expires_in: session.expires_in };
   }
-  async sessionFor(user, parentToken, opts) {
+  async sessionFor(user, parentToken, opts, query = (sql, params) => this.db.query(sql, params)) {
     const now = Math.floor(Date.now() / 1000);
     const timeboxRemaining = this.config.sessionTimeboxSeconds ? opts?.sessionStartedAt !== undefined ? opts.sessionStartedAt + this.config.sessionTimeboxSeconds - now : this.config.sessionTimeboxSeconds : this.config.jwtExpiry;
     const lifetime = Math.max(1, Math.min(this.config.jwtExpiry, timeboxRemaining));
@@ -1791,14 +1816,14 @@ Or sign in with this link: ${link}`
     };
     const accessToken = await signJwt(claims, this.config.jwtSecret);
     const refreshToken = randomToken(24);
-    await this.db.query(`insert into auth.refresh_tokens (token, user_id, parent, session_id) values ($1, $2, $3, $4)`, [refreshToken, user.id, parentToken ?? null, sessionId]);
+    await query(`insert into auth.refresh_tokens (token, user_id, parent, session_id) values ($1, $2, $3, $4)`, [refreshToken, user.id, parentToken ?? null, sessionId]);
     return {
       access_token: accessToken,
       token_type: "bearer",
       expires_in: lifetime,
       expires_at: expiresAt,
       refresh_token: refreshToken,
-      user: this.userJson(user, await this.getUserFactors(user.id), await this.getUserIdentities(user.id))
+      user: this.userJson(user, await this.getUserFactors(user.id, query), await this.getUserIdentities(user.id, query))
     };
   }
 }
@@ -1984,13 +2009,182 @@ function resetCapturedHandler() {
   captured.handler = undefined;
 }
 
+// src/vendor/tinbase/functions/pgredis.ts
+import { AsyncLocalStorage as AsyncLocalStorage2 } from "async_hooks";
+var CACHE_NAMESPACE = "supacloud-edge-runtime";
+var CACHE_TABLE = "public.supacloud_pgredis_kv";
+var MAX_KEY_CHARACTERS = 512;
+var MAX_VALUE_BYTES = 1048576;
+var MAX_TTL_MS = 31536000000;
+var CACHE_SCHEMA_SQL = `
+create table if not exists ${CACHE_TABLE} (
+  namespace text not null,
+  key text not null,
+  value jsonb not null,
+  expires_at timestamptz,
+  updated_at timestamptz not null default now(),
+  primary key (namespace, key)
+);
+
+create index if not exists supacloud_pgredis_kv_expires_at_idx
+  on ${CACHE_TABLE} (expires_at) where expires_at is not null;
+`;
+var CACHE_PERMISSIONS_SQL = `
+revoke all on table ${CACHE_TABLE} from public, anon, authenticated, service_role;
+`;
+
+class PgredisCache {
+  db;
+  constructor(db) {
+    this.db = db;
+  }
+  static async create(db) {
+    await db.exec(CACHE_SCHEMA_SQL);
+    if (!db.engine.minimalBootstrap)
+      await db.exec(CACHE_PERMISSIONS_SQL);
+    return new PgredisCache(db);
+  }
+  async get(key) {
+    assertCacheKey(key);
+    return this.db.transaction(async (query) => {
+      await deleteExpiredKey(query, key);
+      const stored = await query(`select value::text as serialized_value from ${CACHE_TABLE} where namespace = $1 and key = $2`, [CACHE_NAMESPACE, key]);
+      return stored.rows[0] ? parseStoredValue(stored.rows[0]) : null;
+    });
+  }
+  async set(key, cacheValue, ttlMs) {
+    assertCacheKey(key);
+    assertTtl(ttlMs);
+    const serializedValue = serializeCacheValue(cacheValue);
+    await this.db.query(`insert into ${CACHE_TABLE} (namespace, key, value, expires_at, updated_at)
+       values ($1, $2, $3::jsonb,
+         case when $4::bigint is null then null else clock_timestamp() + $4::double precision * interval '1 millisecond' end,
+         now())
+       on conflict (namespace, key) do update set
+         value = excluded.value, expires_at = excluded.expires_at, updated_at = now()`, [CACHE_NAMESPACE, key, serializedValue, ttlMs ?? null]);
+    return true;
+  }
+  async delete(key) {
+    assertCacheKey(key);
+    return this.db.transaction(async (query) => {
+      await deleteExpiredKey(query, key);
+      const deleted = await query(`delete from ${CACHE_TABLE} where namespace = $1 and key = $2 returning key`, [CACHE_NAMESPACE, key]);
+      return deleted.rows.length > 0;
+    });
+  }
+  async ttl(key) {
+    assertCacheKey(key);
+    return this.db.transaction(async (query) => {
+      await deleteExpiredKey(query, key);
+      const stored = await query(`select case when expires_at is null then null
+          else greatest(0, ceil(extract(epoch from (expires_at - clock_timestamp())) * 1000))::bigint
+        end as ttl_ms from ${CACHE_TABLE} where namespace = $1 and key = $2`, [CACHE_NAMESPACE, key]);
+      const ttlMs = stored.rows[0]?.ttl_ms;
+      return ttlMs === null || ttlMs === undefined ? null : Number(ttlMs);
+    });
+  }
+  async getset(key, cacheValue) {
+    assertCacheKey(key);
+    const serializedValue = serializeCacheValue(cacheValue);
+    return this.db.transaction(async (query) => {
+      await deleteExpiredKey(query, key);
+      const previous = await query(`select value::text as serialized_value from ${CACHE_TABLE}
+         where namespace = $1 and key = $2 for update`, [CACHE_NAMESPACE, key]);
+      await upsertWithoutTtl(query, key, serializedValue);
+      return previous.rows[0] ? parseStoredValue(previous.rows[0]) : null;
+    });
+  }
+  async getdel(key) {
+    assertCacheKey(key);
+    return this.db.transaction(async (query) => {
+      await deleteExpiredKey(query, key);
+      const deleted = await query(`delete from ${CACHE_TABLE} where namespace = $1 and key = $2 returning value::text as serialized_value`, [CACHE_NAMESPACE, key]);
+      return deleted.rows[0] ? parseStoredValue(deleted.rows[0]) : null;
+    });
+  }
+}
+var cacheContexts = new AsyncLocalStorage2;
+var cacheFacade = Object.freeze({
+  get: async (key) => activeCache().get(key),
+  set: async (key, cacheValue, ttlMs) => activeCache().set(key, cacheValue, ttlMs),
+  delete: async (key) => activeCache().delete(key),
+  ttl: async (key) => activeCache().ttl(key),
+  getset: async (key, cacheValue) => activeCache().getset(key, cacheValue),
+  getdel: async (key) => activeCache().getdel(key)
+});
+function installPgredisShim() {
+  const runtime = globalThis;
+  if (runtime.SupaCloud?.pgredis) {
+    if (runtime.SupaCloud.pgredis === cacheFacade)
+      return;
+    throw new Error("globalThis.SupaCloud.pgredis is already owned by another runtime");
+  }
+  Object.defineProperty(runtime, "SupaCloud", {
+    configurable: false,
+    enumerable: true,
+    value: Object.freeze({ ...runtime.SupaCloud ?? {}, pgredis: cacheFacade }),
+    writable: false
+  });
+}
+function runWithPgredisCache(cache, operation) {
+  const context = { cache, active: true };
+  return cacheContexts.run(context, async () => {
+    try {
+      return await operation();
+    } finally {
+      context.active = false;
+    }
+  });
+}
+function activeCache() {
+  const context = cacheContexts.getStore();
+  if (!context?.active)
+    throw new Error("pgredis binding is unavailable outside a function request");
+  return context.cache;
+}
+function assertCacheKey(key) {
+  if (typeof key !== "string" || key.length < 1 || key.length > MAX_KEY_CHARACTERS) {
+    throw new TypeError(`pgredis key must contain between 1 and ${MAX_KEY_CHARACTERS} characters`);
+  }
+}
+function assertTtl(ttlMs) {
+  if (ttlMs === null || ttlMs === undefined)
+    return;
+  if (!Number.isSafeInteger(ttlMs) || ttlMs < 0)
+    throw new TypeError("pgredis ttlMs must be a non-negative safe integer or null");
+  if (ttlMs > MAX_TTL_MS)
+    throw new RangeError(`pgredis ttlMs must not exceed ${MAX_TTL_MS}`);
+}
+function serializeCacheValue(cacheValue) {
+  const serializedValue = JSON.stringify(cacheValue);
+  if (serializedValue === undefined)
+    throw new TypeError("pgredis value must be JSON serializable");
+  if (new TextEncoder().encode(serializedValue).byteLength > MAX_VALUE_BYTES) {
+    throw new RangeError(`pgredis value must not exceed ${MAX_VALUE_BYTES} bytes`);
+  }
+  return serializedValue;
+}
+function parseStoredValue(stored) {
+  return JSON.parse(stored.serialized_value);
+}
+async function deleteExpiredKey(query, key) {
+  await query(`delete from ${CACHE_TABLE} where namespace = $1 and key = $2 and expires_at <= clock_timestamp()`, [CACHE_NAMESPACE, key]);
+}
+async function upsertWithoutTtl(query, key, serializedValue) {
+  await query(`insert into ${CACHE_TABLE} (namespace, key, value, expires_at, updated_at)
+     values ($1, $2, $3::jsonb, null, now())
+     on conflict (namespace, key) do update set value = excluded.value, expires_at = null, updated_at = now()`, [CACHE_NAMESPACE, key, serializedValue]);
+}
+
 // src/vendor/tinbase/functions/handler.ts
 class FunctionsHandler {
   functions;
   env;
-  constructor(functions, env) {
+  pgredis;
+  constructor(functions, env, pgredis) {
     this.functions = functions;
     this.env = env;
+    this.pgredis = pgredis;
   }
   register(name, fn) {
     this.functions.set(name, fn);
@@ -2008,7 +2202,8 @@ class FunctionsHandler {
       return json2(404, { error: `function "${name}" not found` });
     }
     try {
-      const res = await runWithDenoEnv(this.env, () => Promise.resolve(fn(req, { auth: ctx, env: this.env })));
+      const invoke = () => Promise.resolve(fn(req, { auth: ctx, env: this.env }));
+      const res = await runWithDenoEnv(this.env, () => runWithPgredisCache(this.pgredis, invoke));
       if (!(res instanceof Response)) {
         return json2(500, { error: `function "${name}" did not return a Response` });
       }
@@ -2550,7 +2745,24 @@ grant execute on function realtime.send(jsonb, text, text, boolean) to anon, aut
 // src/vendor/tinbase/db/emulated.ts
 var PGMQ_SQL = `
 create schema if not exists pgmq;
-grant usage on schema pgmq to anon, authenticated, service_role;
+revoke all on schema pgmq from public, anon, authenticated;
+grant usage on schema pgmq to service_role;
+
+create table if not exists pgmq.meta (
+  queue_name text primary key,
+  physical_name text not null unique,
+  is_partitioned boolean not null default false,
+  is_unlogged boolean not null default false,
+  created_at timestamptz not null default now()
+);
+
+-- Preserve queues created by older Lite versions. Their physical names were
+-- the queue names, so only the already-truncated identifier can be recovered.
+insert into pgmq.meta (queue_name, physical_name)
+select substring(tablename from 3), substring(tablename from 3)
+from pg_tables
+where schemaname = 'pgmq' and left(tablename, 2) = 'q_'
+on conflict do nothing;
 
 do $$ begin
   if not exists (select 1 from pg_type t join pg_namespace n on n.oid = t.typnamespace
@@ -2561,32 +2773,78 @@ do $$ begin
   end if;
 end $$;
 
+create or replace function pgmq._normalize_queue_name(queue_name text)
+returns text language plpgsql immutable set search_path = pgmq, pg_catalog, public as $pgmq$
+declare normalized text := btrim(queue_name);
+begin
+  if normalized is null or normalized !~ '^[a-z0-9][a-z0-9_-]{0,127}$' then
+    raise exception 'invalid queue name: must match ^[a-z0-9][a-z0-9_-]{0,127}$'
+      using errcode = '22023';
+  end if;
+  return normalized;
+end $pgmq$;
+
+-- PostgreSQL identifiers are limited to 63 bytes. Keep the conventional table
+-- name for short queues and add a deterministic hash for valid 62-128 byte
+-- public names so truncation can never merge two queues.
+create or replace function pgmq._physical_queue_name(queue_name text)
+returns text language sql immutable set search_path = pgmq, pg_catalog, public as $pgmq$
+  select case when length(normalized) <= 61 then normalized
+    else left(normalized, 28) || '_' || md5(normalized) end
+  from (select pgmq._normalize_queue_name(queue_name) as normalized) names;
+$pgmq$;
+
+create or replace function pgmq._resolve_queue(queue_name text)
+returns text language plpgsql stable security definer set search_path = pgmq, pg_catalog, public as $pgmq$
+declare normalized text := pgmq._normalize_queue_name(queue_name); physical text;
+begin
+  select physical_name into physical from pgmq.meta where pgmq.meta.queue_name = normalized;
+  if physical is null then
+    raise exception 'queue "%" does not exist', normalized using errcode = '42P01';
+  end if;
+  return physical;
+end $pgmq$;
+
 create or replace function pgmq.create(queue_name text) returns void language plpgsql security definer set search_path = pgmq, pg_catalog, public as $pgmq$
+declare normalized text := pgmq._normalize_queue_name(queue_name); physical text := pgmq._physical_queue_name(queue_name);
 begin
+  insert into pgmq.meta (queue_name, physical_name) values (normalized, physical)
+  on conflict do nothing;
+  select physical_name into physical from pgmq.meta where pgmq.meta.queue_name = normalized;
   execute format('create table if not exists pgmq.%I (
     msg_id bigint generated always as identity primary key,
     read_ct integer not null default 0,
     enqueued_at timestamptz not null default now(),
     vt timestamptz not null default now(),
-    message jsonb)', 'q_' || queue_name);
+    message jsonb)', 'q_' || physical);
   execute format('create table if not exists pgmq.%I (
     msg_id bigint primary key, read_ct integer not null default 0,
     enqueued_at timestamptz not null, archived_at timestamptz not null default now(),
-    vt timestamptz, message jsonb)', 'a_' || queue_name);
+    vt timestamptz, message jsonb)', 'a_' || physical);
 end $pgmq$;
 
 create or replace function pgmq.send(queue_name text, msg jsonb, delay integer default 0)
 returns bigint language plpgsql security definer set search_path = pgmq, pg_catalog, public as $pgmq$
-declare id bigint;
+declare id bigint; physical text := pgmq._resolve_queue(queue_name);
 begin
-  perform pgmq.create(queue_name);
-  execute format('insert into pgmq.%I (vt, message) values (now() + make_interval(secs => $1), $2) returning msg_id', 'q_' || queue_name)
+  execute format('insert into pgmq.%I (vt, message) values (now() + make_interval(secs => $1), $2) returning msg_id', 'q_' || physical)
     into id using delay, msg;
   return id;
 end $pgmq$;
 
+create or replace function pgmq.send_batch(queue_name text, msgs jsonb[], delay integer default 0)
+returns setof bigint language plpgsql security definer set search_path = pgmq, pg_catalog, public as $pgmq$
+declare queue_message jsonb;
+begin
+  perform pgmq._resolve_queue(queue_name);
+  foreach queue_message in array msgs loop
+    return next pgmq.send(queue_name, queue_message, delay);
+  end loop;
+end $pgmq$;
+
 create or replace function pgmq.read(queue_name text, vt integer, qty integer)
 returns setof pgmq.message_record language plpgsql security definer set search_path = pgmq, pg_catalog, public as $pgmq$
+declare physical text := pgmq._resolve_queue(queue_name);
 begin
   return query execute format($fmt$
     with cte as (
@@ -2595,52 +2853,68 @@ begin
     update pgmq.%I m set vt = now() + make_interval(secs => $2), read_ct = read_ct + 1
     from cte where m.msg_id = cte.msg_id
     returning m.msg_id, m.read_ct, m.enqueued_at, m.vt, m.message
-  $fmt$, 'q_' || queue_name, 'q_' || queue_name) using qty, vt;
+  $fmt$, 'q_' || physical, 'q_' || physical) using qty, vt;
 end $pgmq$;
 
 create or replace function pgmq.pop(queue_name text)
 returns setof pgmq.message_record language plpgsql security definer set search_path = pgmq, pg_catalog, public as $pgmq$
+declare physical text := pgmq._resolve_queue(queue_name);
 begin
   return query execute format($fmt$
     with cte as (select msg_id from pgmq.%I where vt <= now() order by msg_id limit 1 for update skip locked)
     delete from pgmq.%I m using cte where m.msg_id = cte.msg_id
     returning m.msg_id, m.read_ct, m.enqueued_at, m.vt, m.message
-  $fmt$, 'q_' || queue_name, 'q_' || queue_name);
+  $fmt$, 'q_' || physical, 'q_' || physical);
+end $pgmq$;
+
+create or replace function pgmq.set_vt(queue_name text, msg_id bigint, vt_offset integer)
+returns setof pgmq.message_record language plpgsql security definer set search_path = pgmq, pg_catalog, public as $pgmq$
+declare physical text := pgmq._resolve_queue(queue_name);
+begin
+  return query execute format($fmt$
+    update pgmq.%I m set vt = now() + make_interval(secs => $1)
+    where m.msg_id = $2
+    returning m.msg_id, m.read_ct, m.enqueued_at, m.vt, m.message
+  $fmt$, 'q_' || physical) using vt_offset, msg_id;
 end $pgmq$;
 
 create or replace function pgmq.delete(queue_name text, msg_id bigint)
 returns boolean language plpgsql security definer set search_path = pgmq, pg_catalog, public as $pgmq$
-declare n integer;
+declare n integer; physical text := pgmq._resolve_queue(queue_name);
 begin
-  execute format('delete from pgmq.%I where msg_id = $1', 'q_' || queue_name) using msg_id;
+  execute format('delete from pgmq.%I where msg_id = $1', 'q_' || physical) using msg_id;
   get diagnostics n = row_count;
   return n > 0;
 end $pgmq$;
 
 create or replace function pgmq.archive(queue_name text, msg_id bigint)
 returns boolean language plpgsql security definer set search_path = pgmq, pg_catalog, public as $pgmq$
-declare n integer;
+declare n integer; physical text := pgmq._resolve_queue(queue_name);
 begin
   execute format($fmt$
     with del as (delete from pgmq.%I where msg_id = $1 returning *)
     insert into pgmq.%I (msg_id, read_ct, enqueued_at, vt, message)
     select msg_id, read_ct, enqueued_at, vt, message from del
-  $fmt$, 'q_' || queue_name, 'a_' || queue_name) using msg_id;
+  $fmt$, 'q_' || physical, 'a_' || physical) using msg_id;
   get diagnostics n = row_count;
   return n > 0;
 end $pgmq$;
 
 create or replace function pgmq.drop_queue(queue_name text) returns boolean language plpgsql security definer set search_path = pgmq, pg_catalog, public as $pgmq$
+declare normalized text := pgmq._normalize_queue_name(queue_name); physical text;
 begin
-  execute format('drop table if exists pgmq.%I', 'q_' || queue_name);
-  execute format('drop table if exists pgmq.%I', 'a_' || queue_name);
+  select physical_name into physical from pgmq.meta where pgmq.meta.queue_name = normalized;
+  if physical is null then return false; end if;
+  execute format('drop table if exists pgmq.%I', 'q_' || physical);
+  execute format('drop table if exists pgmq.%I', 'a_' || physical);
+  delete from pgmq.meta where pgmq.meta.queue_name = normalized;
   return true;
 end $pgmq$;
 
 create or replace function pgmq.purge_queue(queue_name text) returns bigint language plpgsql security definer set search_path = pgmq, pg_catalog, public as $pgmq$
-declare n bigint;
+declare n bigint; physical text := pgmq._resolve_queue(queue_name);
 begin
-  execute format('delete from pgmq.%I', 'q_' || queue_name);
+  execute format('delete from pgmq.%I', 'q_' || physical);
   get diagnostics n = row_count;
   return n;
 end $pgmq$;
@@ -2648,11 +2922,47 @@ end $pgmq$;
 create or replace function pgmq.list_queues()
 returns table(queue_name text, is_partitioned boolean, is_unlogged boolean, created_at timestamptz)
 language sql security definer set search_path = pgmq, pg_catalog, public as $pgmq$
-  select substring(tablename from 3), false, false, now()
-  from pg_tables where schemaname = 'pgmq' and left(tablename, 2) = 'q_';
+  select queue_name, is_partitioned, is_unlogged, created_at from pgmq.meta;
 $pgmq$;
 
-grant execute on all functions in schema pgmq to anon, authenticated, service_role;
+revoke all on all functions in schema pgmq from public, anon, authenticated;
+grant execute on all functions in schema pgmq to service_role;
+
+create schema if not exists pgmq_public;
+grant usage on schema pgmq_public to anon, authenticated, service_role;
+
+create or replace function pgmq_public.send(queue_name text, message jsonb, sleep_seconds integer default 0)
+returns setof bigint language sql volatile security definer set search_path = pgmq, pg_catalog, public as $pgmq_public$
+  select * from pgmq.send(queue_name, message, sleep_seconds);
+$pgmq_public$;
+
+create or replace function pgmq_public.send_batch(queue_name text, messages jsonb[], sleep_seconds integer default 0)
+returns setof bigint language sql volatile security definer set search_path = pgmq, pg_catalog, public as $pgmq_public$
+  select * from pgmq.send_batch(queue_name, messages, sleep_seconds);
+$pgmq_public$;
+
+create or replace function pgmq_public.read(queue_name text, sleep_seconds integer, n integer)
+returns setof pgmq.message_record language sql volatile security definer set search_path = pgmq, pg_catalog, public as $pgmq_public$
+  select * from pgmq.read(queue_name, sleep_seconds, n);
+$pgmq_public$;
+
+create or replace function pgmq_public.pop(queue_name text)
+returns setof pgmq.message_record language sql volatile security definer set search_path = pgmq, pg_catalog, public as $pgmq_public$
+  select * from pgmq.pop(queue_name);
+$pgmq_public$;
+
+create or replace function pgmq_public.archive(queue_name text, message_id bigint)
+returns boolean language sql volatile security definer set search_path = pgmq, pg_catalog, public as $pgmq_public$
+  select pgmq.archive(queue_name, message_id);
+$pgmq_public$;
+
+create or replace function pgmq_public."delete"(queue_name text, message_id bigint)
+returns boolean language sql volatile security definer set search_path = pgmq, pg_catalog, public as $pgmq_public$
+  select pgmq.delete(queue_name, message_id);
+$pgmq_public$;
+
+revoke all on all functions in schema pgmq_public from public;
+grant execute on all functions in schema pgmq_public to anon, authenticated, service_role;
 `;
 var CRON_SQL = `
 create schema if not exists cron;
@@ -2982,9 +3292,16 @@ function pickTag(text, base) {
 // src/vendor/tinbase/db/pglite-engine.ts
 import { mkdir, open, readFile, unlink } from "fs/promises";
 import { dirname, resolve } from "path";
+
+// src/standalone-assets-protocol.ts
+var STANDALONE_PGLITE_ASSETS = Symbol.for("supacloud-lite.pglite-standalone-assets");
+
+// src/vendor/tinbase/db/pglite-engine.ts
 async function createPgliteEngine(dataDir) {
   const releaseLock = await acquireDataDirLock(dataDir);
   let PGlite, extensions;
+  const standaloneAssets = getStandaloneAssets();
+  let cleanupStandaloneBundles = async () => {};
   try {
     ({ PGlite } = await import("@electric-sql/pglite"));
     const [uuid_ossp, pgcrypto, citext, pg_trgm, ltree, hstore, fuzzystrmatch] = await Promise.all([
@@ -2997,19 +3314,48 @@ async function createPgliteEngine(dataDir) {
       import("@electric-sql/pglite/contrib/fuzzystrmatch").then((m) => m.fuzzystrmatch)
     ]);
     extensions = { uuid_ossp, pgcrypto, citext, pg_trgm, ltree, hstore, fuzzystrmatch };
-  } catch (e) {
+  } catch (error) {
     await releaseLock();
-    if (e instanceof Error && /wasm/.test(e.message))
-      throw e;
+    if (error instanceof Error && /wasm/.test(error.message))
+      throw error;
     throw new Error("the PGlite WASM engine is not available in this build");
   }
+  if (standaloneAssets) {
+    try {
+      const standaloneBundles = await standaloneAssets.prepareExtensionBundles();
+      cleanupStandaloneBundles = standaloneBundles.cleanup;
+      extensions = {
+        uuid_ossp: withEmbeddedBundle(extensions.uuid_ossp, standaloneBundles.bundles.uuid_ossp),
+        pgcrypto: withEmbeddedBundle(extensions.pgcrypto, standaloneBundles.bundles.pgcrypto),
+        citext: withEmbeddedBundle(extensions.citext, standaloneBundles.bundles.citext),
+        pg_trgm: withEmbeddedBundle(extensions.pg_trgm, standaloneBundles.bundles.pg_trgm),
+        ltree: withEmbeddedBundle(extensions.ltree, standaloneBundles.bundles.ltree),
+        hstore: withEmbeddedBundle(extensions.hstore, standaloneBundles.bundles.hstore),
+        fuzzystrmatch: withEmbeddedBundle(extensions.fuzzystrmatch, standaloneBundles.bundles.fuzzystrmatch)
+      };
+    } catch (error) {
+      await removePreparedBundles(cleanupStandaloneBundles);
+      await releaseLock();
+      throw error;
+    }
+  }
   let pg;
   try {
-    pg = new PGlite({ dataDir, extensions });
+    pg = new PGlite({
+      dataDir,
+      extensions,
+      ...standaloneAssets ? {
+        pgliteWasmModule: standaloneAssets.pgliteWasmModule,
+        initdbWasmModule: standaloneAssets.initdbWasmModule,
+        fsBundle: standaloneAssets.fsBundle
+      } : {}
+    });
     await pg.waitReady;
   } catch (error) {
     await releaseLock();
     throw error;
+  } finally {
+    await removePreparedBundles(cleanupStandaloneBundles);
   }
   let closed = false;
   return {
@@ -3048,6 +3394,25 @@ async function createPgliteEngine(dataDir) {
     }
   };
 }
+function getStandaloneAssets() {
+  return globalThis[STANDALONE_PGLITE_ASSETS];
+}
+function withEmbeddedBundle(extension, bundlePath) {
+  return {
+    ...extension,
+    setup: async (pg, emscriptenOpts, clientOnly) => ({
+      ...await extension.setup(pg, emscriptenOpts, clientOnly),
+      bundlePath
+    })
+  };
+}
+async function removePreparedBundles(cleanup) {
+  try {
+    await cleanup();
+  } catch (error) {
+    console.error("Unable to remove temporary PGlite extension bundles:", error);
+  }
+}
 async function acquireDataDirLock(dataDir) {
   if (!dataDir || dataDir.includes("://"))
     return async () => {};
@@ -3055,21 +3420,7 @@ async function acquireDataDirLock(dataDir) {
   const lockPath = `${absoluteDataDir}.supacloud-lite.lock`;
   await mkdir(dirname(absoluteDataDir), { recursive: true, mode: 448 });
   const nonce = crypto.randomUUID();
-  let handle;
-  try {
-    handle = await open(lockPath, "wx", 384);
-    await handle.writeFile(`${JSON.stringify({ pid: process.pid, nonce, createdAt: new Date().toISOString() })}
-`);
-  } catch (error) {
-    await handle?.close().catch(() => {});
-    if (error.code !== "EEXIST")
-      throw error;
-    const owner = await readLockOwner(lockPath);
-    if (owner && isProcessAlive(owner.pid)) {
-      throw new Error(`PGlite data directory is already in use: ${absoluteDataDir} (pid ${owner.pid})`);
-    }
-    throw new Error(`PGlite data directory has a stale or unreadable lock: ${lockPath}. Confirm no SupaCloud Lite process is using it, then remove the lock manually.`);
-  }
+  const handle = await createDataDirLock(absoluteDataDir, lockPath, nonce);
   let released = false;
   return async () => {
     if (released)
@@ -3085,10 +3436,48 @@ async function acquireDataDirLock(dataDir) {
     });
   };
 }
+async function createDataDirLock(absoluteDataDir, lockPath, nonce) {
+  for (let attempt = 0;attempt < 2; attempt++) {
+    try {
+      return await writeDataDirLock(lockPath, nonce);
+    } catch (error) {
+      if (error.code !== "EEXIST")
+        throw error;
+      const owner = await readLockOwner(lockPath);
+      if (owner && isProcessAlive(owner.pid))
+        throw lockInUseError(absoluteDataDir, owner.pid);
+      if (!owner || attempt > 0)
+        throw unreadableLockError(lockPath);
+      await unlink(lockPath).catch((unlinkError) => {
+        if (unlinkError.code !== "ENOENT")
+          throw unlinkError;
+      });
+    }
+  }
+  throw unreadableLockError(lockPath);
+}
+async function writeDataDirLock(lockPath, nonce) {
+  const handle = await open(lockPath, "wx", 384);
+  try {
+    await handle.writeFile(`${JSON.stringify({ pid: process.pid, nonce, createdAt: new Date().toISOString() })}
+`);
+    return handle;
+  } catch (error) {
+    await handle.close().catch(() => {});
+    await unlink(lockPath).catch(() => {});
+    throw error;
+  }
+}
+function lockInUseError(dataDir, pid) {
+  return new Error(`PGlite data directory is already in use: ${dataDir} (pid ${pid})`);
+}
+function unreadableLockError(lockPath) {
+  return new Error(`PGlite data directory has an unreadable lock: ${lockPath}. Confirm no SupaCloud Lite process is using it, then remove the lock manually.`);
+}
 async function readLockOwner(lockPath) {
   try {
     const value = JSON.parse(await readFile(lockPath, "utf8"));
-    return typeof value.pid === "number" && Number.isInteger(value.pid) && typeof value.nonce === "string" ? { pid: value.pid, nonce: value.nonce } : null;
+    return typeof value.pid === "number" && Number.isInteger(value.pid) && value.pid > 0 && typeof value.nonce === "string" ? { pid: value.pid, nonce: value.nonce } : null;
   } catch {
     return null;
   }
@@ -3137,6 +3526,9 @@ class Database {
   exec(sql) {
     return this.engine.exec(sql);
   }
+  transaction(fn) {
+    return this.engine.transaction((tx) => fn((sql, params) => tx.query(sql, params)));
+  }
   async withContext(ctx, fn) {
     return this.engine.transaction(async (tx) => {
       await tx.query(`select set_config('role', $1, true),
@@ -6905,6 +7297,7 @@ class RetentionService {
     await this.run(`delete from auth.one_time_tokens where expires_at < now()`);
     await this.run(`delete from auth.mfa_challenges where expires_at < now()`);
     await this.run(`delete from auth.flow_state where expires_at < now()`);
+    await this.run(`delete from public.supacloud_pgredis_kv where expires_at <= now()`);
     if (this.refreshTokenDays > 0) {
       const cutoff = new Date(now.getTime() - this.refreshTokenDays * DAY_MS).toISOString();
       await this.run(`delete from auth.refresh_tokens where revoked = true and updated_at < $1`, [cutoff]);
@@ -7388,11 +7781,13 @@ async function createBackend(config = {}) {
   } catch (e) {
     await failStartup(e);
   }
+  const pgredis = await PgredisCache.create(db).catch(failStartup);
   const now = Math.floor(Date.now() / 1000);
   const tenYears = 10 * 365 * 24 * 3600;
   const anonKey = await signJwt({ iss: "supabase", ref: "local", role: "anon", iat: now, exp: now + tenYears }, jwtSecret);
   const serviceRoleKey = await signJwt({ iss: "supabase", ref: "local", role: "service_role", iat: now, exp: now + tenYears }, jwtSecret);
-  const rest = new RestHandler(db, { exposedSchemas: config.dbSchemas, maxRows: config.maxRows });
+  const exposedSchemas = [...new Set(config.dbSchemas ?? ["public", "pgmq_public"])];
+  const rest = new RestHandler(db, { exposedSchemas, maxRows: config.maxRows });
   const exposed = isNetworkExposed(config.host);
   const inbox = config.mailer || exposed ? null : new InboxMailer((msg) => log(config.logMailBody ? `[mail] to=${msg.to} subject="${msg.subject}"
 ${msg.text}` : `[mail] to=${msg.to} subject="${msg.subject}"`));
@@ -7453,7 +7848,12 @@ ${msg.text}` : `[mail] to=${msg.to} subject="${msg.subject}"`));
     ...config.functionEnv ?? {}
   };
   installDenoShim();
-  const functions = new FunctionsHandler(fnMap, fnEnv);
+  try {
+    installPgredisShim();
+  } catch (error) {
+    await failStartup(error);
+  }
+  const functions = new FunctionsHandler(fnMap, fnEnv, pgredis);
   async function resolveContext(req, url) {
     const authz = req.headers.get("authorization");
     const bearer = authz?.toLowerCase().startsWith("bearer ") ? authz.slice(7) : null;
@@ -8736,6 +9136,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 +9532,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 +9552,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 +9566,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 +9611,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 +9627,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);
@@ -8889,8 +9686,7 @@ Use --service-role to print the privileged key.`);
   Run "supacloud-lite keys" for the anon key.
   Run "supacloud-lite keys --service-role" only when privileged access is required.
 `);
-  await waitForShutdown();
-  await project.close();
+  await waitForShutdown(() => project.close());
 }
 async function runDbCommand(options) {
   const subcommand = options.positionals[0];
@@ -8901,8 +9697,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 +9708,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 +9721,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 +9733,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 +9744,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".');
@@ -8962,11 +9815,15 @@ function timestamp() {
   return new Date().toISOString().replace(/[-:T]/g, "").slice(0, 14);
 }
 function quietLog() {}
-async function waitForShutdown() {
-  await new Promise((resolveShutdown) => {
-    const stop = () => resolveShutdown();
-    process.once("SIGINT", stop);
-    process.once("SIGTERM", stop);
+function waitForShutdown(closeProject) {
+  return new Promise((resolveShutdown, rejectShutdown) => {
+    const closeOnSignal = () => {
+      process.off("SIGINT", closeOnSignal);
+      process.off("SIGTERM", closeOnSignal);
+      closeProject().then(resolveShutdown, rejectShutdown);
+    };
+    process.once("SIGINT", closeOnSignal);
+    process.once("SIGTERM", closeOnSignal);
   });
 }
 function printHelp() {
@@ -8984,6 +9841,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 +9861,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) {