Turso runs libSQL (a SQLite fork) at the edge with embedded replica support. UUID v7 TEXT primary keys work natively with Turso’s SQLite storage — lexicographic order equals insertion order for efficient range scans. See UUID v7 in Turso for the implementation guide.
libsql client insert with UUID v7
import { createClient } from '@libsql/client';
import { v7 as uuidv7 } from 'uuid';
const client = createClient({
url: process.env.TURSO_DATABASE_URL!,
authToken: process.env.TURSO_AUTH_TOKEN!,
});
async function createOrder(customerId: string, total: number) {
const id = uuidv7(); // UUID v7 — time-ordered, replica-safe
await client.execute({
sql: 'INSERT INTO orders (id, customer_id, total) VALUES (?, ?, ?)',
args: [id, customerId, total],
});
return id;
}
Cursor pagination
async function listOrders(cursor?: string, limit = 20) {
const result = cursor
? await client.execute({
sql: 'SELECT id, total, status FROM orders WHERE id > ? ORDER BY id LIMIT ?',
args: [cursor, limit],
})
: await client.execute({
sql: 'SELECT id, total, status FROM orders ORDER BY id LIMIT ?',
args: [limit],
});
const items = result.rows;
const nextCursor = items.length === limit ? String(items.at(-1)?.id) : null;
return { items, nextCursor };
}
Further reading
External references
Frequently asked questions
How do I use UUID v7 as a primary key in Turso?
Turso uses SQLite under the hood. Store UUID v7 as TEXT: CREATE TABLE orders (id TEXT PRIMARY KEY). Insert with the @libsql/client package: client.execute({ sql: "INSERT INTO orders (id) VALUES (?)", args: [uuidv7()] }). UUID v7 lexicographic order enables WHERE id > cursor ORDER BY id pagination. See UUID v7 in Turso for the full guide.
Does UUID v7 work with Turso embedded replicas?
Yes. Turso embedded replicas sync a local SQLite file from the remote libSQL server. UUID v7 IDs generated locally before a network write are unique across all replicas — the 74 random bits prevent collisions even when multiple replicas write simultaneously. The time-ordered prefix ensures recently written records sort correctly after sync. See UUID in SQLite.
How does UUID v7 compare to Turso's default rowid?
Turso (SQLite) uses a 64-bit integer rowid by default — monotonic but not globally unique across replicas. UUID v7 as a TEXT primary key is globally unique with 74 random bits, time-ordered at millisecond granularity, and safe across any number of replica writers without coordination. The trade-off is 36 bytes vs 8 bytes per key.