step 5

server/index.js

@@ -11,9 +11,9 @@ import fs from 'fs';
 import { registerFeedbackRoutes } from './handleFeedback.js';
 import { SUPABASE_URL, SUPABASE_ANON_KEY } from './config.js';
 import { safeSend } from './helpers.js';
-import { initializePostgresStorage } from './postgres.js';
-import { POSTGRES_STORAGE_DIR, refreshStorageMode } from './dataPaths.js';
-import { migrateLegacyDataToPostgres } from './postgresMigration.js';
+import { getPostgresBackendType, initializePostgresStorage } from './postgres.js';
+import { POSTGRES_STORAGE_DB_DIR, POSTGRES_STORAGE_DIR, refreshStorageMode } from './dataPaths.js';
+import { materializeEmbeddedPostgresStorage, migrateLegacyDataToPostgres } from './postgresMigration.js';
 import { loadStoredSHA, saveStoredSHA } from './versionStore.js';
 
 export { SUPABASE_URL, SUPABASE_ANON_KEY };
@@ -63,21 +63,29 @@ async function ensureStorageBackendReady() {
   const autoBootstrap = process.env.POSTGRES_AUTO_BOOTSTRAP !== '0';
 
   if (mode !== 'postgres' && autoBootstrap) {
-    console.log(`[storage] PostgreSQL marker folder missing at ${POSTGRES_STORAGE_DIR}; starting automatic bootstrap.`);
+    console.log(`[storage] PostgreSQL storage folder missing at ${POSTGRES_STORAGE_DIR}; starting automatic bootstrap.`);
     const report = await migrateLegacyDataToPostgres({ skipIfFolderExists: true });
     mode = refreshStorageMode();
     if (report?.skipped) {
-      console.log(`[storage] PostgreSQL marker folder became available during bootstrap check.`);
+      console.log(`[storage] PostgreSQL storage folder became available during bootstrap check.`);
     } else {
       console.log(`[storage] automatic PostgreSQL bootstrap ${report.status} at ${POSTGRES_STORAGE_DIR}`);
     }
   }
 
   if (mode === 'postgres') {
+    const materialized = await materializeEmbeddedPostgresStorage();
+    if (materialized?.upgraded && materialized?.report) {
+      console.log(`[storage] materialized embedded PostgreSQL database at ${POSTGRES_STORAGE_DB_DIR}`);
+    }
     await initializePostgresStorage();
   }
 
-  console.log(`[storage] mode=${mode} target=${mode === 'postgres' ? POSTGRES_STORAGE_DIR : '/data'}`);
+  const backend = mode === 'postgres' ? getPostgresBackendType() : 'legacy';
+  const target = mode === 'postgres'
+    ? (backend === 'embedded' ? POSTGRES_STORAGE_DB_DIR : POSTGRES_STORAGE_DIR)
+    : '/data';
+  console.log(`[storage] mode=${mode}${mode === 'postgres' ? ` backend=${backend}` : ''} target=${target}`);
   return mode;
 }
 

server/postgres.js

@@ -1,3 +1,6 @@
+import { EventEmitter } from 'events';
+import fs from 'fs/promises';
+import { PGlite } from '@electric-sql/pglite';
 import { Pool } from 'pg';
 import {
   createLookupHash,
@@ -8,11 +11,19 @@ import {
   packEncryptedBuffer,
   unpackEncryptedBuffer,
 } from './cryptoUtils.js';
-import { isPostgresStorageMode, POSTGRES_STORAGE_DIR, STORAGE_MODE } from './dataPaths.js';
+import {
+  hasEmbeddedPostgresDatabaseFiles,
+  isPostgresStorageMode,
+  POSTGRES_STORAGE_DB_DIR,
+  POSTGRES_STORAGE_DIR,
+  readPostgresStorageManifest,
+  STORAGE_MODE,
+} from './dataPaths.js';
 import { APP_SCHEMA_NAME, POSTGRES_SCHEMA_SQL } from './postgresSchema.js';
 
 let poolInstance = null;
 let initPromise = null;
+let activeBackendType = null;
 const configuredClients = new WeakSet();
 const patchedPools = new WeakSet();
 
@@ -46,7 +57,98 @@ export function getSetSearchPathSql() {
   return `SET search_path TO "${getValidatedSchemaName()}", public`;
 }
 
-export function buildPoolConfig() {
+export function hasExternalPostgresConfig() {
+  const connectionString = process.env.DATABASE_URL || process.env.POSTGRES_URL || '';
+  if (connectionString) return true;
+  const { PGHOST, PGUSER, PGDATABASE } = process.env;
+  return !!(PGHOST && PGUSER && PGDATABASE);
+}
+
+function getRequestedBackendType() {
+  const raw = String(process.env.POSTGRES_STORAGE_BACKEND || '').trim().toLowerCase();
+  return raw === 'embedded' || raw === 'external' ? raw : null;
+}
+
+function getManifestBackendType() {
+  const raw = String(readPostgresStorageManifest()?.backend || '').trim().toLowerCase();
+  return raw === 'embedded' || raw === 'external' ? raw : null;
+}
+
+function resolveBackendType(explicit = null) {
+  if (explicit === 'embedded' || explicit === 'external') return explicit;
+  const requested = getRequestedBackendType();
+  if (requested) return requested;
+  const manifestBackend = getManifestBackendType();
+  if (manifestBackend) return manifestBackend;
+  if (hasEmbeddedPostgresDatabaseFiles()) return 'embedded';
+  if (hasExternalPostgresConfig()) return 'external';
+  return 'embedded';
+}
+
+function normalizeQueryResult(result = {}) {
+  const rows = Array.isArray(result.rows) ? result.rows : [];
+  const affectedRows = Number(result.affectedRows || 0);
+  return {
+    ...result,
+    rows,
+    fields: Array.isArray(result.fields) ? result.fields : [],
+    rowCount: rows.length || affectedRows || 0,
+  };
+}
+
+class EmbeddedPostgresClient {
+  constructor(executor) {
+    this.executor = executor;
+    this.embedded = true;
+  }
+
+  async query(text, params = []) {
+    return normalizeQueryResult(await this.executor.query(text, params));
+  }
+
+  async exec(text) {
+    const results = await this.executor.exec(text);
+    return Array.isArray(results) ? results.map(normalizeQueryResult) : [];
+  }
+
+  release() {}
+}
+
+class EmbeddedPostgresPool extends EventEmitter {
+  constructor(db, dataDir) {
+    super();
+    this.db = db;
+    this.dataDir = dataDir;
+    this.embedded = true;
+  }
+
+  async connect() {
+    return new EmbeddedPostgresClient(this.db);
+  }
+
+  async query(text, params = []) {
+    return normalizeQueryResult(await this.db.query(text, params));
+  }
+
+  async exec(text) {
+    const results = await this.db.exec(text);
+    return Array.isArray(results) ? results.map(normalizeQueryResult) : [];
+  }
+
+  async transaction(fn) {
+    return this.db.transaction(async (tx) => fn(new EmbeddedPostgresClient(tx)));
+  }
+
+  async end() {
+    await this.db.close();
+  }
+}
+
+function resolveEmbeddedDataDir(dataDir = null) {
+  return dataDir || POSTGRES_STORAGE_DB_DIR;
+}
+
+function buildExternalPoolConfig() {
   const connectionString = process.env.DATABASE_URL || process.env.POSTGRES_URL || '';
   const ssl = resolveSslConfig();
   if (connectionString) {
@@ -56,7 +158,7 @@ export function buildPoolConfig() {
   const { PGHOST, PGPORT, PGUSER, PGPASSWORD, PGDATABASE } = process.env;
   if (!PGHOST || !PGUSER || !PGDATABASE) {
     throw new Error(
-      `PostgreSQL bootstrap/storage for ${POSTGRES_STORAGE_DIR} requires a database connection. Set DATABASE_URL or PGHOST/PGUSER/PGDATABASE.`
+      `PostgreSQL storage for ${POSTGRES_STORAGE_DIR} requires either an embedded database directory or a database connection. Set POSTGRES_STORAGE_BACKEND=embedded to use the local folder, or configure DATABASE_URL / PGHOST / PGUSER / PGDATABASE for an external server.`
     );
   }
 
@@ -70,15 +172,31 @@ export function buildPoolConfig() {
   };
 }
 
+export function buildPoolConfig(options = {}) {
+  const backend = resolveBackendType(options.backend);
+  if (backend === 'embedded') {
+    return {
+      backend,
+      dataDir: resolveEmbeddedDataDir(options.dataDir),
+    };
+  }
+  return {
+    backend,
+    ...buildExternalPoolConfig(),
+  };
+}
+
 function attachPoolErrorHandler(pool) {
-  pool.on('error', (err) => {
-    console.error('PostgreSQL pool error:', err);
-  });
+  if (typeof pool.on === 'function') {
+    pool.on('error', (err) => {
+      console.error('PostgreSQL pool error:', err);
+    });
+  }
   return pool;
 }
 
 function patchPoolClientSetup(pool) {
-  if (patchedPools.has(pool)) return pool;
+  if (pool?.embedded || patchedPools.has(pool)) return pool;
 
   const originalConnect = pool.connect.bind(pool);
   const originalQuery = pool.query.bind(pool);
@@ -108,14 +226,31 @@ function patchPoolClientSetup(pool) {
   return pool;
 }
 
-export async function createRawPostgresPool() {
-  const pool = new Pool(buildPoolConfig());
+async function createEmbeddedPostgresPool({ dataDir } = {}) {
+  const resolvedDataDir = resolveEmbeddedDataDir(dataDir);
+  await fs.mkdir(resolvedDataDir, { recursive: true });
+  const db = await PGlite.create(resolvedDataDir);
+  await db.query(getCreateSchemaSql());
+  await db.query(getSetSearchPathSql());
+  return attachPoolErrorHandler(new EmbeddedPostgresPool(db, resolvedDataDir));
+}
+
+export function getPostgresBackendType() {
+  return activeBackendType || resolveBackendType();
+}
+
+export async function createRawPostgresPool(options = {}) {
+  const config = buildPoolConfig(options);
+  if (config.backend === 'embedded') {
+    return createEmbeddedPostgresPool({ dataDir: config.dataDir });
+  }
+  const pool = new Pool(config);
   attachPoolErrorHandler(pool);
   return patchPoolClientSetup(pool);
 }
 
 export async function preparePostgresClient(client) {
-  if (configuredClients.has(client)) return;
+  if (client?.embedded || configuredClients.has(client)) return;
   await client.query(getCreateSchemaSql());
   await client.query(getSetSearchPathSql());
   configuredClients.add(client);
@@ -125,7 +260,11 @@ export async function applyPostgresSchema(pool) {
   const client = await pool.connect();
   try {
     await preparePostgresClient(client);
-    await client.query(POSTGRES_SCHEMA_SQL);
+    if (typeof client.exec === 'function') {
+      await client.exec(POSTGRES_SCHEMA_SQL);
+    } else {
+      await client.query(POSTGRES_SCHEMA_SQL);
+    }
   } finally {
     client.release();
   }
@@ -135,9 +274,10 @@ async function createPool() {
   return createStandalonePostgresPool();
 }
 
-export async function createStandalonePostgresPool() {
-  const pool = await createRawPostgresPool();
+export async function createStandalonePostgresPool(options = {}) {
+  const pool = await createRawPostgresPool(options);
   await applyPostgresSchema(pool);
+  activeBackendType = pool?.embedded ? 'embedded' : 'external';
   return pool;
 }
 
@@ -146,6 +286,7 @@ export async function initializePostgresStorage() {
   if (!initPromise) {
     initPromise = createPool().then((pool) => {
       poolInstance = pool;
+      activeBackendType = pool?.embedded ? 'embedded' : 'external';
       return pool;
     });
   }
@@ -178,6 +319,13 @@ export async function withPgClient(fn) {
 }
 
 export async function withPgTransaction(fn) {
+  const pool = await getPostgresPool();
+  if (typeof pool.transaction === 'function') {
+    return pool.transaction(async (client) => {
+      await preparePostgresClient(client);
+      return fn(client);
+    });
+  }
   return withPgClient(async (client) => {
     await client.query('BEGIN');
     try {

server/postgresMigration.js

@@ -1,19 +1,23 @@
 import fs from 'fs/promises';
 import path from 'path';
 import { createClient } from '@supabase/supabase-js';
-import { loadEncryptedJson } from './cryptoUtils.js';
+import { loadEncryptedJson, readEncryptedFile } from './cryptoUtils.js';
 import {
   POSTGRES_STORAGE_DIR,
+  POSTGRES_STORAGE_DB_DIR,
   POSTGRES_STORAGE_MANIFEST,
   DATA_ROOT,
+  readPostgresStorageManifest,
   refreshStorageMode,
 } from './dataPaths.js';
 import {
   applyPostgresSchema,
   createRawPostgresPool,
+  encryptBinaryPayload,
   encryptJsonPayload,
   getCreateSchemaSql,
   getDropSchemaSql,
+  hasExternalPostgresConfig,
   getPostgresSchemaName,
   getSetSearchPathSql,
   makeLookupToken,
@@ -106,6 +110,121 @@ function webUsageAad(key, day) {
   return `web-search-usage:${key}:${day}`;
 }
 
+function mediaBlobAad(entry) {
+  return `media:${entry.id}:${entry.ownerType}:${entry.ownerId}`;
+}
+
+function getTempStorageDir() {
+  return `${POSTGRES_STORAGE_DIR}.tmp`;
+}
+
+function getTempStorageDbDir() {
+  return path.join(getTempStorageDir(), path.basename(POSTGRES_STORAGE_DB_DIR));
+}
+
+function buildStorageManifest(report, backend = 'embedded') {
+  return {
+    formatVersion: 2,
+    createdAt: report.completedAt,
+    updatedAt: report.completedAt,
+    storageMode: 'postgres',
+    backend,
+    dbDir: path.basename(POSTGRES_STORAGE_DB_DIR),
+    status: report.status,
+    pending: report.pending,
+  };
+}
+
+const SQL_TABLE_COPY_PLANS = [
+  {
+    table: 'app_versions',
+    reportKey: 'copiedAppVersions',
+    columns: ['public_url_lookup', 'updated_at', 'payload'],
+  },
+  {
+    table: 'guest_state',
+    reportKey: 'copiedGuestStateRows',
+    columns: ['owner_lookup', 'expires_at', 'updated_at', 'payload'],
+  },
+  {
+    table: 'chat_sessions',
+    reportKey: 'copiedChatSessions',
+    columns: ['id', 'scope_type', 'owner_lookup', 'created_at', 'updated_at', 'expires_at', 'payload'],
+  },
+  {
+    table: 'session_shares',
+    reportKey: 'copiedSessionShares',
+    columns: ['id', 'token_lookup', 'owner_lookup', 'created_at', 'payload'],
+  },
+  {
+    table: 'deleted_chats',
+    reportKey: 'copiedDeletedChats',
+    columns: ['id', 'owner_lookup', 'purge_at', 'deleted_at', 'payload'],
+  },
+  {
+    table: 'memories',
+    reportKey: 'copiedMemories',
+    columns: ['id', 'owner_lookup', 'created_at', 'updated_at', 'payload'],
+  },
+  {
+    table: 'media_entries',
+    reportKey: 'copiedMediaEntries',
+    columns: [
+      'id',
+      'owner_lookup',
+      'parent_id',
+      'entry_type',
+      'updated_at',
+      'created_at',
+      'trashed_at',
+      'purge_at',
+      'expires_at',
+      'size_bytes',
+      'payload',
+    ],
+  },
+  {
+    table: 'media_blobs',
+    reportKey: 'copiedMediaBlobs',
+    columns: ['entry_id', 'updated_at', 'payload'],
+  },
+  {
+    table: 'system_prompts',
+    reportKey: 'copiedSystemPrompts',
+    columns: ['owner_lookup', 'updated_at', 'payload'],
+  },
+  {
+    table: 'feedback_tickets',
+    reportKey: 'copiedFeedbackTickets',
+    columns: ['id', 'status', 'submitted_at', 'payload'],
+  },
+  {
+    table: 'guest_request_counters',
+    reportKey: 'copiedGuestRequestCounters',
+    columns: ['key_lookup', 'expires_at', 'updated_at', 'payload'],
+  },
+  {
+    table: 'web_search_usage',
+    reportKey: 'copiedWebSearchUsageRows',
+    columns: ['key_lookup', 'day_key', 'updated_at', 'payload'],
+  },
+  {
+    table: 'user_settings',
+    reportKey: 'copiedUserSettings',
+    columns: ['owner_lookup', 'updated_at', 'payload'],
+  },
+  {
+    table: 'user_profiles',
+    reportKey: 'copiedUserProfiles',
+    columns: ['owner_lookup', 'username_lookup', 'updated_at', 'payload'],
+  },
+  {
+    table: 'device_sessions',
+    reportKey: 'copiedDeviceSessions',
+    columns: ['token_lookup', 'user_lookup', 'active', 'created_at', 'last_seen_at', 'payload'],
+  },
+];
+
 async function fileExists(filePath) {
   try {
     await fs.access(filePath);
@@ -371,11 +490,15 @@ async function migrateMedia(pool, report) {
     if (entry.type === 'file') {
       const blobPath = path.join(MEDIA_BLOBS_DIR, `${entry.id}.bin`);
       if (await fileExists(blobPath)) {
-        const blob = await fs.readFile(blobPath);
+        const blob = await readEncryptedFile(blobPath, mediaBlobAad(entry));
         await pool.query(
           `INSERT INTO media_blobs (entry_id, updated_at, payload)
            VALUES ($1, $2, $3)`,
-          [entry.id, entry.updatedAt || entry.createdAt, blob]
+          [
+            entry.id,
+            entry.updatedAt || entry.createdAt,
+            encryptBinaryPayload(blob, mediaBlobAad(entry)),
+          ]
         );
         blobCount += 1;
       }
@@ -494,35 +617,93 @@ async function migrateSupabaseData(pool, report) {
   report.migrated.supabaseProfiles = profiles.length;
 }
 
-async function writeStorageFolder(report) {
-  const tempDir = `${POSTGRES_STORAGE_DIR}.tmp`;
-  await fs.rm(tempDir, { recursive: true, force: true });
-  await fs.mkdir(tempDir, { recursive: true });
+async function writeStorageFolder(targetDir, report, backend = 'embedded') {
+  await fs.mkdir(targetDir, { recursive: true });
   await fs.writeFile(
-    path.join(tempDir, path.basename(POSTGRES_STORAGE_MANIFEST)),
-    JSON.stringify({
-      createdAt: report.completedAt,
-      storageMode: 'postgres',
-      status: report.status,
-      pending: report.pending,
-    }, null, 2),
+    path.join(targetDir, path.basename(POSTGRES_STORAGE_MANIFEST)),
+    JSON.stringify(buildStorageManifest(report, backend), null, 2),
     'utf8'
   );
-  await fs.writeFile(path.join(tempDir, 'schema.sql'), POSTGRES_SCHEMA_SQL, 'utf8');
-  await fs.writeFile(path.join(tempDir, 'migration-report.json'), JSON.stringify(report, null, 2), 'utf8');
+  await fs.writeFile(path.join(targetDir, 'schema.sql'), POSTGRES_SCHEMA_SQL, 'utf8');
+  await fs.writeFile(path.join(targetDir, 'migration-report.json'), JSON.stringify(report, null, 2), 'utf8');
   await fs.writeFile(
-    path.join(tempDir, 'README.txt'),
+    path.join(targetDir, 'README.txt'),
     [
-      'This folder marks PostgreSQL storage as active for the backend.',
-      'The server checks for this folder on startup and uses PostgreSQL-only mode when it exists.',
+      'This folder contains the encrypted PostgreSQL storage used by the backend.',
+      `The actual embedded database files live in ./${path.basename(POSTGRES_STORAGE_DB_DIR)}/.`,
       'schema.sql contains the schema used for the migrated encrypted SQL backend.',
     ].join('\n'),
     'utf8'
   );
+}
+
+async function prepareTempEmbeddedTarget() {
+  const tempDir = getTempStorageDir();
+  await fs.rm(tempDir, { recursive: true, force: true });
+  await fs.mkdir(tempDir, { recursive: true });
+  return {
+    tempDir,
+    tempDbDir: getTempStorageDbDir(),
+  };
+}
+
+async function activateEmbeddedStorageFolder(tempDir) {
+  await fs.rm(POSTGRES_STORAGE_DIR, { recursive: true, force: true });
   await fs.rename(tempDir, POSTGRES_STORAGE_DIR);
+  refreshStorageMode();
+}
+
+function buildInsertValueSql(table, columns) {
+  return columns
+    .map((column, index) => (column === 'payload' && table !== 'media_blobs'
+      ? `$${index + 1}::jsonb`
+      : `$${index + 1}`))
+    .join(', ');
+}
+
+function normalizeCopiedSqlValue(table, column, value) {
+  if (column === 'payload' && table !== 'media_blobs' && value && typeof value === 'object' && !Buffer.isBuffer(value)) {
+    return JSON.stringify(value);
+  }
+  return value ?? null;
+}
+
+async function copySqlTable(sourcePool, targetPool, plan, report) {
+  const selectSql = `SELECT ${plan.columns.join(', ')} FROM ${plan.table}`;
+  const insertSql = `
+    INSERT INTO ${plan.table} (${plan.columns.join(', ')})
+    VALUES (${buildInsertValueSql(plan.table, plan.columns)})
+  `;
+  const { rows } = await sourcePool.query(selectSql);
+  for (const row of rows) {
+    await targetPool.query(
+      insertSql,
+      plan.columns.map((column) => normalizeCopiedSqlValue(plan.table, column, row[column]))
+    );
+  }
+  report.migrated[plan.reportKey] = rows.length;
+}
+
+async function copyExistingSqlData(sourcePool, targetPool, report) {
+  for (const plan of SQL_TABLE_COPY_PLANS) {
+    await copySqlTable(sourcePool, targetPool, plan, report);
+  }
+}
+
+async function hasMaterializedEmbeddedDatabase() {
+  try {
+    const entries = await fs.readdir(POSTGRES_STORAGE_DB_DIR);
+    return entries.length > 0;
+  } catch {
+    return false;
+  }
 }
 
-export async function migrateLegacyDataToPostgres({ skipIfFolderExists = true } = {}) {
+export async function migrateLegacyDataToPostgres({
+  skipIfFolderExists = true,
+  replaceExistingFolder = false,
+  sourceLabel = 'legacy_files',
+} = {}) {
   if (skipIfFolderExists && await fileExists(POSTGRES_STORAGE_DIR)) {
     refreshStorageMode();
     return {
@@ -534,17 +715,21 @@ export async function migrateLegacyDataToPostgres({ skipIfFolderExists = true }
     };
   }
 
-  if (!skipIfFolderExists && await fileExists(POSTGRES_STORAGE_DIR)) {
+  if (!skipIfFolderExists && !replaceExistingFolder && await fileExists(POSTGRES_STORAGE_DIR)) {
     throw new Error(`SQL storage folder already exists at ${POSTGRES_STORAGE_DIR}. Remove it before running the migration again.`);
   }
 
   await fs.mkdir(DATA_ROOT, { recursive: true });
 
-  const pool = await createRawPostgresPool();
+  const { tempDir, tempDbDir } = await prepareTempEmbeddedTarget();
+  const pool = await createRawPostgresPool({ backend: 'embedded', dataDir: tempDbDir });
   const report = {
     startedAt: nowIso(),
+    source: sourceLabel,
     targetFolder: POSTGRES_STORAGE_DIR,
+    targetDatabaseDir: POSTGRES_STORAGE_DB_DIR,
     targetSchema: getPostgresSchemaName(),
+    targetBackend: 'embedded',
     migrated: {},
     pending: [],
   };
@@ -565,13 +750,86 @@ export async function migrateLegacyDataToPostgres({ skipIfFolderExists = true }
 
     report.completedAt = nowIso();
     report.status = report.pending.length ? 'completed_with_pending_items' : 'completed';
-
-    await writeStorageFolder(report);
-    refreshStorageMode();
-    return report;
   } finally {
     await pool.end();
   }
+
+  await writeStorageFolder(tempDir, report, 'embedded');
+  await activateEmbeddedStorageFolder(tempDir);
+  return report;
+}
+
+export async function materializeEmbeddedPostgresStorage() {
+  const manifest = readPostgresStorageManifest();
+  if (!manifest) {
+    return {
+      skipped: true,
+      reason: 'manifest_missing',
+    };
+  }
+
+  if (await hasMaterializedEmbeddedDatabase()) {
+    if (manifest.backend !== 'embedded') {
+      const report = {
+        startedAt: nowIso(),
+        completedAt: nowIso(),
+        source: 'manifest_refresh',
+        targetFolder: POSTGRES_STORAGE_DIR,
+        targetDatabaseDir: POSTGRES_STORAGE_DB_DIR,
+        targetSchema: getPostgresSchemaName(),
+        targetBackend: 'embedded',
+        migrated: {},
+        pending: [],
+        status: 'completed',
+      };
+      await writeStorageFolder(POSTGRES_STORAGE_DIR, report, 'embedded');
+      refreshStorageMode();
+      return { upgraded: true, report };
+    }
+    return {
+      skipped: true,
+      reason: 'already_embedded',
+    };
+  }
+
+  if (!hasExternalPostgresConfig()) {
+    const report = await migrateLegacyDataToPostgres({
+      skipIfFolderExists: false,
+      replaceExistingFolder: true,
+      sourceLabel: 'legacy_files_upgrade',
+    });
+    return { upgraded: true, report };
+  }
+
+  const { tempDir, tempDbDir } = await prepareTempEmbeddedTarget();
+  const sourcePool = await createRawPostgresPool({ backend: 'external' });
+  const targetPool = await createRawPostgresPool({ backend: 'embedded', dataDir: tempDbDir });
+  const report = {
+    startedAt: nowIso(),
+    source: 'external_postgres',
+    previousBackend: String(manifest.backend || 'external_marker'),
+    targetFolder: POSTGRES_STORAGE_DIR,
+    targetDatabaseDir: POSTGRES_STORAGE_DB_DIR,
+    targetSchema: getPostgresSchemaName(),
+    targetBackend: 'embedded',
+    migrated: {},
+    pending: [],
+  };
+
+  try {
+    await resetBootstrapSchema(targetPool);
+    await applyPostgresSchema(targetPool);
+    await copyExistingSqlData(sourcePool, targetPool, report);
+    report.completedAt = nowIso();
+    report.status = 'completed';
+  } finally {
+    await sourcePool.end();
+    await targetPool.end();
+  }
+
+  await writeStorageFolder(tempDir, report, 'embedded');
+  await activateEmbeddedStorageFolder(tempDir);
+  return { upgraded: true, report };
 }
 
 export async function runPostgresMigrationCli() {