quickstart.mdx

title	sidebarTitle	description
Turso Quickstart (HTTP)	Quickstart	Get started with Turso using the libSQL remote protocol in a few simple steps.

In this HTTP quickstart we will learn how to:

• Obtain HTTP URL for a Turso database
• Create a database auth token
• Connect to a remote Turso database
• Execute a SQL using the libSQL remote protocol

Using the Turso CLI or Platform API, fetch your database URL:

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

Append /v2/pipeline to the URL and continue.

Using the Turso CLI or Platform API, create a new auth token for your database:

turso db tokens create <database-name>

We'll be sending the query using JSON, so let's create a JSON payload that executes a SQL statement and closes the connection immediately:

{
  "requests": [
    { "type": "execute", "stmt": { "sql": "SELECT * FROM users" } },
    { "type": "close" }
  ]
}

Make sure to update the stmt.sql to select from a table you already have.

Bound parameter examples included on the Reference Page,

Depending on your language, you can use a HTTP client library to send the request to the URL you created as well as the Authorization header set to the token you created, and the request body as JSON with your SQL statement.

You must append to the Base URL the actual pipeline URL that accepts requests — /v2/pipeline.

const url = "https://[databaseName]-[organizationSlug].turso.io/v2/pipeline";
const authToken = "...";

fetch(url, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${authToken}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    requests: [
      { type: "execute", stmt: { sql: "SELECT * FROM users" } },
      { type: "close" },
    ],
  }),
})
  .then((res) => res.json())
  .then((data) => console.log(data))
  .catch((err) => console.log(err));

require 'net/http'
require 'json'
require 'uri'

url = "https://[databaseName]-[organizationSlug].turso.io/v2/pipeline"
auth_token = "..."

uri = URI(url)
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer #{auth_token}"
request["Content-Type"] = "application/json"
request.body = JSON.generate({
  "requests": [
    { "type": "execute", "stmt": { "sql": "SELECT * FROM users" } },
    { "type": "close" }
  ]
})

begin
  response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
    http.request(request)
  end

  puts JSON.parse(response.body)
rescue => e
  puts e.message
end

The response will be a JSON object with a results array containing the results of your query that looks something like this:

{
  "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"
      }
    }
  ]
}

If you need to use placeholders for values, you can do that:

{
  "type": "execute",
  "stmt": {
    "sql": "SELECT * FROM users WHERE id = ?",
    "args": [
      {
        "type": "integer",
        "value": "1"
      }
    ]
  }
}

{
  "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"
        }
      }
    ]
  }
}

The type field within each arg corresponds to the column datatype and can be one of the following: null, integer, float, text, or blob.

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