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.