The Complete Production SOP: How to Deploy and Run libSQL & Turso Edge Distributed SQLite in Autonomous AI Agents

---
name: "sqlite-libsql-turso-distributed"
description: "Deploy distributed, embedded SQLite replicas worldwide with sub-millisecond edge latency."
metadata:
  author: "Turso Database"
  version: "1.0.0"
  runtime_compatibility:
    - "codex"
    - "claude-code"
    - "cursor"
    - "windsurf"
triggers:
  - "connect to turso libsql"
  - "configure libsql embedded replica"
  - "sync local edge sqlite replica"
permissions:
  fs_read: true
  fs_write: "workspace"
  shell_exec: false
  net_access: false
---

import { createClient } from '@libsql/client';
import path from 'node:path';

const isProd = process.env.NODE_ENV === 'production';

export const db = createClient({
  url: process.env.LOCAL_REPLICA_URL || `file:${path.resolve(process.cwd(), 'data/replica.db')}`,
  syncUrl: process.env.TURSO_DATABASE_URL,
  authToken: process.env.TURSO_AUTH_TOKEN,
  syncInterval: isProd ? 60000 : undefined, // periodic background sync
});

export async function syncDatabase() {
  try {
    const info = await db.sync();
    console.log(`[libSQL] Synchronized replica. Frame count: ${info.framesSynced}`);
  } catch (error) {
    console.error('[libSQL] Replica sync failed:', error);
    throw error;
  }
}

import { db, syncDatabase } from '../lib/tursoClient';

export async function getUserById(id: string) {
  // Sub-millisecond read directly from the embedded local file
  const result = await db.execute({
    sql: 'SELECT id, email, created_at FROM users WHERE id = ?',
    args: [id],
  });
  return result.rows[0] || null;
}

export async function createUser(id: string, email: string) {
  // Write mutation automatically forwarded to the primary Turso instance
  await db.execute({
    sql: 'INSERT INTO users (id, email, created_at) VALUES (?, ?, unixepoch())',
    args: [id, email],
  });
  // Pull latest committed frames back to embedded replica immediately
  await syncDatabase();
}

#!/usr/bin/env bash
set -euo pipefail

if [ ! -f .env.local ]; then
  echo "Error: .env.local not found"
  exit 1
fi

echo "Validating libSQL client build..."
npx tsc --noEmit

echo "Executing live embedded replica test query..."
node --import tsx/esm -e "
import { db, syncDatabase } from './src/lib/tursoClient';
await syncDatabase();
const res = await db.execute('SELECT 1 as test');
if (res.rows[0].test !== 1) process.exit(1);
console.log('PASS: Embedded replica synchronized and functional');
"
echo "Quality gate passed."