How to Use Turso: The Beginner's Guide (First Database, First Query, Embedded Replicas, and Branching)

CodexFuse Team · 2026-10-31T03:57:27.257Z · 17 min read

How to Use Turso: The Beginner's Guide (First Database, First Query, Embedded Replicas, and Branching)

Learning how to use Turso comes down to one idea: SQLite without the "stuck on one machine" problem. Turso gives you a managed, SQLite-compatible database that lives in the cloud and replicates close to your users, so you keep SQLite's simplicity — one file, plain SQL, zero database server to babysit — while your app reads data from the edge instead of one distant server. Install the CLI, sign up, create a database, and you can run your first SELECT from the interactive shell within minutes.

This Turso database for beginners tutorial walks the complete arc in one sitting: what Turso actually is (and how it differs from plain SQLite), installing the CLI, creating your first database, running your first table and query, connecting from JavaScript with @libsql/client, picking the right SDK package, adding embedded replicas for local-speed reads, branching a database for safe testing, pairing Turso with the Drizzle ORM, what the free tier honestly includes, and the beginner mistakes to avoid. If you want to practice SQL statements before you touch the shell, a free SQL query builder in your browser builds your first SELECT statements for you.

What Is the Fastest Way to Start Using Turso?

Install the CLI, sign up, create a database, and open the shell — four commands get you to your first query.

1. Install the CLI: curl -sSfL https://get.tur.so/install.sh | bash (or brew install tursodatabase/tap/turso on macOS).
2. Sign up: turso auth signup opens your browser to create your account.
3. Create your first database: turso db create my-db --tursodb — Turso picks the location closest to you automatically.
4. Open the shell: turso db shell my-db, then run CREATE TABLE, INSERT, and SELECT like any SQLite database.
5. Get your connection details: turso db show my-db --url and turso db tokens create my-db.
6. Store both in environment variables — TURSO_DATABASE_URL and TURSO_AUTH_TOKEN — never in your source code.
7. Query from your app with npm install @libsql/client and createClient({ url, authToken }).

What Is Turso, Exactly?

Turso is a SQLite-compatible database platform with two engines: Turso Database, a ground-up rewrite of SQLite in Rust with concurrent writes (MVCC) and async I/O, and libSQL, an open-source fork of SQLite. Turso Cloud hosts both, and your existing SQLite SQL, schemas, and queries work unchanged on either.

That "compatible with SQLite" part is the whole pitch. SQLite is beloved because it is a single file with no server process, but a single file cannot serve a global app — reads from Tokyo hit a server in Virginia. Turso keeps the SQLite experience (plain SQL, tiny footprint, instant database creation) and distributes it: your data replicates to edge locations so reads happen near your users instead of across an ocean.

One current event matters before you invest time. On October 2, 2026, Turso announced it is joining Supabase (which also raised $150 million in the same announcement, led by GIC). The message to existing users is continuity: "Turso keeps running. Your databases, APIs, and workflows continue as they do today," Turso Database remains open source, Turso keeps working on SQLite while Supabase keeps building around Postgres, and pricing is unchanged so far. Treat Turso as a stable platform today with a Supabase-shaped future — not as a product about to disappear.

What Do You Need Before You Start?

You need a terminal, a GitHub account (Turso signup runs through it), and about ten minutes. Node.js 18 or newer is needed only when you reach the JavaScript section; everything before that is pure CLI.

Windows users should use WSL2, since the install script and CLI target macOS and Linux (the CLI docs list Windows separately in some guides, but the smoothest path is WSL). No credit card is required — the free tier starts at $0.

How Do You Install the Turso CLI?

Run the official install script, which downloads the right binary for your machine.

# macOS or Linux — official installer
curl -sSfL https://get.tur.so/install.sh | bash

# macOS alternative — Homebrew tap
brew install tursodatabase/tap/turso

Confirm it worked with turso --version. If your shell cannot find the command after the script finishes, restart the terminal or add the install directory to your PATH as the script instructs — this is the most common install hiccup and it is always the PATH.

How Do You Create Your First Database?

Sign up, create the database with one command, and open the shell.

# Opens your browser to sign up (or log in)
turso auth signup

# Create your first database — Turso picks the closest location
turso db create my-db --tursodb

# Look at what you just made
turso db show my-db

The --tursodb flag chooses the Turso Database engine (the Rust rewrite with concurrent writes). Omit it — turso db create my-db — and you get a libSQL database instead, the SQLite fork. For a first project the difference barely matters; pick --tursodb unless you have a reason to want classic SQLite behavior.

Now open the interactive shell and create your first table. The shell speaks plain SQLite-flavored SQL, and .quit exits when you are done.

turso db shell my-db

CREATE TABLE users (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  name TEXT NOT NULL,
  email TEXT UNIQUE
);

INSERT INTO users (name, email) VALUES ('Ava', '[email protected]');
INSERT INTO users (name, email) VALUES ('Ben', '[email protected]');

SELECT * FROM users;
.quit

If that output showed your two rows, you have a live cloud database. The shell is the fastest place to sketch schemas and test queries before you wire anything into code.

Where Do the Database URL and Auth Token Go?

They go in environment variables — never in your source code, and never in a committed file.

# Your database URL — looks like libsql://my-db-yourname.turso.io
turso db show my-db --url

# Create an authentication token for the database
turso db tokens create my-db

Put both values in a .env file as TURSO_DATABASE_URL and TURSO_AUTH_TOKEN, and add .env to your .gitignore before your first commit. A leaked database token is a leaked database: anyone with the token and URL gets full read and write access. If you are still fuzzy on keeping secrets out of repositories, a GitHub beginner guide covers .gitignore and safe commit habits from the ground up.

How Do You Query Turso From JavaScript?

Install @libsql/client, create a client from your two environment variables, and call execute().

npm install @libsql/client

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

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

await db.execute(
  "CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT, email TEXT UNIQUE)"
);

await db.execute({
  sql: "INSERT INTO users (name, email) VALUES (?, ?)",
  args: ["Ava", "[email protected]"],
});

const result = await db.execute("SELECT * FROM users");
console.log(result.rows);

Always use ? placeholders with an args array instead of string-interpolating values into SQL. It prevents SQL injection, and it is the same habit every database driver rewards.

If your app runs in a container, the same two environment variables and the same client code work unchanged — pass them with -e flags or a secrets manager. A Docker beginner guide shows the container side of that setup if you have not containerized an app before.

Which Turso SDK Package Should You Pick?

Pick by where your code runs. Turso's official docs split the choice four ways, and choosing wrong is the most common source of "it works locally but not deployed" confusion.

The simple rule: starting a local project, use @tursodatabase/database. Connecting over the network to Turso Cloud — including Node servers, Docker, Cloudflare Workers, and Vercel Edge — use @tursodatabase/serverless (or @libsql/client if you need an ORM, covered below).

How Do Embedded Replicas Work?

An embedded replica keeps a local copy of your Turso Cloud database inside your application: reads run against the local file in microseconds, and writes are sent to the cloud primary and reflected back. It is read-local, write-to-primary — not magic instant global writes.

This is the feature that makes Turso feel like SQLite again at scale. The official docs describe it as "especially useful for VMs or VPS deployments, and for mobile applications where stable connectivity is a challenge," because the app keeps working against its local copy even when the network hiccups. If you are deploying on a virtual server rather than serverless, a what is VPS hosting explainer covers the hosting side so the database choice makes sense in context.

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

const db = createClient({
  url: "file:replica.db",          // local file — reads always come from here
  syncUrl: process.env.TURSO_DATABASE_URL,   // remote primary — writes go here
  authToken: process.env.TURSO_AUTH_TOKEN,
  syncInterval: 60,                // pull remote changes every 60 seconds
});

// Pull the latest changes on demand (e.g. at startup, or every 5 minutes)
await db.sync();

const result = await db.execute("SELECT * FROM users"); // served locally

Three rules from the official docs decide whether embedded replicas fit your app. First, writes are sent to the remote primary by default — they are not written to the local file first (an offline: true option enables local writes). Second, your writes are readable immediately on the replica that made them (read-your-writes), while other replicas see the data at their next sync. Third, never open the local database file with another process while the replica is syncing — that can corrupt it.

Embedded replicas also have real limits. Serverless environments without a filesystem (like some edge runtimes) cannot use them at all. And sync bandwidth is page-level: one frame equals 4 kB, so a 1-byte row still syncs as a 4 kB write, and btree splits or dirty WAL restarts can sync more frames than you expect. For new projects that need sync, Turso now recommends Turso Sync (@tursodatabase/sync) instead — logical change-data-capture with explicit push()/pull(), which the docs say uses significantly less bandwidth than embedded replicas' page-level replication. If you containerize the app holding a replica, use a Docker volume for the local .db file so it survives container restarts.

How Do You Branch a Turso Database?

You create a new database from an existing one with --from-db. A branch is a completely separate database instance — ideal for testing a migration without touching production.

# Create "my-app-staging" as a copy of "my-app"
turso db create my-app-staging --from-db my-app

# It needs its own token (or a group token)
turso db tokens create my-app-staging

# Delete it when the experiment is over
turso db destroy my-app-staging

Branches are a development workflow feature, not a backup strategy. The official docs are explicit: branches are fully separate databases, you must create a new token for the branch, you merge schema changes back manually with a migration tool, and you must delete the branch yourself when you are done. Branches also count toward your plan's database quota, so a forgotten staging branch quietly eats your free-tier database allowance.

The natural automation is one database per pull request: a GitHub Action calls the Turso Platform API on every new branch, tests run against the clone, and the branch database is destroyed on merge. Point-in-time restore uses the same machinery — you can branch from a snapshot, not just from the live database.

How Do You Use Drizzle With Turso?

Pair @libsql/client with Drizzle's libSQL driver. Turso's own docs name @libsql/client as the package for ORM integration with Drizzle and Prisma, and Drizzle is the native-feeling choice here.

npm install @libsql/client drizzle-orm

import { createClient } from "@libsql/client";
import { drizzle } from "drizzle-orm/libsql";

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

const db = drizzle(client);
// now use db.select(), db.insert(), and drizzle-kit migrations

Prisma works too — it is the comparison path, not the primary one — but the field's guides and Turso's own docs consistently reach for Drizzle first with libSQL databases. If you need a different SQL dialect later, that is the signal to re-read the next section.

Turso vs Supabase: Which Should You Choose?

Choose by database engine: Turso is SQLite-compatible, Supabase is Postgres. If your data model fits SQLite (single-file semantics, relational, moderate write concurrency), Turso gives you edge distribution with almost no operational weight. If you need Postgres features — advanced types, full-text search at scale, row-level security, the Supabase auth/storage/realtime stack — choose Supabase.

The October 2026 acquisition softens the rivalry rather than sharpening it. Supabase's stated plan is that Turso keeps running on SQLite while Supabase keeps building around Postgres, with a graduation path from a lightweight Turso database into standard Postgres "when SQLite isn't enough." Starting on Turso today does not paint you into a corner — it buys you the cheapest possible start with a named upgrade route. For the other side of the comparison, a Supabase beginner guide walks the Postgres backend path step by step.

Turso vs PlanetScale: Which Should You Choose?

Choose by SQL dialect and ecosystem. PlanetScale is a serverless MySQL (Vitess-based) platform with its own branching model (pscale branch create), while Turso is SQLite-based with turso db create --from-db branching. If your team thinks in MySQL or you are migrating a MySQL app, PlanetScale is the natural lane; if you want SQLite's zero-friction developer experience with global reach, Turso is. Both give you branch-per-PR workflows — the syntax differs, the idea is the same.

What Does Turso Cost? The Free Tier, Honestly

The free tier is genuinely usable for side projects: $0, no credit card, 100 databases, 5 GB of storage, 500 million rows read and 10 million rows written per month, 3 GB of embedded-replica syncs, and 1 day of point-in-time restore. These figures are from turso.tech/pricing as verified on 2026-10-11 — older guides quote conflicting numbers (9 GB storage, 25 billion or 25 million reads), so trust the pricing page, not the blog posts.

Three billing facts beginners miss. First, "rows read" counts every row touched while producing a response, not just rows returned — an unindexed lookup that scans a whole table counts the whole table, so indexes are the cheapest optimization on Turso. Second, overages are opt-in on paid plans; on the free plan, hitting any single limit blocks the database until you upgrade. Third, branching and point-in-time restores add no usage cost themselves, but every branch consumes your storage quota and counts as one of your databases.

What Are the Beginner Mistakes to Avoid?

Sources

• Turso CLI quickstart — install (brew install tursodatabase/tap/turso), turso auth signup, the two engines (Turso Database vs libSQL), turso db create my-db --tursodb, turso db show, turso db shell, .quit: docs.turso.tech/quickstart (checked 2026-10-30)
• Turso TypeScript quickstart — @tursodatabase/database (local/embedded), @tursodatabase/sync (push/pull), @tursodatabase/serverless (fetch-only remote, /compat module), @libsql/client (remote libSQL + ORM integration with Drizzle/Prisma), turso db show --url, turso db tokens create, TURSO_DATABASE_URL/TURSO_AUTH_TOKEN env vars: docs.turso.tech/sdk/ts/quickstart (checked 2026-10-30)
• Embedded replicas docs — reads from the local file in microseconds, writes sent to the remote primary (not written locally first), read-your-writes, syncUrl/syncInterval, await client.sync(), offline: true option, do-not-open-file-during-sync warning, filesystem-less runtimes unsupported, 1 frame = 4 kB: docs.turso.tech/features/embedded-replicas (checked 2026-10-30)
• Branching docs — branches are separate databases created from an existing database or point-in-time snapshot, new token or group token required, merge manually with a migration tool, delete manually, count toward the database quota: docs.turso.tech/features/branching (checked 2026-10-30)
• Turso branching blog — turso db create my-new-db --from-db my-existing-db via CLI and the Platform API for GitHub Actions branch workflows: turso.tech/blog/create-a-database-branch-with-github-actions-07bbf804 (checked 2026-10-30)
• Turso pricing — plan table, rows-read/rows-written metering (rows touched, not rows returned), overage opt-in, free plan blocked at quota, branching and point-in-time restore add no usage cost: turso.tech/pricing (checked 2026-10-30)
• Turso pricing, free tier figures — $0, 100 databases, 5 GB storage, 500M rows read/month, 10M rows written/month, 3 GB syncs/month, 1-day point-in-time restore, no credit card; prices verified against turso.tech/pricing on 2026-10-11: aibizhub.io/articles/turso-pricing (checked 2026-10-30)
• Turso llms.txt — Turso Database as a ground-up SQLite rewrite (MVCC concurrent writes, async I/O), package selection guidance, turso db destroy command: turso.tech/llms.txt (checked 2026-10-30)
• Supabase-Turso acquisition — announced October 2, 2026; Supabase raised $150M led by GIC; "Turso keeps running, databases, APIs, and workflows continue as they do today"; founder Glauber Costa becomes Head of Agentic Services; Turso continues on SQLite, Supabase on Postgres: verdict.co.uk and beri.net (checked 2026-10-30)
• Cloudflare Workers + Turso integration docs — CLI install commands, turso auth login, turso db create with automatic closest-location selection, turso db shell, turso db show --url, turso db tokens create: developers.cloudflare.com (checked 2026-10-30)
• Koyeb Turso + Drizzle tutorial — full Turso + Drizzle ORM + Express walkthrough, libsql:// URL and token via environment variables: koyeb.com/tutorials (checked 2026-10-30)

Frequently Asked Questions

Is Turso really free?

Yes, for real projects up to a point. The free tier costs $0 with no credit card and includes 100 databases, 5 GB of storage, 500 million rows read and 10 million rows written per month, plus 3 GB of embedded-replica syncs. The catch: exceeding any single limit blocks your databases until you upgrade, so it fits side projects and prototypes, not busy production apps.

Is Turso just SQLite in the cloud?

Close, but with two important upgrades. Turso Cloud hosts libSQL (an open-source SQLite fork) and the Turso Database engine, a ground-up SQLite rewrite with concurrent writes via MVCC and async I/O — plain SQLite allows only one writer at a time. On top of that you get edge replication, embedded replicas, and branching, which vanilla SQLite never had.

Does Turso work offline?

Partly. Embedded replicas keep serving reads from the local file without a connection, and an offline: true option lets the app write locally too — but writes normally go to the cloud primary, and sync needs connectivity. For fully offline-first apps with two-way sync, Turso Sync (@tursodatabase/sync) with explicit push/pull is the designed path.

Did Supabase buy Turso? Should I worry?

Supabase agreed to acquire Turso on October 2, 2026, and both companies say existing users see no change: Turso keeps running, Turso Database stays open source, and Turso keeps working on SQLite while Supabase keeps building around Postgres. The stated future is a graduation path from Turso into standard Postgres "when SQLite isn't enough" — starting on Turso today does not trap you.

When should I pick Turso over Postgres?

Pick Turso when your workload is SQLite-shaped: relational data, moderate write concurrency, a strong need for global low-latency reads, or many small databases (per tenant, per agent, per branch) that would be wasteful as full Postgres instances. Pick Postgres (via Supabase or elsewhere) when you need advanced types, heavy analytics, row-level security, or a full backend stack around the database.