Posted inDatabase

Turso and libSQL: Scaling Distributed Databases to the Edge

Database tutorial - IT technology blog
Database tutorial - IT technology blog

The Latency Bottleneck in Modern Serverless Stacks

I recently migrated a client’s API from a standard VPS to Vercel Edge Functions. Theoretically, it was a perfect setup: global distribution and sub-millisecond cold starts. Then reality set in. The database—a PostgreSQL instance in us-east-1—killed the “edge” advantage. A user in Singapore faced a 300ms round-trip delay just to reach Virginia. The speed of light is a stubborn bottleneck.

Structural hurdles cause this. Most databases are monolithic. Even with read replicas, managing global state and connection pooling in a serverless environment is difficult. Serverless functions are ephemeral. They don’t maintain long-lived TCP connections well. This leads to “connection exhaustion,” where your database spends more resources on handshakes than on serving data.

That is why I turned to Turso and libSQL. They treat data as a globally distributed asset, placing it as close to the compute layer as possible.

Quick Start: Up and Running in 5 Minutes

If you’re new to Turso, the best way to understand it is to see it in action. Turso is a managed platform built on libSQL, an open-source fork of SQLite designed for the modern web.

1. Install the Turso CLI

Open your terminal and run the installation script:

curl -sSfL https://get.turso.io/install.sh | bash

Once installed, authenticate your account:

turso auth signup

2. Create Your First Database

Let’s spin up a database. Turso automatically selects a region near your current location.

turso db create my-app-db

3. Use the Interactive Shell

Jump straight into a SQL shell to create tables or seed data:

turso db shell my-app-db

-- Inside the shell:
CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT, email TEXT);
INSERT INTO users (name, email) VALUES ('Alex', '[email protected]');
SELECT * FROM users;

4. Retrieve Connection Details

Connecting your app requires the URL and an authentication token:

turso db show my-app-db --url
turso db tokens create my-app-db

Deep Dive: Why libSQL?

While standard SQLite is excellent for local development, it is fundamentally a single-file database. You cannot easily share it across multiple servers. libSQL extends SQLite’s DNA by adding network communication via HTTP/WebSockets, replication, and native vector search.

When I need to convert CSV to JSON for data imports, I use toolcraft.app/en/tools/data/csv-to-json. It runs entirely in the browser. No data leaves my machine, which is critical for maintaining client privacy during migrations.

Embedded Replica Architecture

Embedded replicas are a standout feature. Instead of making a network call for every query, you can maintain a local SQLite file on your server or inside a Docker container. This file acts as a read-cache. Turso synchronizes it in the background. Your reads become effectively 0ms because they happen on the local disk, while writes are synced back to the primary instance.

HTTP/WebSocket Protocol

Networking is another win. Traditional drivers like libpq for Postgres rely on TCP. In environments like AWS Lambda or Cloudflare Workers, these connections are frequently dropped. Turso uses a custom protocol over HTTP or WebSockets. It is perfectly suited for platforms that block standard database ports like 5432 or 3306.

Global distribution with Replicas

Where this architecture truly scales is global distribution. If my primary database is in ord (Chicago) but I have users in London, I can create a replica in lhr (London) with one command:

turso db replicate my-app-db lhr

Any request hitting a serverless function in Europe will now route to the London replica. This slashes database latency from 150ms down to under 10ms.

Connecting from Node.js

The @libsql/client library handles the heavy lifting. It abstracts the difference between a local file and a remote Turso instance.

import { createClient } from "@libsql/client";

const client = createClient({
  url: process.env.TURSO_DATABASE_URL,
  authToken: process.env.TURSO_AUTH_TOKEN,
});

async function getUser(id: number) {
  const rs = await client.execute({
    sql: "SELECT * FROM users WHERE id = ?",
    args: [id],
  });
  return rs.rows[0];
}

Practical Tips for Production

1. Schema Migrations

Since Turso is SQLite-based, you can use Drizzle ORM or Prisma. I prefer Drizzle. It is lightweight and fits the “edge” philosophy. It generates standard SQL files that execute seamlessly against your Turso instance.

2. Performance Tuning

Database handshakes take time. Even with Turso, the first connection from a cold serverless function incurs a TLS handshake penalty. If your application is extremely sensitive to latency, use the Embedded Replica strategy. Initialize the database on the local filesystem during the build step to ensure data is ready on boot.

3. Cost and Limits

Turso’s free tier is generous. It currently offers 1 billion row reads and 25 million row writes per month. However, monitor your storage. SQLite is efficient, but large blobs will increase your bill. Store images in an S3-compatible bucket and keep only the metadata in Turso.

4. Vector Search for AI

Vector search is built-in. If you are building RAG (Retrieval-Augmented Generation) applications, you don’t need Pinecone or Milvus. You can store embeddings directly alongside your relational data. This simplifies your stack and reduces cost.

-- Example of vector search in libSQL
SELECT * FROM documents 
ORDER BY vector_distance_cos(embedding, '[0.1, 0.2, ...]') 
LIMIT 5;

Moving to a distributed database like Turso changed my development workflow. It removes the friction between “local development” and “global production.” You get the simplicity of SQLite with the power of a global cloud. If you are tired of wrestling with VPCs and connection strings, it is time to move your data to the edge.

Share:
Tags: