Turso

https://docs.turso.tech/
Admin
Turso is a small, efficient database built on SQLite, designed for modern applications, AI, and...
Tokens:281,681
Snippets:3,455
Trust Score:9.8
Update:1 month ago
Show doc for...
Tokens:
Raw
### AgentFS Python SDK Quick Start

Source: https://docs.turso.tech/agentfs/sdk/python

A quick start example demonstrating how to open an agent filesystem, use the key-value store, perform filesystem operations, and track tool calls.

```python
import asyncio
from agentfs_sdk import AgentFS, AgentFSOptions

async def main():
    # Open an agent filesystem
    agent = await AgentFS.open(AgentFSOptions(id='my-agent'))

    # Use key-value store
    await agent.kv.set('config', {'debug': True})
    config = await agent.kv.get('config')

    # Use filesystem
    await agent.fs.write_file('/notes.txt', 'Hello, AgentFS!')
    content = await agent.fs.read_file('/notes.txt')

    # Track tool calls
    call_id = await agent.tools.start('search', {'query': 'Python'})
    await agent.tools.success(call_id, {'results': ['result1']})

    await agent.close()

asyncio.run(main())
```

--------------------------------

### AgentFS Quick Start Example

Source: https://docs.turso.tech/agentfs/sdk/rust

Demonstrates how to open persistent or ephemeral AgentFS databases and use the core APIs for key-value storage, filesystem operations, and tool tracking.

```rust
use agentfs::{AgentFS, AgentFSOptions};
use anyhow::Result;

#[tokio::main]
async fn main() -> Result<()> {
    // Persistent storage with identifier
    let agent = AgentFS::open(AgentFSOptions::with_id("my-agent")).await?;
    // Creates: .agentfs/my-agent.db

    // Or use ephemeral in-memory database
    let ephemeral = AgentFS::open(AgentFSOptions::ephemeral()).await?;

    // Use the three main APIs
    agent.kv.set("key", "value").await?;
    agent.fs.write_file("/file.txt", b"data").await?;
    agent.tools.record(...).await?;

    Ok(())
}
```

--------------------------------

### Setup libSQL

Source: https://docs.turso.tech/sdk/c/reference

Call the setup function before using libSQL. This is a one-time setup for the library.

```c
libsql_setup((libsql_config_t){0});
```

--------------------------------

### Complete AgentFS Python Example

Source: https://docs.turso.tech/agentfs/sdk/python

This example demonstrates how to use the AgentFS Python SDK to open an agent, store configuration, write a file, track a tool call, and list created files and tool statistics. Ensure you have the agentfs_sdk installed and an agent ID available.

```python
import asyncio
import time
from agentfs_sdk import AgentFS, AgentFSOptions

async def main():
    async with await AgentFS.open(AgentFSOptions(id='demo-agent')) as agent:
        # Store configuration
        await agent.kv.set('agent:config', {
            'model': 'gpt-4',
            'temperature': 0.7
        })

        # Create a research document
        research = """
        # Research Notes

        ## Topic: AgentFS

        AgentFS provides persistent storage for AI agents.
        """

        await agent.fs.write_file('/research/agentfs.md', research)

        # Track a simulated tool call
        call_id = await agent.tools.start('web_search', {
            'query': 'AgentFS documentation'
        })

        # Simulate some work
        await asyncio.sleep(0.1)

        await agent.tools.success(call_id, {
            'results_count': 5,
            'top_result': 'https://docs.turso.tech/agentfs'
        })

        # List what we created
        files = await agent.fs.readdir('/research')
        print(f"Files: {files}")

        # Get tool stats
        stats = await agent.tools.get_stats()
        for stat in stats:
            print(f"{stat.name}: {stat.total_calls} calls")

asyncio.run(main())
```

--------------------------------

### Install @libsql/client

Source: https://docs.turso.tech/sdk/http/quickstart

Install the production-ready libSQL driver.

```bash
npm install @libsql/client
```

--------------------------------

### Create and Populate Sales Table

Source: https://docs.turso.tech/sql-reference/functions/aggregate

Initial setup for the sales table used in subsequent aggregate function examples.

```sql
CREATE TABLE sales (
    id INTEGER PRIMARY KEY,
    region TEXT,
    product TEXT,
    amount REAL,
    quantity INTEGER
);

INSERT INTO sales VALUES
    (1, 'North', 'Widget', 100.00, 5),
    (2, 'North', 'Gadget', 250.00, 2),
    (3, 'South', 'Widget', 150.00, 8),
    (4, 'South', 'Gadget', NULL, 3),
    (5, 'North', 'Widget', 200.00, NULL),
    (6, 'South', 'Widget', 175.00, 6);
```

--------------------------------

### Install libsql-client-go

Source: https://docs.turso.tech/sdk/go/quickstart

Install the driver for remote libSQL database access.

```bash
go get github.com/tursodatabase/libsql-client-go/libsql
```

--------------------------------

### Setup Function

Source: https://docs.turso.tech/sdk/c/reference

Before using libSQL, you must call the setup function. This initializes the library for use.

```APIDOC
## Setup Function

### Description

Initializes the libSQL C library. This must be called before any other libSQL functions.

### Code

```c
libsql_setup((libsql_config_t){0});
```
```

--------------------------------

### Starting Transactions

Source: https://docs.turso.tech/sql-reference/statements/transactions

Examples of starting transactions with different locking modes.

```sql
-- Start a deferred transaction (default)
BEGIN;

-- Start an immediate transaction
BEGIN IMMEDIATE;

-- The TRANSACTION keyword is optional
BEGIN IMMEDIATE TRANSACTION;
```

--------------------------------

### Install Turso CLI on Windows using WSL

Source: https://docs.turso.tech/cli/installation

First, open WSL in PowerShell, then execute the installation script to install the Turso CLI.

```bash
wsl
```

```bash
curl -sSfL https://get.tur.so/install.sh | bash
```

--------------------------------

### Common tursodb usage examples

Source: https://docs.turso.tech/sql-reference/cli/command-line-options

Examples showing how to open databases, run queries, and pipe input.

```bash
# In-memory database
tursodb

# Open an existing file
tursodb customers.db

# Run a query and exit
tursodb customers.db "SELECT count(*) FROM orders;"

# Pipe SQL from stdin
echo "SELECT 1 + 1;" | tursodb -q
```

--------------------------------

### Install turso_serverless

Source: https://docs.turso.tech/sdk/python/quickstart

Installation commands for the turso_serverless driver.

```bash
uv add turso_serverless
```

```bash
pip install turso_serverless
```

--------------------------------

### Install libsql

Source: https://docs.turso.tech/sdk/python/quickstart

Installation commands for the libsql driver.

```bash
uv add libsql
```

```bash
pip install libsql
```

--------------------------------

### Install @libsql/client

Source: https://docs.turso.tech/sdk/ts

Commands to install the client dependency using various package managers.

```bash
npm install @libsql/client
```

```bash
pnpm install @libsql/client
```

```bash
yarn add @libsql/client
```

```bash
deno add npm:@libsql/client
```

--------------------------------

### Install AgentFS SDK

Source: https://docs.turso.tech/agentfs/sdk

Installation commands for different package managers.

```bash
npm install agentfs-sdk
```

```bash
bun add agentfs-sdk
```

--------------------------------

### Install @tursodatabase/serverless

Source: https://docs.turso.tech/sdk/http/quickstart

Install the serverless package for Turso databases.

```bash
npm install @tursodatabase/serverless
```

--------------------------------

### List Databases using Node.js Client

Source: https://docs.turso.tech/api-reference/databases/list

This Node.js example demonstrates how to list databases using the Turso client library. Ensure you have the '@tursodatabase/api' package installed and provide your organization and token.

```typescript
import { createClient } from "@tursodatabase/api";

const turso = createClient({
  org: "...",
  token: "",
});

const databases = await turso.databases.list();
```

--------------------------------

### Install Drizzle and libSQL SDK

Source: https://docs.turso.tech/sdk/ts/orm/drizzle

Install Drizzle ORM, the libSQL client, and dotenv for environment variables. Also install drizzle-kit as a development dependency.

```bash
npm i drizzle-orm @libsql/client dotenv
npm i -D drizzle-kit
```

```bash
pnpm add drizzle-orm @libsql/client dotenv
pnpm add -D drizzle-kit
```

```bash
yarn add drizzle-orm @libsql/client dotenv
yarn add -D drizzle-kit
```

--------------------------------

### Install tursogo-serverless

Source: https://docs.turso.tech/sdk/go/quickstart

Install the driver for remote Turso database access.

```bash
go get turso.tech/database/tursogo-serverless
```

--------------------------------

### Install libSQL SDK and Prisma Driver (npm)

Source: https://docs.turso.tech/sdk/ts/orm/prisma

Install the necessary packages for using Prisma with Turso using npm.

```bash
npm install @libsql/client @prisma/adapter-libsql
```

--------------------------------

### Install libSQL SDK and Prisma Driver (pnpm)

Source: https://docs.turso.tech/sdk/ts/orm/prisma

Install the necessary packages for using Prisma with Turso using pnpm.

```bash
pnpm add @libsql/client @prisma/adapter-libsql
```

--------------------------------

### Install pyturso

Source: https://docs.turso.tech/sdk/python/quickstart

Install the required package using uv or pip.

```bash
uv add pyturso
```

```bash
pip install pyturso
```

--------------------------------

### Configure Environment Variables

Source: https://docs.turso.tech/sdk/python

Example structure for .env file configuration.

```text
TURSO_DATABASE_URL=turso://[databaseName]-[organizationSlug].turso.io
TURSO_AUTH_TOKEN=
```

--------------------------------

### Quick Install AgentFS CLI

Source: https://docs.turso.tech/agentfs/installation

Use this command to quickly install the AgentFS CLI on Linux, macOS, and Windows. It downloads and executes an installation script.

```bash
curl -fsSL https://github.com/tursodatabase/agentfs/releases/latest/download/agentfs-installer.sh | sh
```

--------------------------------

### Install libSQL SDK and Prisma Driver (yarn)

Source: https://docs.turso.tech/sdk/ts/orm/prisma

Install the necessary packages for using Prisma with Turso using yarn.

```bash
yarn add @libsql/client @prisma/adapter-libsql
```

--------------------------------

### Install Gems

Source: https://docs.turso.tech/sdk/activerecord/guides/rails

Run bundle install after adding the gem to your Gemfile.

```bash
bundle install
```

--------------------------------

### Start the local sync server

Source: https://docs.turso.tech/sync/local-sync-server

Starts the sync server on a specified address and port, using a local file as the database backend.

```bash
tursodb ./server.db --sync-server 0.0.0.0:8080
```

--------------------------------

### Install libSQL Rubygem

Source: https://docs.turso.tech/sdk/ruby/quickstart

Install the turso_libsql Rubygem using Bundler.

```bash
bundle add turso_libsql
```

--------------------------------

### Start Sync Server

Source: https://docs.turso.tech/sql-reference/cli/getting-started

Starts the Turso CLI as a sync server for database replication. This allows for data synchronization between different Turso instances.

```bash
tursodb --sync-server 0.0.0.0:8080 mydata.db
```

--------------------------------

### Install AgentFS SDK with Bun

Source: https://docs.turso.tech/agentfs/sdk/typescript

Install the AgentFS SDK using Bun for projects using the Bun runtime.

```bash
bun add agentfs-sdk
```

--------------------------------

### Install Turso Sync Package

Source: https://docs.turso.tech/sdk/ts

Install the sync package to enable cloud synchronization capabilities.

```bash
npm install @tursodatabase/sync
```

--------------------------------

### Install TypeScript SDK

Source: https://docs.turso.tech/api-reference/introduction

Install the official @tursodatabase/api client for JavaScript or TypeScript.

```bash
npm install @tursodatabase/api
```

--------------------------------

### Install Turso Database Package

Source: https://docs.turso.tech/sdk/ts

Install the recommended package for local and embedded use cases.

```bash
npm install @tursodatabase/database
```

--------------------------------

### Install turso_dart package

Source: https://docs.turso.tech/connect/dart

Run 'dart pub get' after updating pubspec.yaml to download and install the package.

```bash
dart pub get
```

--------------------------------

### Initialize AgentFS in Browser

Source: https://docs.turso.tech/agentfs/sdk

Demonstrates importing the SDK from a CDN and performing basic KV and file system operations.

```html
<!DOCTYPE html>
<html>
<head>
  <script type="module">
    import { AgentFS } from 'https://unpkg.com/agentfs-sdk/dist/browser.js';

    const agent = await AgentFS.open({ id: 'browser-agent' });

    // All APIs work the same in browser
    await agent.kv.set('browser:data', { platform: 'web' });
    await agent.fs.writeFile('/notes.txt', 'Hello from browser!');
  </script>
</head>
</html>
```

--------------------------------

### Get Help for a Specific Turso CLI Command

Source: https://docs.turso.tech/cli/help

To get detailed information about a specific command, including its arguments, use the `--help` flag with that command. For example, to get help for the `turso auth` command, run `turso auth --help`.

```bash
turso auth --help
```

```bash
turso db create --help
```

--------------------------------

### Examples of generate_series Usage

Source: https://docs.turso.tech/sql-reference/extensions

Practical examples showing how to generate ascending and descending integer sequences.

```sql
SELECT value FROM generate_series(1, 5);
-- 1, 2, 3, 4, 5

SELECT value FROM generate_series(0, 10, 2);
-- 0, 2, 4, 6, 8, 10

SELECT value FROM generate_series(10, 1, -3);
-- 10, 7, 4, 1
```

--------------------------------

### Install Turso Go Package

Source: https://docs.turso.tech/connect/go

Add the Turso package to your Go project using the go get command.

```bash
go get turso.tech/database/tursogo
```

--------------------------------

### Products Controller Example

Source: https://docs.turso.tech/sdk/activerecord/guides/rails

Implement index and create actions in the ProductsController to fetch all products and handle new product creation.

```ruby
class ProductsController < ApplicationController
  def index
    @products = Product.all
  end

  def create
    @product = Product.new(product_params)
    if @product.save
      redirect_to @product, notice: 'Product was successfully created.'
    else
      render :new
    end
  end

  private

  def product_params
    params.require(:product).permit(:name, :description)
  end
end
```

--------------------------------

### Encrypted Database URI Examples

Source: https://docs.turso.tech/tursodb/encryption

Examples of connection strings using different encryption algorithms and key lengths.

```bash
# AEGIS-256 with 256-bit key
file:encrypted.db?cipher=aegis256&hexkey=2d7a30108d3eb3e45c90a732041fe54778bdcf707c76749fab7da335d1b39c1d

# AES-128-GCM with 128-bit key
file:encrypted.db?cipher=aes128gcm&hexkey=5f3e2a8c9b1d4f6e7a2c8d4b9e1f3a6c

# AEGIS-256X4 (max performance) with 256-bit key
file:encrypted.db?cipher=aegis256x4&hexkey=2d7a30108d3eb3e45c90a732041fe54778bdcf707c76749fab7da335d1b39c1d
```

--------------------------------

### Install Turso API Client

Source: https://docs.turso.tech/api-reference/groups/remove-location

Install the official Turso API client package via npm.

```bash
npm install @tursodatabase/api
```

--------------------------------

### Drop a Domain

Source: https://docs.turso.tech/sql-reference/statements/drop-domain

This example shows how to create a domain and then successfully drop it. Ensure no dependencies exist before dropping.

```sql
CREATE DOMAIN positive_int AS integer CHECK (value > 0);
DROP DOMAIN positive_int;
```

--------------------------------

### Start AgentFS MCP Server

Source: https://docs.turso.tech/agentfs/guides/mcp

Starts an MCP server that exposes AgentFS tools over stdio. Use this to allow AI assistants to interact with your filesystem.

```bash
agentfs serve mcp my-agent
```

--------------------------------

### Start sync server

Source: https://docs.turso.tech/sql-reference/cli/command-line-options

Initialize a sync server for database replication at a specific address.

```bash
tursodb --sync-server 0.0.0.0:8080 mydata.db
```

--------------------------------

### List and Get Databases with TypeScript SDK

Source: https://docs.turso.tech/api-reference/introduction

Manage databases within your organization using the TypeScript SDK. This example shows how to list all databases and retrieve details for a specific database.

```typescript
// List all databases in your organization
const databases = await turso.databases.list();

// Get details for a specific database
const db = await turso.databases.get("customer-db");
```

--------------------------------

### Install Turso CLI on Windows

Source: https://docs.turso.tech/tursodb/quickstart

Installs the Turso CLI using PowerShell. Alternatively, download the executable manually.

```powershell
irm https://github.com/tursodatabase/turso/releases/latest/download/turso_cli-installer.ps1 | iex
```

--------------------------------

### OpenAPI Specification for List Locations

Source: https://docs.turso.tech/api-reference/locations/list

This OpenAPI 3.0.1 specification defines the GET /v1/locations endpoint, detailing its purpose, parameters, and response structure, including example location data.

```yaml
openapi: 3.0.1
info:
  title: Turso Platform API
  description: API description here
  license:
    name: MIT
  version: 0.1.0
servers:
  - url: https://api.turso.tech
    description: Turso's Platform API
security: []
paths:
  /v1/locations:
    get:
      summary: List Locations
      description: Returns a list of locations where you can create or replicate databases.
      operationId: listLocations
      responses:
        '200': 
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  locations:
                    type: object
                    additionalProperties:
                      type: string
                    description: A mapping of location codes to location names.
                example:
                  locations:
                    aws-ap-northeast-1: AWS AP NorthEast (Tokyo)
                    aws-ap-south-1: AWS AP South (Mumbai)
                    aws-eu-west-1: AWS EU West (Ireland)
                    aws-us-east-1: AWS US East (Virginia)
                    aws-us-east-2: AWS US East (Ohio)
                    aws-us-west-2: AWS US West (Oregon)

```

--------------------------------

### AgentFS Backup and Recovery Example

Source: https://docs.turso.tech/agentfs/guides/sync

Demonstrates the workflow for backing up agent state by pushing changes and then recovering on a new machine by initializing and pulling.

```bash
# After important work
agentfs sync my-agent push

# On a new machine
agentfs init my-agent --sync-remote-url libsql://...
agentfs sync my-agent pull
```

--------------------------------

### Start MCP server

Source: https://docs.turso.tech/sql-reference/cli/command-line-options

Launch a Model Context Protocol server for AI assistant integration.

```bash
tursodb --mcp mydata.db
```

--------------------------------

### Install libSQL Client (TypeScript)

Source: https://docs.turso.tech/sdk/ts/guides/elysia

Install the libSQL client for TypeScript. This is the first step in setting up Turso with your Elysia project.

```bash
npm install libsql-ts
```

--------------------------------

### Initialize libSQL and Connect to Local Database

Source: https://docs.turso.tech/sdk/c/quickstart

Initialize libSQL and establish a connection to a local-only database. This setup only requires the database path.

```c
#include "libsql.h"

libsql_setup((libsql_config_t){0});

libsql_database_t db = libsql_database_init((libsql_database_desc_t){
    .path = "local.db"
});

libsql_connection_t conn = libsql_database_connect(db);
```

--------------------------------

### Start of Period Modifiers

Source: https://docs.turso.tech/sql-reference/functions/date-time

Use 'start of day', 'start of month', or 'start of year' to reset the time component to midnight and adjust the date to the beginning of the respective period.

```sql
SELECT datetime('2025-06-15 14:30:00', 'start of day');
-- '2025-06-15 00:00:00'
```

```sql
SELECT date('2025-06-15', 'start of month');
-- '2025-06-01'
```

```sql
SELECT date('2025-06-15', 'start of year');
-- '2025-01-01'
```

--------------------------------

### Install libSQL PHP Client

Source: https://docs.turso.tech/sdk/php/quickstart

Install the libSQL PHP client using Composer. This command adds the necessary package to your project's dependencies.

```console
composer require turso/libsql
```

--------------------------------

### Install AgentFS CLI on Linux

Source: https://docs.turso.tech/agentfs/installation

Installs the AgentFS CLI on Linux using a curl command. Ensure FUSE is installed. After installation, restart your terminal or source your shell configuration file.

```bash
curl -fsSL https://github.com/tursodatabase/agentfs/releases/latest/download/agentfs-installer.sh | sh
```

```bash
source ~/.bashrc  # or ~/.zshrc
```

--------------------------------

### Start MCP Server

Source: https://docs.turso.tech/agentfs/reference/cli

Starts a Model Context Protocol (MCP) server for a given agent. You can specify a comma-separated list of tools to enable, such as filesystem operations or key-value store access.

```bash
agentfs serve mcp <ID_OR_PATH> [OPTIONS]
```

```bash
agentfs serve mcp my-agent
```

```bash
agentfs serve mcp my-agent --tools read_file,readdir,stat
```

--------------------------------

### Install pyturso

Source: https://docs.turso.tech/sdk/python/reference

Install the package using pip.

```bash
pip install pyturso
```

--------------------------------

### Start local sync server

Source: https://docs.turso.tech/sdk/go/quickstart

Run a local sync server for testing synchronization without a Turso Cloud account.

```bash
tursodb :memory: --sync-server 127.0.0.1:8080
```

--------------------------------

### Initialize and Query Database

Source: https://docs.turso.tech/integrations/vercel

Example of creating a database instance, executing schema changes, and performing CRUD operations.

```ts
import { createDb } from "@tursodatabase/vercel-experimental";

const db = await createDb(process.env.TURSO_DATABASE!);
try {
  // Create tables
  await db.execute(`
    CREATE TABLE IF NOT EXISTS users (
      id INTEGER PRIMARY KEY AUTOINCREMENT,
      name TEXT NOT NULL,
      email TEXT UNIQUE
    )
  `);

  // Insert data
  await db.execute(
    "INSERT INTO users (name, email) VALUES (?, ?)",
    ["Alice", "alice@example.com"]
  );

  // Query data
  const result = await db.query("SELECT * FROM users");
  console.log(result.rows);
} finally {
  await db.close(); // Syncs and closes the connection
}
```

--------------------------------

### Start local libSQL server

Source: https://docs.turso.tech/cli/dev

Launch a local libSQL server for development using the Turso CLI.

```bash
turso dev
```

--------------------------------

### Initialize libSQL and Connect to Remote Database

Source: https://docs.turso.tech/sdk/c/quickstart

Initialize libSQL and establish a connection to a remote Turso database. This setup requires the database URL and authentication token.

```c
#include "libsql.h"

libsql_setup((libsql_config_t){0});

libsql_database_t db = libsql_database_init((libsql_database_desc_t){
    .url = "TURSO_DATABASE_URL",
    .auth_token = "TURSO_AUTH_TOKEN"
});

libsql_connection_t conn = libsql_database_connect(db);
```

--------------------------------

### Create Directories

Source: https://docs.turso.tech/agentfs/sdk/rust

Demonstrates creating a single directory and creating nested directories using `mkdir_p`.

```rust
agent.fs.mkdir("/reports").await?;

agent.fs.mkdir_p("/reports/2024/Q4").await?;
```

--------------------------------

### Initialize libSQL and Connect to Embedded Replica

Source: https://docs.turso.tech/sdk/c/quickstart

Initialize libSQL and establish a connection to an embedded replica database. This setup includes database path, URL, and authentication token.

```c
#include "libsql.h"

libsql_setup((libsql_config_t){0});

libsql_database_t db = libsql_database_init((libsql_database_desc_t){
    .path = "local.db",
    .url = "TURSO_DATABASE_URL",
    .auth_token = "TURSO_AUTH_TOKEN",
    .sync_interval = 300
});

libsql_connection_t conn = libsql_database_connect(db);
```

--------------------------------

### List Database Instances using Turso SDK

Source: https://docs.turso.tech/api-reference/databases/list-instances

This Node.js example demonstrates how to use the Turso SDK to fetch a list of instances for a database. Ensure you have initialized the client with your organization and token.

```typescript
import { createClient } from "@tursodatabase/api";

const turso = createClient({
  org: "...",
  token: "",
});

const instances = await turso.databases.listInstances("my-db");
```

--------------------------------

### Initializing LibsqlClient

Source: https://docs.turso.tech/sdk/flutter/reference

Demonstrates how to create a database client instance using the LibsqlClient constructor. Supports in-memory, local SQLite, remote Turso/libSQL, and embedded replica configurations.

```APIDOC
## Initializing LibsqlClient

Call `LibsqlClient` constructor to create the database client. Different configurations are supported, allowing connection to in-memory database, local sqlite file, remote Turso / libSQL database, or embedded replica.

### In-Memory Databases

libSQL supports connecting to [in-memory databases](https://www.sqlite.org/inmemorydb.html) for cases where you don't require persistence:

```dart
final client = LibsqlClient(":memory:");
```

### Local Development

You can work locally using an SQLite file and passing the path to `LibsqlClient`:

```dart
final dir = await getApplicationCacheDirectory();
final path = '${dir.path}/local.db';

final client = LibsqlClient(path);
```

### Remote

You can work with remote database by passing your Turso Database URL:

```dart
final client = LibsqlClient('<TURSO_OR_LIBSQL_URL>')
	..authToken = '<TOKEN>';
```

### Embedded Replicas

You can work with embedded replicas by passing your Turso Database URL to `syncUrl`:

```dart
final dir = await getApplicationCacheDirectory();
final path = '${dir.path}/local.db';

final client = LibsqlClient(path)
	..authToken = '<TOKEN>'
	..syncUrl = '<TURSO_OR_LIBSQL_URL>'
	..readYourWrites = true;
```

### Encryption at rest

To enable encryption on a SQLite file, pass the `encryptionKey`:

```dart
final dir = await getApplicationCacheDirectory();
final path = '${dir.path}/local.db';

final client = LibsqlClient(path)..encryptionKey = '<KEY>';
```
```

--------------------------------

### Install Turso CLI with Script (macOS, Linux, Windows/WSL)

Source: https://docs.turso.tech/cli/installation

Execute this script to install the Turso CLI on macOS, Linux, or within WSL on Windows. Ensure you have curl installed.

```bash
curl -sSfL https://get.tur.so/install.sh | bash
```

--------------------------------

### Install AgentFS CLI on macOS

Source: https://docs.turso.tech/agentfs/installation

Installs the AgentFS CLI on macOS using a curl command. After installation, you may need to restart your terminal or source your shell configuration file.

```bash
curl -fsSL https://github.com/tursodatabase/agentfs/releases/latest/download/agentfs-installer.sh | sh
```

```bash
source ~/.zshrc  # or ~/.bashrc
```

--------------------------------

### SQL CREATE DOMAIN with Chained Constraints

Source: https://docs.turso.tech/sql-reference/statements/create-domain

Demonstrates creating a base domain and then a derived domain with additional constraints. Shows how constraints are enforced on INSERT.

```sql
CREATE DOMAIN base_amount AS integer CHECK (value > 0);
CREATE DOMAIN small_amount AS base_amount CHECK (value < 1000);

CREATE TABLE orders (
    id INTEGER PRIMARY KEY,
    quantity small_amount
) STRICT;

INSERT INTO orders VALUES (1, 50);
-- OK: passes both value > 0 and value < 1000

INSERT INTO orders VALUES (2, -1);
-- Error: fails base_amount's CHECK (value > 0)

INSERT INTO orders VALUES (3, 5000);
-- Error: fails small_amount's CHECK (value < 1000)
```

--------------------------------

### Query with Positional Placeholder (Rust Example)

Source: https://docs.turso.tech/sdk/php/reference

Example of executing a query with a positional placeholder using Rust syntax. Note: This example uses Rust syntax but is presented in a PHP context.

```rust
conn->query("SELECT * FROM users WHERE id = ?", [1]);
```

--------------------------------

### Execute with Named Placeholder (Rust Example)

Source: https://docs.turso.tech/sdk/php/reference

Example of executing an insert statement with a named placeholder using Rust syntax. Note: This example uses Rust syntax but is presented in a PHP context.

```rust
conn->execute("INSERT INTO users (name) VALUES (:name)", [ ":name" => "Iku" ]);
```

--------------------------------

### Configure libSQL Environment Variables

Source: https://docs.turso.tech/sdk/python

Example structure for libSQL .env file configuration.

```text
TURSO_DATABASE_URL=
TURSO_AUTH_TOKEN=
```

--------------------------------

### Complete FTS Example: Create, Index, Insert, Query

Source: https://docs.turso.tech/sql-reference/functions/fts

Demonstrates the full lifecycle of using FTS in Turso: creating a table, adding an FTS index with weights, inserting data, performing simple and ranked searches, and highlighting results. Also shows combining FTS with regular SQL filters.

```sql
-- Create a table
CREATE TABLE articles (
    id INTEGER PRIMARY KEY,
    title TEXT NOT NULL,
    body TEXT,
    author TEXT
);

-- Create an FTS index on title and body with field weights
CREATE INDEX idx_articles_fts ON articles USING fts (title, body)
    WITH (weights = 'title=2.0,body=1.0');

-- Insert sample data
INSERT INTO articles VALUES (1, 'Introduction to Databases', 'Databases store and organize data for efficient retrieval.', 'Alice');
INSERT INTO articles VALUES (2, 'Full-Text Search in Practice', 'Full-text search allows finding documents by content.', 'Bob');
INSERT INTO articles VALUES (3, 'Database Performance Tuning', 'Optimizing database queries requires understanding indexes.', 'Alice');
INSERT INTO articles VALUES (4, 'Getting Started with Rust', 'Rust is a systems programming language focused on safety.', 'Carol');

-- Simple search: find articles mentioning "database"
SELECT id, title FROM articles
WHERE fts_match(title, body, 'database');
-- 1 | Introduction to Databases
-- 3 | Database Performance Tuning

-- Ranked search: order by relevance
SELECT
    id,
    title,
    fts_score(title, body, 'database') AS score
FROM articles
WHERE fts_match(title, body, 'database')
ORDER BY score DESC
LIMIT 10;

-- Highlighted results
SELECT
    id,
    fts_highlight(title, '<b>', '</b>', 'database') AS title,
    fts_highlight(body, '<b>', '</b>', 'database') AS body
FROM articles
WHERE fts_match(title, body, 'database');

-- Combine FTS with regular SQL filters
SELECT id, title, author,
    fts_score(title, body, 'database') AS score
FROM articles
WHERE fts_match(title, body, 'database')
  AND author = 'Alice'
ORDER BY score DESC;
```

--------------------------------

### Install Turso Vercel Experimental Package

Source: https://docs.turso.tech/integrations/vercel

Install the required package via npm.

```bash
npm install @tursodatabase/vercel-experimental
```

--------------------------------

### Install Sentry Integration

Source: https://docs.turso.tech/sdk/ts/integrations/sentry

Install the Sentry integration package for @libsql/client using npm.

```bash
npm install sentry-integration-libsql-client
```

--------------------------------

### Install Turso CLI

Source: https://docs.turso.tech/quickstart

Commands to install the Turso CLI on different operating systems.

```bash
brew install tursodatabase/tap/turso
```

```bash
curl -sSfL https://get.tur.so/install.sh | bash
```

```bash
curl -sSfL https://get.tur.so/install.sh | bash
```

--------------------------------

### Start Drizzle Studio

Source: https://docs.turso.tech/sdk/ts/orm/drizzle

Launch Drizzle Studio using the 'db:studio' script for visual database management.

```bash
npm run db:studio
```

```bash
pnpm run db:studio
```

--------------------------------

### Launch Encrypted Database

Source: https://docs.turso.tech/tursodb/encryption

Initialize a database with encryption using the experimental flag and a connection URI.

```bash
tursodb --experimental-encryption "file:encrypted.db?cipher=aegis256&hexkey=YOUR_HEX_KEY"
```

--------------------------------

### Install libsql_dart

Source: https://docs.turso.tech/sdk/flutter/quickstart

Install the libsql_dart package using Flutter's package manager.

```bash
flutter pub add libsql_dart
```

--------------------------------

### Install AgentFS CLI

Source: https://docs.turso.tech/agentfs/introduction

Installs the AgentFS command-line interface using a curl script.

```bash
curl -fsSL https://agentfs.ai/install | bash
```

--------------------------------

### Install AgentFS Python SDK

Source: https://docs.turso.tech/agentfs/sdk/python

Install the AgentFS Python SDK using pip.

```bash
pip install agentfs-sdk
```

--------------------------------

### connect(path, options?)

Source: https://docs.turso.tech/sdk/ts/reference

Initializes a connection to a local or in-memory Turso database.

```APIDOC
## connect(path, options?)

### Description
Establishes a connection to a Turso database. Supports local file paths, in-memory databases, and optional encryption settings.

### Parameters
- **path** (string) - Required - The file path to the database or ":memory:" for an in-memory database.
- **options** (object) - Optional - Configuration object including encryption settings.

### Example
```ts
import { connect } from "@tursodatabase/database";
const db = await connect("encrypted.db", {
  encryption: {
    cipher: "aegis256",
    hexkey: "b1bbfda4f589dc9daaf004fe21111e00dc00c98237102f5c7002a5669fc76327",
  },
});
```
```

--------------------------------

### array_agg Usage Examples

Source: https://docs.turso.tech/sql-reference/functions/aggregate

Examples demonstrating how to collect values into an array using array_agg.

```sql
SELECT array_agg(name) FROM users;
-- ["Alice","Bob","Charlie"]

SELECT department, array_agg(name) FROM employees GROUP BY department;
```

--------------------------------

### Percentile Fraction Error Example

Source: https://docs.turso.tech/sql-reference/functions/aggregate

Example demonstrating an error when the percentile fraction is out of range.

```sql
SELECT percentile_cont(2.0) WITHIN GROUP (ORDER BY amount) FROM sales;
-- Error: percentile value 2 is not between 0 and 1
```

--------------------------------

### mode() Usage Examples

Source: https://docs.turso.tech/sql-reference/functions/aggregate

Examples of using mode() to find the most frequent value in a dataset.

```sql
SELECT mode() WITHIN GROUP (ORDER BY product) FROM sales;
-- 'Widget' (the most frequent product)

SELECT region, mode() WITHIN GROUP (ORDER BY product) AS top_product
FROM sales
GROUP BY region;
```

--------------------------------

### Initialize and Mount an Overlay Filesystem

Source: https://docs.turso.tech/agentfs/guides/overlay

Explicitly initializes a named overlay filesystem with a specified base directory and then mounts it to a local workspace directory. This is useful for setting up persistent, named overlay environments.

```bash
agentfs init my-overlay --base /path/to/project
```

```bash
agentfs mount my-overlay ./workspace
```

--------------------------------

### Write and push data from Client A

Source: https://docs.turso.tech/sync/local-sync-server

Demonstrates creating a table, inserting data, and pushing changes to the local sync server.

```ts
import { connect } from '@tursodatabase/sync';

const clientA = await connect({
  path: './client-a.db',
  url: 'http://localhost:8080',
});

await clientA.exec("CREATE TABLE IF NOT EXISTS notes (id TEXT PRIMARY KEY, body TEXT)");
await clientA.exec("INSERT INTO notes VALUES ('n1', 'hello from client A')");

await clientA.push();
```

```py
import turso.sync

client_a = turso.sync.connect(
    path="./client-a.db",
    remote_url="http://localhost:8080",
)

client_a.execute("CREATE TABLE IF NOT EXISTS notes (id TEXT PRIMARY KEY, body TEXT)")
client_a.commit()
client_a.execute("INSERT INTO notes VALUES ('n1', 'hello from client A')")
client_a.commit()

client_a.push()
```

```go
clientA, err := turso.NewTursoSyncDb(ctx, turso.TursoSyncDbConfig{
    Path:      "./client-a.db",
    RemoteUrl: "http://localhost:8080",
})
if err != nil {
    return err
}
connA, _ := clientA.Connect(ctx)

connA.ExecContext(ctx, "CREATE TABLE IF NOT EXISTS notes (id TEXT PRIMARY KEY, body TEXT)")
connA.ExecContext(ctx, "INSERT INTO notes VALUES ('n1', 'hello from client A')")

clientA.Push(ctx)
```

--------------------------------

### CSV Data Example

Source: https://docs.turso.tech/sql-reference/cli/shell-commands

Example content of a CSV file used for data import.

```csv
name,age
Alice,30
Bob,25
Charlie,35
```

--------------------------------

### Turso CLI Signup Command (Headless)

Source: https://docs.turso.tech/cli/auth/signup

Use the `--headless` flag when signing up from environments without a system web browser, such as Windows with WSL or remote CI/CD systems.

```bash
turso auth signup --headless
```

--------------------------------

### Slice Operator [start:end]

Source: https://docs.turso.tech/sql-reference/functions/array

Extract a sub-array using half-open range [start, end).

```APIDOC
## Slice Operator [start:end]

### Description
Extract a sub-array using half-open range [start, end).

### Syntax
`array_expr[start:end]`
```

--------------------------------

### Start local libSQL server with persistence

Source: https://docs.turso.tech/cli/dev

Launch the local libSQL server while persisting data to a specific SQLite file.

```bash
turso dev --db-file local.db
```

--------------------------------

### Create PHP Project Directory

Source: https://docs.turso.tech/sdk/php/orm/doctrine-dbal

Set up a new directory for your PHP project and navigate into it.

```bash
mkdir your-awesome-php-project
cd your-awesome-php-project
```

--------------------------------

### Install SQLAlchemy libSQL dialect

Source: https://docs.turso.tech/sdk/python/orm/sqlalchemy

Install the necessary library for SQLAlchemy to interact with libSQL databases.

```bash
pip install sqlalchemy-libsql
```

--------------------------------

### Create and Inspect Databases

Source: https://docs.turso.tech/quickstart

Commands to create Turso or libSQL databases and view their details.

```bash
turso db create my-db --tursodb
```

```bash
turso db create my-db
```

```bash
turso db show my-db
```

--------------------------------

### Execute a SQL Query

Source: https://docs.turso.tech/sdk/c/quickstart

Prepare and execute a SQL query against the database connection. This example selects all columns from the 'users' table.

```c
libsql_statement_t stmt = libsql_connection_prepare(conn, "SELECT * FROM users");
libsql_rows_t rows = libsql_statement_query(stmt);
```

--------------------------------

### Install AgentFS SDK with npm

Source: https://docs.turso.tech/agentfs/sdk/typescript

Install the AgentFS SDK using npm for Node.js projects.

```bash
npm install agentfs-sdk
```

--------------------------------

### Configure Prefix Bootstrap

Source: https://docs.turso.tech/sync/partial

Initializes a database connection by downloading a specified number of bytes from the start of the file.

```ts
import { connect } from '@tursodatabase/sync';

const db = await connect({
  path: './app.db',
  url: 'turso://...',
  authToken: process.env.TURSO_AUTH_TOKEN,
  partialSyncExperimental: {
    bootstrapStrategy: { kind: 'prefix', length: 128 * 1024 }, // 128 KiB
  },
});
```

```py
import os
import turso.sync

conn = turso.sync.connect(
    path="./app.db",
    remote_url="turso://...",
    auth_token=os.environ["TURSO_AUTH_TOKEN"],
    partial_sync_experimental=turso.sync.PartialSyncOpts(
        bootstrap_strategy=turso.sync.PartialSyncPrefixBootstrap(length=128 * 1024),
    ),
)
```

```go
import (
	turso "turso.tech/database/tursogo"
)

db, err := turso.NewTursoSyncDb(context.Background(), turso.TursoSyncDbConfig{
  Path:      "./app.db",
  RemoteUrl: "turso://...",
  AuthToken: os.Getenv("TURSO_AUTH_TOKEN"),
  PartialSyncExperimental: turso.TursoPartialSyncConfig{
    BootstrapStrategyPrefix: 128 * 1024, // 128 KiB
  },
})
```

--------------------------------

### stddev Usage Examples

Source: https://docs.turso.tech/sql-reference/functions/aggregate

Examples demonstrating how to calculate population standard deviation using stddev.

```sql
SELECT stddev(amount) FROM sales;

SELECT region, avg(amount) AS mean, stddev(amount) AS std_dev
FROM sales
GROUP BY region;
```

--------------------------------

### percentile_cont and percentile_disc Usage Examples

Source: https://docs.turso.tech/sql-reference/functions/aggregate

Examples calculating median and quartiles using percentile functions.

```sql
-- Median, interpolated vs. an actual data point
SELECT percentile_cont(0.5) WITHIN GROUP (ORDER BY amount) FROM sales;  -- 175.0
SELECT percentile_disc(0.5) WITHIN GROUP (ORDER BY amount) FROM sales;  -- 175.0

-- Quartiles per region
SELECT region,
       percentile_cont(0.25) WITHIN GROUP (ORDER BY amount) AS q1,
       percentile_cont(0.75) WITHIN GROUP (ORDER BY amount) AS q3
FROM sales
WHERE amount IS NOT NULL
GROUP BY region;
```

--------------------------------

### Create a Turso Database

Source: https://docs.turso.tech/agentfs/guides/sync

Use the `turso db create` command to create a new database for your agent. This is the first step in setting up synchronization.

```bash
turso db create my-agent-db
```

--------------------------------

### Open AgentFS with Options

Source: https://docs.turso.tech/agentfs/sdk/typescript

Demonstrates opening an AgentFS database with options, including persistent storage using an ID and ephemeral in-memory storage.

```typescript
interface AgentFSOptions {
  /**
   * Optional unique identifier for the agent.
   * - If provided: Creates persistent storage at `.agentfs/{id}.db`
   * - If omitted: Uses ephemeral in-memory database
   */
  id?: string;
}

// Persistent storage
const agent = await AgentFS.open({ id: 'my-agent' });
// Creates: .agentfs/my-agent.db

// Ephemeral in-memory database
const ephemeralAgent = await AgentFS.open();
```

--------------------------------

### array_overlap usage examples

Source: https://docs.turso.tech/sql-reference/functions/array

Examples demonstrating how to check if two arrays share any common elements.

```sql
SELECT array_overlap('[1, 2, 3]', '[3, 4, 5]');
-- 1

SELECT array_overlap('[1, 2, 3]', '[4, 5, 6]');
-- 0

SELECT array_overlap('[]', '[1, 2]');
-- 0
```

--------------------------------

### array_contains_all usage examples

Source: https://docs.turso.tech/sql-reference/functions/array

Examples demonstrating how to check if one array contains all elements of another.

```sql
SELECT array_contains_all('[1, 2, 3, 4, 5]', '[2, 4]');
-- 1

SELECT array_contains_all('[1, 2, 3]', '[2, 4]');
-- 0

SELECT array_contains_all('[1, 2, 3]', '[]');
-- 1
```

--------------------------------

### Initialize libSQL Client in Quasar

Source: https://docs.turso.tech/sdk/ts/guides/quasar

Create a libSQL client instance using environment variables for Turso connection details.

```javascript
import { createClient } from "@libsql/client/web";

const turso = createClient({
  url: import.meta.env.VITE_TURSO_DATABASE_URL,
  authToken: import.meta.env.VITE_TURSO_AUTH_TOKEN,
});
```
Tokens:
Raw