{"slug":"api-baas-turso","title":"api-baas-turso","summary":"Edge-hosted SQLite database with libSQL driver and embedded replicas","platform":"Claude","tags":[],"authorName":"LLM Mart","authorSlug":"llm-mart","score":0,"source":"github","price":null,"verified":false,"createdAt":"2026-09-29T15:27:54.422316Z","repo":{"url":"https://github.com/agents-inc/skills","stars":26,"forks":8,"license":"MIT","updatedAt":"2026-10-27T00:00:49Z"},"bodyHtml":"<hr>\n<h2>name: api-baas-turso\ndescription: Edge-hosted SQLite database with libSQL driver and embedded replicas</h2>\n<h1>Turso / libSQL Patterns</h1>\n<blockquote>\n<p><strong>Quick Guide:</strong> Use <code>@libsql/client</code> for all Turso database access. Use <code>execute()</code> for single queries, <code>batch()</code> for atomic multi-statement operations (preferred over interactive transactions), and <code>transaction()</code> only when subsequent queries depend on prior results. For edge/serverless runtimes without filesystem access, import from <code>@libsql/client/web</code>. For zero-latency reads, configure embedded replicas with a local file URL + <code>syncUrl</code>. All writes are forwarded to the primary -- design for 15-50ms write latency. Turso is SQLite under the hood: single-writer model, no <code>ALTER TABLE ... ADD CONSTRAINT</code>, no stored procedures.</p>\n</blockquote>\n<hr>\n<p>&lt;critical_requirements&gt;</p>\n<h2>CRITICAL: Before Using This Skill</h2>\n<blockquote>\n<p><strong>All code must follow project conventions in CLAUDE.md</strong> (kebab-case, named exports, import ordering, <code>import type</code>, named constants)</p>\n</blockquote>\n<p><strong>(You MUST use <code>batch()</code> with a transaction mode for multi-statement atomic operations -- it is faster and safer than interactive <code>transaction()</code> because it executes in a single round trip)</strong></p>\n<p><strong>(You MUST import from <code>@libsql/client/web</code> in edge/serverless runtimes that lack filesystem access (Cloudflare Workers, Vercel Edge Functions) -- the base <code>@libsql/client</code> import pulls in native bindings that fail in these environments)</strong></p>\n<p><strong>(You MUST specify a transaction mode (<code>\"write\"</code>, <code>\"read\"</code>, or <code>\"deferred\"</code>) as the second argument to <code>batch()</code> and <code>transaction()</code> -- the default is <code>\"deferred\"</code>, which silently fails to acquire a write lock for INSERT/UPDATE/DELETE)</strong></p>\n<p><strong>(You MUST call <code>client.close()</code> when the client is no longer needed in short-lived processes -- open clients hold connections and file handles)</strong></p>\n<p><strong>(You MUST NOT access the local embedded replica database file directly while the client is running -- concurrent access causes data corruption)</strong></p>\n<p>&lt;/critical_requirements&gt;</p>\n<hr>\n<p><strong>Auto-detection:</strong> Turso, libSQL, @libsql/client, createClient, turso.io, embedded replica, syncUrl, syncInterval, turso db, turso group, libsql, .turso.io, TURSO_DATABASE_URL, TURSO_AUTH_TOKEN</p>\n<p><strong>When to use:</strong></p>\n<ul>\n<li>Querying a Turso-hosted SQLite database from any runtime (Node.js, edge, serverless)</li>\n<li>Setting up embedded replicas for zero-latency local reads synced from a remote primary</li>\n<li>Multi-tenant SaaS with database-per-tenant (Turso supports millions of databases)</li>\n<li>Serverless/edge functions needing a database without connection pooling complexity</li>\n<li>Running atomic multi-statement operations with <code>batch()</code> or interactive <code>transaction()</code></li>\n<li>Managing database groups and multi-region placement via the Turso CLI</li>\n</ul>\n<p><strong>When NOT to use:</strong></p>\n<ul>\n<li>Write-heavy workloads requiring strong multi-writer consistency (Turso is single-writer, writes forwarded to primary)</li>\n<li>Complex relational queries needing PostgreSQL features (CTEs with mutating subqueries, stored procedures, advanced constraints)</li>\n<li>Complex distributed transactions across multiple databases</li>\n<li>Large analytical datasets (SQLite row-size and concurrency limitations apply)</li>\n</ul>\n<p><strong>Detailed Resources:</strong></p>\n<ul>\n<li><a href=\"examples/core.md\">examples/core.md</a> -- Client setup, execute, batch, transactions, import paths</li>\n<li><a href=\"examples/embedded-replicas.md\">examples/embedded-replicas.md</a> -- Local replicas, sync, offline mode, encryption</li>\n<li><a href=\"reference.md\">reference.md</a> -- Decision frameworks, type definitions, CLI commands, lookup tables</li>\n</ul>\n<hr>\n\n<hr>\n\n<hr>\n<p>&lt;decision_framework&gt;</p>\n<h2>Decision Framework</h2>\n<h3>batch() vs transaction()</h3>\n<pre><code>Are all SQL statements known upfront (no conditional logic between them)?\n+-- YES --&gt; Use batch() (single round trip, implicit transaction, preferred)\n+-- NO  --&gt; Do later statements depend on results of earlier statements?\n    +-- YES --&gt; Use transaction() (interactive, multiple round trips, holds lock)\n    +-- NO  --&gt; Use batch()\n</code></pre>\n<h3>Import Path Selection</h3>\n<pre><code>What runtime environment?\n+-- Node.js / Bun / Deno / VM / container\n|   +-- Need embedded replicas (local file)?\n|   |   +-- YES --&gt; @libsql/client with file: URL + syncUrl\n|   |   +-- NO  --&gt; @libsql/client with libsql:// URL\n+-- Cloudflare Workers / Vercel Edge / browser / serverless without filesystem\n    +-- @libsql/client/web (remote connections only, no file: URLs)\n</code></pre>\n<h3>Embedded Replica vs Remote-Only</h3>\n<pre><code>Is the process long-lived with filesystem access?\n+-- YES --&gt; Do you need sub-millisecond read latency?\n|   +-- YES --&gt; Embedded replica (file: URL + syncUrl)\n|   +-- NO  --&gt; Remote-only is simpler (libsql:// URL)\n+-- NO (serverless, edge, short-lived)\n    +-- Remote-only (@libsql/client/web, libsql:// URL)\n</code></pre>\n<h3>Transaction Mode Selection</h3>\n<pre><code>What operations will the batch/transaction perform?\n+-- Only SELECT queries --&gt; \"read\" (allows parallel execution on replicas)\n+-- Any INSERT / UPDATE / DELETE --&gt; \"write\" (acquires exclusive lock)\n+-- Unsure at call time --&gt; \"deferred\" (starts read, escalates if needed)\n</code></pre>\n<p>&lt;/decision_framework&gt;</p>\n<hr>\n<p>&lt;red_flags&gt;</p>\n<h2>RED FLAGS</h2>\n<p><strong>High Priority Issues:</strong></p>\n<ul>\n<li><strong>Missing transaction mode in <code>batch()</code>/<code>transaction()</code></strong> -- Omitting the second argument defaults to <code>\"deferred\"</code>, which starts read-only and may silently fail to acquire a write lock for INSERT/UPDATE/DELETE. Always specify the mode explicitly.</li>\n<li><strong>Using <code>@libsql/client</code> in edge runtimes</strong> -- The base package bundles native SQLite bindings that fail in Cloudflare Workers, Vercel Edge Functions, and similar environments. Use <code>@libsql/client/web</code> instead.</li>\n<li><strong>String interpolation in SQL</strong> -- <code>execute(\\</code>SELECT * FROM users WHERE id = '$'`)<code>is a SQL injection vulnerability. Always use parameterized queries with</code>args`.</li>\n<li><strong>Accessing embedded replica file directly</strong> -- Opening the local <code>.db</code> file with another SQLite client while the libSQL client is running causes data corruption. Only access through the client.</li>\n</ul>\n<p><strong>Medium Priority Issues:</strong></p>\n<ul>\n<li><strong>Using <code>transaction()</code> when <code>batch()</code> suffices</strong> -- Interactive transactions hold a database lock with a 5-second timeout, require multiple round trips, and block other writers. Use <code>batch()</code> for predetermined statement sets.</li>\n<li><strong>Not calling <code>client.close()</code></strong> -- In short-lived processes (CLI scripts, test teardown), forgetting to close the client leaves connections and file handles open.</li>\n<li><strong>Ignoring write latency with embedded replicas</strong> -- Reads are microseconds (local), but writes are 15-50ms (forwarded to remote primary). Design accordingly -- avoid tight write loops.</li>\n<li><strong>Setting <code>syncInterval</code> too low</strong> -- Each sync pulls all changed frames (4KB each). Sub-second intervals on write-heavy databases generate significant network and I/O overhead.</li>\n</ul>\n<p><strong>Common Mistakes:</strong></p>\n<ul>\n<li><strong>Wrong package name</strong> -- The package is <code>@libsql/client</code>, not <code>libsql-client</code>, <code>@turso/client</code>, or <code>turso-client</code>.</li>\n<li><strong>Named parameter prefix in args object</strong> -- Args use bare names: <code>{ name: \"Alice\" }</code> matches <code>:name</code>, <code>@name</code>, and <code>$name</code> in SQL. Do not include the prefix: <code>{ \":name\": \"Alice\" }</code> will not match.</li>\n<li><strong>Expecting <code>lastInsertRowid</code> to be a number</strong> -- It is <code>bigint | undefined</code>. If you need a number, explicitly convert: <code>Number(result.lastInsertRowid)</code>, but be aware of precision loss for very large rowids.</li>\n<li><strong>Using <code>executeMultiple()</code> for atomic operations</strong> -- <code>executeMultiple()</code> runs raw SQL text (semicolon-separated) with no parameterization and no implicit transaction. Use <code>batch()</code> for atomic parameterized operations.</li>\n</ul>\n<p><strong>Gotchas &amp; Edge Cases:</strong></p>\n<ul>\n<li><strong><code>batch()</code> statements share a transaction but are NOT parallel</strong> -- They execute sequentially. <code>last_insert_rowid()</code> in a later statement reflects the previous statement's insert.</li>\n<li><strong><code>transaction()</code> has a 5-second idle timeout</strong> -- If no statement is executed within 5 seconds after the last one, the transaction is automatically rolled back. This matters on high-latency connections.</li>\n<li><strong>Embedded replica <code>sync()</code> is not atomic with reads</strong> -- If you read immediately after <code>sync()</code>, another sync could start. The client handles this internally, but be aware that <code>syncInterval</code> syncs happen in the background.</li>\n<li><strong>Frame-based sync overhead</strong> -- Embedded replica sync operates in 4KB frames. A 1-byte write still transfers a full 4KB frame. B-tree splits and WAL checkpoint operations can trigger unexpectedly large sync payloads.</li>\n<li><strong><code>intMode</code> affects how SQLite integers are returned</strong> -- Default is <code>\"number\"</code>, which loses precision for integers &gt; 2^53. Use <code>\"bigint\"</code> for large IDs or counters, or <code>\"string\"</code> for universal safety.</li>\n<li><strong>SQLite type affinity</strong> -- Turso is SQLite. A <code>TEXT</code> column will happily store an integer without error. There is no strict type enforcement unless you use <code>STRICT</code> tables.</li>\n<li><strong>No <code>ALTER TABLE ... ADD CONSTRAINT</code></strong> -- SQLite (and Turso) do not support adding constraints after table creation. You must recreate the table.</li>\n<li><strong>Single-writer model</strong> -- Only one write transaction can execute at a time across all clients. Concurrent write attempts queue behind the current writer. This is fundamental to SQLite/libSQL, not a Turso limitation.</li>\n</ul>\n<p>&lt;/red_flags&gt;</p>\n<hr>\n<p>&lt;critical_reminders&gt;</p>\n<h2>CRITICAL REMINDERS</h2>\n<blockquote>\n<p><strong>All code must follow project conventions in CLAUDE.md</strong> (kebab-case, named exports, import ordering, <code>import type</code>, named constants)</p>\n</blockquote>\n<p><strong>(You MUST use <code>batch()</code> with a transaction mode for multi-statement atomic operations -- it is faster and safer than interactive <code>transaction()</code> because it executes in a single round trip)</strong></p>\n<p><strong>(You MUST import from <code>@libsql/client/web</code> in edge/serverless runtimes that lack filesystem access (Cloudflare Workers, Vercel Edge Functions) -- the base <code>@libsql/client</code> import pulls in native bindings that fail in these environments)</strong></p>\n<p><strong>(You MUST specify a transaction mode (<code>\"write\"</code>, <code>\"read\"</code>, or <code>\"deferred\"</code>) as the second argument to <code>batch()</code> and <code>transaction()</code> -- the default is <code>\"deferred\"</code>, which silently fails to acquire a write lock for INSERT/UPDATE/DELETE)</strong></p>\n<p><strong>(You MUST call <code>client.close()</code> when the client is no longer needed in short-lived processes -- open clients hold connections and file handles)</strong></p>\n<p><strong>(You MUST NOT access the local embedded replica database file directly while the client is running -- concurrent access causes data corruption)</strong></p>\n<p><strong>Failure to follow these rules will cause data corruption, runtime crashes in edge environments, or silent data inconsistency.</strong></p>\n<p>&lt;/critical_reminders&gt;</p>\n","files":[{"path":"examples/core.md","sizeBytes":9581,"isText":true},{"path":"examples/embedded-replicas.md","sizeBytes":7330,"isText":true},{"path":"reference.md","sizeBytes":7796,"isText":true},{"path":"SKILL.md","sizeBytes":16602,"isText":true}],"reviewScore":null,"reviewSummary":null,"trust":{"provenance":"trusted-source-unreviewed","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow.","bodySource":null},"bodyLocked":false,"purchaseUrl":null,"sourceUrl":null,"report":{"provenance":"trusted-source-unreviewed","screen":{"ran":true,"outcome":"clean","suspicious":0,"notes":0,"hiddenCharacters":false},"virusScan":{"engine":"clamav","status":"clean","scannedAt":"2026-10-24T18:58:34.959434Z","sha256":"A4050A24B6096BBEC611B8D070488626F21EB3568A88D5E8FFB05A05B843FBDE","sizeBytes":14910},"review":null,"source":{"repositoryUrl":"https://github.com/agents-inc/skills","path":"dist/plugins/api-baas-turso/skills/api-baas-turso","license":"MIT","commit":"845a1f2833eedc494bb82e3172710c06cab547a1","subtreeSha":"C50C0B4B8821F0889217AE0F5D89DC1BFAAD382FA22A017D88B8A68579021F3D","lastSyncedAt":"2026-11-14T00:39:21.716782Z"},"reviewedAt":"2026-10-24T19:03:02.74927Z","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow."},"install":[{"target":"skills-cli","command":"npx skills add https://github.com/agents-inc/skills/tree/main/dist/plugins/api-baas-turso/skills/api-baas-turso"},{"target":"claude-code","command":"claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install agents-inc-skills@llmmart"},{"target":"git","command":"git clone https://github.com/agents-inc/skills.git"}]}