Home › Turso / libSQL › Turso / libSQL AGENTS.md

Turso / libSQL AGENTS.md

AGENTS.md for apps on Turso (libSQL/SQLite at the edge): client setup, embedded replicas, migrations, and SQLite rules.

AGENTS.mdTurso / libSQL

Copy AGENTS.md

How to use

Save this as AGENTS.md in your repository root, commit it, and your agent will pick it up automatically. Edit the commands to match your project.

# AGENTS.md: Turso (libSQL)

## Setup
- Client: `createClient({ url: process.env.TURSO_DATABASE_URL!, authToken: process.env.TURSO_AUTH_TOKEN })` from `@libsql/client` (`/web` in edge runtimes). Created once and reused.
- Local dev uses a file DB (`file:local.db`) or `turso dev`; tests use `:memory:` or a temp file.
- Embedded replicas (`syncUrl` + local file) for read-heavy servers; call `client.sync()` on a schedule, and remember writes go to the primary.

## SQL (it's SQLite)
- Parameterized statements only: `client.execute({ sql: "select * from users where id = ?", args: [id] })`.
- Group related writes in `client.batch([...], "write")` or an interactive `transaction("write")`; keep transactions short.
- Types: SQLite is loosely typed. Use `STRICT` tables for new schemas, `INTEGER` primary keys, ISO-8601 `TEXT` or unix `INTEGER` for times (pick one and stick to it).
- Turn on foreign keys (`PRAGMA foreign_keys = ON` if not default) and declare them.
- Index columns used in `WHERE`/`JOIN`/`ORDER BY`; check with `EXPLAIN QUERY PLAN`.
- `ALTER TABLE` is limited; complex changes use the create-copy-rename pattern in a migration.

## Migrations
Through the ORM in use (Drizzle `dialect: "turso"`, Prisma adapter) or numbered SQL files. Never run destructive SQL on the production database from the agent.

## Done
Typecheck and tests pass against a local libSQL database.