Turso LibSQL Documentation Quick Guide

Turso LibSQL Documentation Quick Start

Basic Usage#

Refer to https://docs.turso.tech/quickstart#select-all-rows-from-table for the quick start documentation.

Install turso cli
Log in, register turso
Create a database
Show database status
Enter database shell
Write SQL to create table, insert data, query data - this part will be completed later using drizzle
Copy the database to another region locations

It's relatively simple to use, and there are two options for connecting to the database in subsequent business: sdk and http connection.

Get the db's url
Get the jwt's token
Install @libsql/client
Create a client based on createClient
Client executes sql

Based on drizzle ORM#

[[Drizzle ORM Documentation Quick Start]]
[[01-Understanding Exploring sqlite and Cloudflare D1]]
[[node + sqlite]]
[[better-sqlite3]]

Drizzle has first-class support for sqlite, and even AstroDB is wrapped based on drizzle.

Usage:

Install drizzle-orm and @libsql/client dependencies
Install drizzle-kit as a development dependency for generating sql and migration sql development operations
- drizzle-kit generate to generate
- drizzle-kit migrate to migrate
- drizzle-kit studio to view on the page
Get the db's uri and jwt token
Create db/schema.ts to export table definitions
Configure drizzle.config.ts to set schema location, driver, connection parameters
Use libsql to create a client instance, wrapped with drizzle
If the schema is modified, generate sql and migrate the database
Use studio to view data

The documentation also mentions that you can use sentry to capture slow sql queries and sql errors.

Based on http Method#

libsql remote protocol

Get the db's url and token
Complete the /v2/pipeline based on the http url
Prepare the json payload parameters, execute and close
Use post to send and query results
During the sending process, parameter indexing and naming were mentioned

Why close? If not closed, it can still be continued based on ctx within 10s.

This method is based on http and is a unique connection solution that can easily connect in any scenario, which is quite interesting.

Keyword Explanation#

sqlite is the db itself
turso is the encapsulation of the entire solution

Docker Self-hosting#

The following can achieve an unauthenticated scheme to intercept the hosted libsql-server, but for jwt authentication, further investigation is needed.

Documentation address
https://github.com/tursodatabase/libsql/blob/main/docs/DOCKER.md

Using this on an M1 chip Apple

docker run --name some-sqld  -p 8080:8080 -ti \
    -e SQLD_NODE=primary \
    --platform linux/amd64 \
    ghcr.io/tursodatabase/libsql-server:latest

Data Persistence

Environment variables

sqld_node=primary/replica/standalone
Data volume -v sqld-data:/var/lib/sqld
db location, essentially still sqlite, SQLD_DB_PATH=iku.db
Remote jwt authorization sqld_auth_jwt_key_file pass a key.pem private key,
- You can also use SQLD_AUTH_JWT_KEY to directly pass a string

What does jwt look like? Hope to connect and operate via http in the future.

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

Hosted Service Quick Code#

# Show url
turso db show my-db --http-url

# token
turso db tokens create my-db

Refer to https://www.json.cn/jwt/
https://jwt.io/

// header
{
  "alg": "EdDSA",
  "typ": "JWT"
}

// payload
{
  "iat": 1726756735,
  "id": "81220406-4854-4d4b-817e-61f4a092cdc4"
}