libSQL Remote Protocol Reference
Turso Databases can be accessed via HTTP. The API enable developers to perform SQL operations using the libSQL remote protocol, 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 libsql://
with https://
:
You can obtain your database base URL from the Turso CLI:
Authentication
Turso uses Bearer authentication, and requires your API token to be passed with all protected requests in the Authorization
header:
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
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 theargs
field.
- 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 thenamed_args
field of the query should be an array of objects mapping parameters to their values.
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:
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:
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:
GET /health
To check the health of your database, you can use the /health
endpoint which returns an empty body with an HTTP status:
GET /dump
You can dump the database using the /dump
endpoint:
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, Hobby and Scaler plans.
GET /v1/jobs
Returns a summary of all migration jobs for a schema:
Response Fields
Current version of the schema.
List of migration jobs
GET /v1/jobs/:id
Returns detailed information about a specific migration job.
Path Parameters
The ID of the migration job.
Response Fields
Unique ID of the migration job.
Overall status of the job. Possible values are the same as in the /v1/jobs
endpoint.
Error message if the job failed, null otherwise.
List of migration statuses for the individual databases.
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.
Your database group must be using the version v0.24.18
or greater — turso group update <group-name> --version latest
GET /beta/listen
Query Parameters
The name of the table to listen to.
The name of the action to listen to — insert
, update
, or delete
.
Was this page helpful?