Docs / SDK reference / Database

Database

Server-only. flarelink.from(table) returns a chainable that resolves on await. It needs the service key (or, on Cloudflare Workers, a D1 binding), so it only works where those are safe — your server, never the browser. Every result has the same shape:

{
  rows: T[],
  meta: { duration, rows_read?, rows_written?, last_row_id?, changes? },
}

Query builder

// SELECT — * is the default, .select() narrows
const { rows: users } = await flarelink
  .from<User>("users")
  .select(["id", "email", "active"])
  .where({ active: true })          // equality + AND, NULL → IS NULL
  .orderBy("created_at", "desc")
  .limit(20)
  .offset(40)

// INSERT (single, multi, with RETURNING)
await flarelink.from("users").insert({ email: "a@b.com", name: "A" })
const { rows: created } = await flarelink
  .from<User>("users")
  .insert([{ email: "a@b.com" }, { email: "c@d.com" }])
  .returning("*")

// UPDATE
await flarelink.from("users").update({ active: false }).where({ id: 42 })

// DELETE
await flarelink.from("users").delete().where({ id: 99 })

The builder is immutable — each method returns a fresh object, so it's safe to compose partial queries and branch off them. Awaiting is the terminal step that fires the request.

Raw SQL escape hatch

For IN (…), ranges (> / < / LIKE), OR, joins, transactions — use the tagged template. Interpolated values become bind params; there's no way for a value to inject SQL.

const { rows: top } = await flarelink.sql<{ email: string; n: number }>`
  SELECT email, count(*) AS n
  FROM events
  WHERE created_at > ${cutoff}
  GROUP BY email
  ORDER BY n DESC
  LIMIT 10
`

A flarelink.sql\`…\` call runs as a single D1 batch, so a multi-statement template (BEGIN; …; COMMIT;) is atomic. The values you interpolate are coerced for D1's bind contract: null/undefined → null, primitives pass through, objects/arrays are JSON.stringify'd for you.

On Cloudflare Workers? Query the binding directly v0.3+

If your app is itself a Cloudflare Worker, pass your D1 binding as d1 and the same flarelink.from(...) / flarelink.sql calls run straight against it — no HTTP hop to the auth Worker, and no service key needed for the database:

const flarelink = createFlarelink({
  url: env.FLARELINK_URL,
  serviceKey: env.FLARELINK_SERVICE_KEY, // still used for storage + auth
  d1: env.DB,                            // ← db now runs on the binding
})

Same query builder, same identifier safety, same { rows, meta } — only the transport changes. Bind the same D1 your auth Worker uses (so user_id foreign keys resolve), and set "remote": true on the binding so wrangler dev uses the real remote D1. Without d1, db calls fall back to the HTTP transport gated by the service key — so the identical code is portable to non-Cloudflare hosts.

Limits & gotchas

Builder .where() supports equality + AND only. Anything more dynamic (IN, ranges, OR, joins) goes through flarelink.sql\`…\`.
Identifiers (table + column names) must match /^[A-Za-z_][A-Za-z0-9_]*$/ — anything else throws INVALID_IDENTIFIER before the request is sent.
Flarelink's auth tables share the same D1: user, account, verification, flarelink_config. Avoid those names for your own tables — you can read them like any other (flarelink.from('user')), but the dashboard locks writes to them.
All queries hit the single D1 bound to your auth Worker. Multi-D1 routing and browser-side queries with row-level security are deferred — see Architecture.
No batch([...]) API yet; use flarelink.sql\`…\` for multi-statement transactions. Errors are typed — see Error reference.

Need to create the tables you're querying? See Your schema & migrations.

Something unclear or missing? hello@flarelink.dev llms-full.txt ↗