Query.Farm

---

grainlift-turso is a small server that sits in front of a Turso database and lets analytics and data tools work with it directly. Point DuckDB at it and your Turso tables become tables you can join with local data. Use it from Python and you get results as Apache Arrow, ready for pandas or Polars. Load data into Turso from a DuckDB query in one statement.

It works with both kinds of Turso database:

• Turso Cloud: databases hosted by Turso, on either of its engines.
• Local files: a database file on the server, run by the embedded Turso Database engine.

Why use it

• Your tools, your Turso data. Anything with an ADBC driver can read and write Turso: DuckDB, Haybarn, Python, Go, Rust, Java and more.
• Fast, typed results. Rows arrive as Arrow columns with proper types (integers stay integers), streamed in batches, so even very large results use little memory.
• Bulk loading. Copy a DuckDB query result or a pandas table into Turso in one call; Turso Cloud loads arrive in about 50,000 rows per second.
• Safe to share. Clients authenticate with tokens or certificates, see only the databases you allow, and never see your Turso credentials. Read-only access is enforced by Turso itself.
• Built for production. Runaway queries are stopped, clients can cancel, and it ships with health checks, structured logs, tracing and a container image.

How it works

Your tool loads the Grainlift ADBC driver (pip install adbc-driver-grainlift), which talks to grainlift-turso over the network. grainlift-turso runs your SQL on Turso as written and streams the results back.

Quick start

This takes about five minutes. You need Python 3.13 or newer (for the driver) and uv (to run Haybarn, a DuckDB distribution).

1. Download grainlift-turso for your platform from the latest release and unpack it. For example, on a Mac with Apple Silicon:

curl -L https://github.com/Query-farm/grainlift-turso/releases/latest/download/grainlift-turso-aarch64-apple-darwin.tar.gz | tar xz
cd grainlift-turso-aarch64-apple-darwin

Platform	Download
Linux, x86_64	grainlift-turso-x86_64-unknown-linux-gnu.tar.gz
Linux, ARM64	grainlift-turso-aarch64-unknown-linux-gnu.tar.gz
macOS, Apple Silicon	grainlift-turso-aarch64-apple-darwin.tar.gz
macOS, Intel	grainlift-turso-x86_64-apple-darwin.tar.gz
Windows, x86_64	grainlift-turso-x86_64-pc-windows-msvc.zip

Each release lists SHA-256 checksums in SHA256SUMS. (Prefer containers? ghcr.io/query-farm/grainlift-turso is the same program; see Running it in production.)

2. Install the Grainlift driver from PyPI, and note where its library is:

pip install adbc-driver-grainlift
export GRAINLIFT_DRIVER=$(python -c "import adbc_driver_grainlift; print(adbc_driver_grainlift.driver_path())")

3. Start grainlift-turso on a new local database file:

export GRAINLIFT_TOKEN=choose-a-secret
TURSO_DATABASE_URL=demo.db ./grainlift-turso

It prints Grainlift listening on http://127.0.0.1:8080. Leave it running.

4. Query it from DuckDB. In a second terminal, in the same directory and with the same two exports, start Haybarn with uvx haybarn-cli and paste the SQL below. It attaches the Turso database, creates a table in it from a DuckDB query, adds a row, and joins it with local data. (It is also included as examples/query.sql: uvx haybarn-cli < examples/query.sql runs it in one go.)

FORCE INSTALL adbc_scanner FROM community;
LOAD adbc_scanner;

-- How to reach grainlift-turso: the driver, the server and a token.
CREATE SECRET turso (
    TYPE adbc,
    DRIVER getenv('GRAINLIFT_DRIVER'),
    URI 'http://127.0.0.1:8080',
    SCOPE 'http://127.0.0.1:8080',
    EXTRA_OPTIONS MAP {
        'grainlift.target': 'turso',
        'grainlift.auth.bearer_token': getenv('GRAINLIFT_TOKEN')
    }
);

-- Attach the Turso database. READ_WRITE lets you create tables and insert.
ATTACH 'http://127.0.0.1:8080' AS turso (TYPE adbc, SECRET 'turso', READ_WRITE);

-- Create a Turso table from a DuckDB query, then add a row.
CREATE TABLE turso.cities AS
    SELECT * FROM (VALUES
        ('Lima', 'PE', 10092000),
        ('Pune', 'IN', 7166000),
        ('Rome', 'IT', 2873000)
    ) AS v(name, country, population);

INSERT INTO turso.cities VALUES ('Oslo', 'NO', 709000);

-- Query it like any table, joined here with local data.
SELECT c.name, k.country, c.population
FROM turso.cities c
JOIN (VALUES ('PE', 'Peru'), ('IN', 'India'), ('IT', 'Italy'), ('NO', 'Norway')) AS k(code, country)
  ON c.country = k.code
ORDER BY c.population DESC;

The last query prints:

┌─────────┬─────────┬────────────┐
│  name   │ country │ population │
│ varchar │ varchar │   int64    │
├─────────┼─────────┼────────────┤
│ Lima    │ Peru    │   10092000 │
│ Pune    │ India   │    7166000 │
│ Rome    │ Italy   │    2873000 │
│ Oslo    │ Norway  │     709000 │
└─────────┴─────────┴────────────┘

Using it

From DuckDB

Attach the database with READ_WRITE, and its tables behave much like local ones: query and join them, create them from queries, and insert into them. DRIVER is the library path that adbc_driver_grainlift.driver_path() prints:

FORCE INSTALL adbc_scanner FROM community;
LOAD adbc_scanner;

CREATE SECRET turso (
    TYPE adbc,
    DRIVER '/path/to/libadbc_driver_grainlift.dylib',
    URI 'http://127.0.0.1:8080',
    SCOPE 'http://127.0.0.1:8080',
    EXTRA_OPTIONS MAP {'grainlift.target': 'turso', 'grainlift.auth.bearer_token': 'choose-a-secret'}
);
ATTACH 'http://127.0.0.1:8080' AS turso (TYPE adbc, SECRET 'turso', READ_WRITE);

SELECT * FROM turso.cities WHERE population > 1000000;
CREATE TABLE turso.sales AS SELECT * FROM 'sales.parquet';   -- loads in bulk
INSERT INTO turso.sales SELECT * FROM 'more_sales.parquet';

Leave out READ_WRITE to attach read-only.

DuckDB's attached databases cannot UPDATE or DELETE rows here, or run DDL such as CREATE INDEX or DROP TABLE: DuckDB changes rows by row ID, which remote tables do not have. Send those statements to Turso directly with adbc_execute, which reports the rows changed:

SET VARIABLE conn = (SELECT adbc_connect({'secret': 'turso'}));
CALL adbc_execute(getvariable('conn')::BIGINT, 'UPDATE cities SET population = population + 1000 WHERE country = ''NO''');
CALL adbc_execute(getvariable('conn')::BIGINT, 'CREATE INDEX cities_country ON cities (country)');

A table created with adbc_execute appears in the attached database once you attach it again.

Use Haybarn 1.5.5 or newer: the adbc_scanner that stock DuckDB currently downloads is too old to load data through Grainlift.

From Python

from adbc_driver_grainlift import dbapi

with dbapi.connect(db_kwargs={
    "grainlift.uri": "http://127.0.0.1:8080",
    "grainlift.target": "turso",
    "grainlift.auth.bearer_token": "choose-a-secret",
}) as conn, conn.cursor() as cur:
    cur.execute("SELECT name, population FROM cities")
    table = cur.fetch_arrow_table()      # or cur.fetch_df() for pandas

pip install adbc-driver-grainlift pyarrow provides everything this needs. From Go, Rust, Java or C++, load the same library (driver_path()) through that language's ADBC driver manager, with the entry point AdbcDriverGrainliftInit and the same grainlift.* settings.

With Turso Cloud

Point the server at your database's URL and give it a database token:

export TURSO_DATABASE_URL=libsql://my-db-my-org.turso.io
export TURSO_AUTH_TOKEN=$(turso db tokens create my-db)
./grainlift-turso

Prefer to have each person use their own Turso token, so Turso applies their permissions? Leave TURSO_AUTH_TOKEN unset, and each client adds its token as turso.auth_token next to its other connection settings.

Running it in production

For a long-running deployment, describe your databases and who may use them in a configuration file, then check and serve it:

[server]
listen = "127.0.0.1:8080"

[auth.static_bearer_tokens]
"replace-with-a-long-random-token" = "analytics"

[targets.app]                         # clients connect to the target "app"
url = "libsql://app-myorg.turso.io"
auth_token_env = "TURSO_APP_TOKEN"    # the Turso token comes from the environment

grainlift-turso check --config turso.toml    # validates the file and connects to every database
grainlift-turso serve --config turso.toml

Or run the container image, for Linux on x86_64 or ARM64:

docker run -p 8080:8080 -e TURSO_APP_TOKEN \
  -v ./turso.toml:/etc/grainlift-turso/turso.toml:ro \
  ghcr.io/query-farm/grainlift-turso:latest

One server can serve many databases, each with its own settings, and supports single sign-on (JWT), mutual TLS, per-user database permissions, health checks, JSON logs, tracing and graceful shutdown. The deployment guide covers all of it, and turso.example.toml is a complete, annotated example.

What you can do

• Run any SQL that Turso supports, and read results with proper column types.
• Write: inserts, updates, deletes, schema changes, with transactions.
• Load whole tables at once (bulk ingestion), atomically.
• Use parameterized queries (?, :name, ...).
• Browse tables and columns from tools that show a catalog, like DuckDB's ATTACH.
• Cancel a long-running query.
• On Turso Cloud's newer engine, let many clients write at the same time (transaction_mode = "concurrent").

Troubleshooting

"retry it" or SQLSTATE 40001. Another writer got there first: your transaction was rolled back, and nothing it did was saved. Run it again. This is normal under heavy concurrent writing.

"exceeded its … deadline". The query ran longer than the server allows (60 seconds by default). Narrow the query, or raise operation_timeout_seconds in the configuration.

A write fails as unauthorized. The database is read-only for you: a read-only Turso token, or a file served with read_only = true.

"Column … has type Int64 but row … holds text". A column mixes kinds of values, which SQLite-style databases allow. Add a CAST in your query to choose the type you want.

Loading data hangs in DuckDB. Your adbc_scanner extension is too old. Run FORCE INSTALL adbc_scanner FROM community; in Haybarn 1.5.5 or newer.

"Can only update base table", or "do not support creating tables through DDL". DuckDB's attached databases cannot update, delete or run DDL on remote tables; use adbc_execute (see From DuckDB).

A new table doesn't appear in an attached database. DuckDB caches the table list when you attach. Detach and attach again.

Learn more

• Deployment guide: configuration, authentication, health checks, logging, containers and scaling.
• How it works: architecture, type mapping, design decisions, error codes and limitations.
• Development: building from source, testing and CI.
• Changelog

License

Copyright © 2026 Query Farm LLC. Released under the Apache License 2.0; see LICENSE.

The data in a Turso database belongs to its owner, and Turso Cloud is subject to Turso's terms. See NOTICE. This project is not affiliated with or endorsed by Turso.

---