SQL over HTTP Reference

Turso Databases can be accessed via HTTP. The API enables developers to perform SQL operations using SQL over HTTP, retrieve server version information, and monitor the health status.

It’s recommended you use a native SDK.

Base URL

Simply replace your database URL protocol (turso:// for Turso databases, libsql:// for libSQL databases) with https://:

https://[databaseName]-[organizationSlug].turso.io

You can obtain your database base URL from the Turso CLI:

Obtain HTTP URL using Turso CLI

turso db show <database-name> --http-url

Authentication

Turso uses Bearer authentication, and requires your API token to be passed with all protected requests in the Authorization header:

Authorization: Bearer TOKEN

Create token using Turso CLI

turso db tokens create <database-name>

Endpoints

Your database has the endpoints available below:

`POST /v2/pipeline`

You can use the /v2/pipeline endpoint to query a database. The endpoint accepts a series of operations to perform against a database connection. The supported operation types are:

execute: execute a statement on the connection.
close: close the connection.

Simple query

{
  "requests": [
    { "type": "execute", "stmt": { "sql": "CREATE TABLE users (name)" } },
    { "type": "close" }
  ]
}

{
  "baton": null,
  "base_url": null,
  "results": [
    {
      "type": "ok",
      "response": {
        "type": "execute",
        "result": {
          "cols": [],
          "rows": [],
          "affected_row_count": 0,
          "last_insert_rowid": null,
          "replication_index": "1"
        }
      }
    },
    {
      "type": "ok",
      "response": {
        "type": "close"
      }
    }
  ]
}

Connections are left open until they timeout, unless you close them explicitly in the request (as shown above). Every request made on a connection bumps the timeout. You should close the connection when it’s no longer needed.

Parameter binding

Queries with bound parameters come in two types:

Positional query parameters, bound by their position in the parameter list, and prefixed ?. If the query uses positional parameters, the values should be provided as an array to the args field.

{
  "requests": [
    {
      "type": "execute",
      "stmt": {
        "sql": "SELECT * FROM users WHERE name = ?",
        "args": [
          {
            "type": "text",
            "value": "Turso"
          }
        ]
      }
    },
    {
      "type": "close"
    }
  ]
}

{
  "baton": null,
  "base_url": null,
  "results": [
    {
      "type": "ok",
      "response": {
        "type": "execute",
        "result": {
          "cols": [
            {
              "name": "name",
              "decltype": "TEXT"
            }
          ],
          "rows": [
            [
              {
                "type": "text",
                "value": "Turso"
              }
            ]
          ],
          "affected_row_count": 0,
          "last_insert_rowid": null
        }
      }
    },
    {
      "type": "ok",
      "response": {
        "type": "close"
      }
    }
  ]
}

Named bound parameters, where the parameter is referred to by a name and is prefixed with a :, a @ or a $. If the query uses named parameters, then the named_args field of the query should be an array of objects mapping parameters to their values.

{
  "requests": [
    {
      "type": "execute",
      "stmt": {
        "sql": "SELECT * FROM users WHERE name = :name OR name = $second_name OR name = @third_name",
        "named_args": [
          {
            "name": "name",
            "value": {
              "type": "text",
              "value": "Turso"
            }
          },
          {
            "name": "second_name",
            "value": {
              "type": "text",
              "value": "Not Turso"
            }
          },
          {
            "name": "third_name",
            "value": {
              "type": "text",
              "value": "Maybe Turso"
            }
          }
        ]
      }
    },
    {
      "type": "close"
    }
  ]
}

{
  "baton": null,
  "base_url": null,
  "results": [
    {
      "type": "ok",
      "response": {
        "type": "execute",
        "result": {
          "cols": [
            {
              "name": "name",
              "decltype": "TEXT"
            }
          ],
          "rows": [
            [
              {
                "type": "text",
                "value": "Turso"
              }
            ]
          ],
          "affected_row_count": 0,
          "last_insert_rowid": null
        }
      }
    },
    {
      "type": "ok",
      "response": {
        "type": "close"
      }
    }
  ]
}

The name property of each named_args can match the prefix or omit the prefix. They were omitted in the example above, but both versions are valid.The type field within each arg corresponds to the column datatype and can be one of the following: null, integer, float, text, or blob.

If using the blob type, replace the value property with base64 and encode the argument into base64 before sending the request.

In JSON, the value is a String to avoid losing precision, because some JSON implementations treat all numbers as 64-bit floats.

Interactive query

Sometimes, it may be desirable to perform multiple operation on the same connection, in multiple roundtrips. We can do this by not closing the connection right away:

{
  "requests": [{ "type": "execute", "stmt": { "sql": "BEGIN" } }]
}

{
  "baton": "m7lVVgEvknpf1P1irxHsHqrAqH7BLiwO4DQIAwr93PdZWGvdBNugLSokSsCZNkry",
  "base_url": null,
  "results": [
    {
      "type": "ok",
      "response": {
        "type": "execute",
        "result": {
          "cols": [],
          "rows": [],
          "affected_row_count": 0,
          "last_insert_rowid": null,
          "replication_index": "1"
        }
      }
    }
  ]
}

We can see that we have received a baton back. This is because we haven’t closed the connection. We can now use this baton to perform more queries on the same connection:

Body

{
  "baton": "m7lVVgEvknpf1P1irxHsHqrAqH7BLiwO4DQIAwr93PdZWGvdBNugLSokSsCZNkry",
  "requests": [
    { "type": "execute", "stmt": { "sql": "CREATE TABLE users (name)" } },
    {
      "type": "execute",
      "stmt": { "sql": "INSERT INTO users VALUES (\"iku\")" }
    },
    { "type": "execute", "stmt": { "sql": "COMMIT" } },
    { "type": "close" }
  ]
}

Note that both transactions and connections have timeouts. Transaction have a 5 seconds window to complete, while connections get closed after 10 seconds of idle time.

Response types

The response contains the following fields:

Field	Type	Description
`baton`	string	The baton is used to identify a connection with the server so that it can be reused.
`base_url`	string	The base URL of the server that handled the request. This URL can be reused for subsequent requests to force routing to that server.
`results`	array	The results for each of the requests made in the pipeline.

The results array contains the results for each of the requests made in the pipeline. Each result has the following fields:

Field	Type	Description
`cols`	array	The list of columns for the returned rows.
`rows`	array	The rows returned for the query.
`affected_row_count`	integer	The number of rows affected by the query.
`last_insert_rowid`	integer	The ID of the last inserted row.
`replication_index`	string	The replication timestamp at which this query was executed.
`rows_read`	integer	The number of rows read by the query.
`rows_written`	integer	The number of rows written by the query.
`query_duration_ms`	float	The duration of the query in milliseconds.

`GET /version`

To obtain the current version of the server running your database you can use the /version endpoint:

curl -L -X GET 'https://[databaseName]-[organizationSlug].turso.io/version' \
  -H 'Authorization: Bearer TOKEN'

sqld 0.21.9 (67f3ea5d 2023-10-26)

`GET /health`

To check the health of your database, you can use the /health endpoint which returns an empty body with an HTTP status:

curl -L -X GET 'https://[databaseName]-[organizationSlug].turso.io/health' \
  -H 'Authorization: Bearer TOKEN'

This response has no body data.

`GET /dump`

You can dump the database using the /dump endpoint:

curl -L -X GET 'https://[databaseName]-[organizationSlug].turso.io/dump' \
  -H 'Authorization: Bearer TOKEN'

PRAGMA foreign_keys=OFF;
BEGIN TRANSACTION;
CREATE TABLE IF NOT EXISTS mytable (
content TEXT,
embedding FLOAT32(1536)
);
CREATE TABLE IF NOT EXISTS libsql_vector_index (type TEXT, name TEXT, vector_type TEXT, block_size INTEGER, dims INTEGER, distance_ops TEXT);
INSERT INTO libsql_vector_index VALUES('diskann','mytable_idx','float32',128,1536,'cosine');
CREATE INDEX mytable_idx USING diskann_cosine_ops ON mytable (embedding);
COMMIT;

If you’re using multi-db schemas, or vector databases, you will see statements that represent internally managed tables.

Schema Migration Status

Turso provides a managed multi-tenant schema system — Multi-DB Schemas. This feature allows you to create a single database that shares its schema automatically with any related child databases. Changes to the parent database automatically propogate to the related databases. The /v1/jobs endpoint lets you monitor the status of schema migrations.

Currently not available on AWS for Free, Developer and Scaler plans.

`GET /v1/jobs`

Returns a summary of all migration jobs for a schema:

curl -X GET 'https://[databaseName]-[organizationSlug].turso.io/v1/jobs' \
     -H 'Authorization: Bearer TOKEN'

{
  "schema_version": 4,
  "migrations": [
    {
      "job_id": 43,
      "status": "RunSuccess"
    },
    {
      "job_id": 42,
      "status": "RunSuccess"
    },
    {
      "job_id": 39,
      "status": "RunSuccess"
    }
  ]
}

Response Fields

number

Current version of the schema.

array

List of migration jobs

Show Migration Object

number

Unique ID for the migration job.

string

Current status of the job. Possible values: WaitingDryRun, DryRunSuccess, DryRunFailure, WaitingRun, RunSuccess, RunFailure

`GET /v1/jobs/:id`

Returns detailed information about a specific migration job.

curl -X GET 'https://[databaseName]-[organizationSlug].turso.io/v1/jobs/:id' \
     -H 'Authorization: Bearer TOKEN'

{
  "job_id": 1,
  "status": "RunSuccess",
  "error": null,
  "progress": [
    {
      "namespace": "db1",
      "status": "Success",
      "error": null
    },
    {
      "namespace": "db2",
      "status": "Failure",
      "error": "Connection lost"
    }
  ]
}

Path Parameters

number

required

The ID of the migration job.

Response Fields

number

Unique ID of the migration job.

string

Overall status of the job. Possible values are the same as in the /v1/jobs endpoint.

string

Error message if the job failed, null otherwise.

array

List of migration statuses for the individual databases.

Show Progress Object

string

Name of the database.

string

Status of migration for this database. Possible values: Enqueued, DryRunSuccess, DryRunFailure, Run, Success, Failure

string

Error message if migration failed for this database, null otherwise.

Listen to changes

You can listen to changes committed to your database using the /beta/listen endpoint:

This is currently in technical preview. Join us in Discord to report any issues.

Currently not available on AWS for Free, Developer and Scaler plans.

Your database group must be using the version v0.24.18 or greater — turso group update <group-name> --version latest

`GET /beta/listen`

Request

curl -L 'https://[primary-instance-id]-[databaseName]-[organizationSlug].turso.io/beta/listen?table=TABLE_NAME' \
-H 'Authorization: Bearer TOKEN'

Query Parameters

string

required

The name of the table to listen to.

string

required

The name of the action to listen to — insert, update, or delete.

Turso Cloud

SDKs

CLI

API Reference

Integrations

SQL over HTTP Reference

Base URL

Authentication

Endpoints

`POST /v2/pipeline`

Simple query

Parameter binding

Interactive query

Response types

`GET /version`

`GET /health`

`GET /dump`

Schema Migration Status

`GET /v1/jobs`

Response Fields

`GET /v1/jobs/:id`

Path Parameters

Response Fields

Listen to changes

`GET /beta/listen`

Query Parameters

​Base URL

​Authentication

​Endpoints

​POST /v2/pipeline

​Simple query

​Parameter binding

​Interactive query

​Response types

​GET /version

​GET /health

​GET /dump

​Schema Migration Status

​GET /v1/jobs

​Response Fields

​GET /v1/jobs/:id

​Path Parameters

​Response Fields

​Listen to changes

​GET /beta/listen

​Query Parameters

Base URL

Authentication

Endpoints

`POST /v2/pipeline`

Simple query

Parameter binding

Interactive query

Response types

`GET /version`

`GET /health`

`GET /dump`

Schema Migration Status

`GET /v1/jobs`

Response Fields

`GET /v1/jobs/:id`

Path Parameters

Response Fields

Listen to changes

`GET /beta/listen`

Query Parameters