Telnyx Storage: SQL (Beta) — Full Documentation

Complete page content for SQL (Beta) (Storage section) of the Telnyx developer docs (https://developers.telnyx.com). Root index: https://developers.telnyx.com/llms.txt · Lightweight index for this subsection: https://developers.telnyx.com/development/llms/storage-sql-llms-txt.md

Get Started

SQL Databases

Source: https://developers.telnyx.com/docs/edge-compute/sqldb.md

A SQL database is a SQLite database that lives on its own, outside any function. Create it once, bind it by id, and query it as env.DB from as many functions as need it — or from the CLI and REST API without deploying anything at all. There is no server to size and nothing to deploy per database. Every path reaches the same data through one primary, so writes serialize and there is no replica lag to reason about.

Two Ways to Reach a Database

The same database is reachable two ways. Pick based on where the code runs.

	`env` binding	REST API and CLI
Where	Inside an edge function — TypeScript only	Anywhere — any language, any host, no function required
Auth	Injected by the runtime; no API key in your code	Your `TELNYX_API_KEY` as a bearer token
Shape	`env.DB.prepare(sql).bind(...).all()`	`POST https://api.telnyx.com/v2/storage/sqldbs/{id}/actions/query`, `telnyx-edge storage sqldb execute`
Use it for	Reads and writes on the request path	Creating databases, applying schema and migrations, backfills, one-off inspection — SQL you wrote yourself, since this path has no parameter binding

A row written by a function is visible to the next CLI query, and a table created from the CLI is visible to the next request. That is what lets schema exist before any code does: create the database, apply migrations, then ship a function that binds it.

SQL Databases vs Per-Actor SQL

Stateful Actors also have SQLite, at ctx.storage.sql. Both surfaces are SQLite, which is where the confusion starts. They solve different problems.

	SQL Database (`env.DB`)	Actor SQL (`ctx.storage.sql`)
Scope	One database, shared by the functions that bind its id	One private database per actor instance
Reached from	Any bound function, the CLI, the REST API	Only from inside that one actor instance
API shape	Async — `await env.DB.prepare(sql).bind(...).all()`	Synchronous — `ctx.storage.sql.exec(sql, ...)` returns a cursor
Use it for	Application data more than one caller reads: catalogs, links, accounts, anything an operator also needs to query	State owned by a single entity — a room, a session, a device — where the actor itself is the lock

A per-actor database cannot be queried from outside its actor and cannot join across instances; there is no CLI or REST path to it. A SQL database can be queried from anywhere, but no caller gets exclusive access to it — concurrent callers interleave, and correctness across statements comes from batch(), not from holding the database. Explicit BEGIN is rejected on both surfaces; the runtime owns transaction boundaries.

Next Steps

Quick Start — Create a database, apply a schema, bind it, query it
How SQL Databases Work — The single primary, sharing, and what durability means today
Migrations — Versioned schema changes with storage sqldb migrations
Runtime API — The env binding surface (SqlDatabase)
CLI Commands — Create, inspect, and query databases from the terminal
Limits — Size and duration ceilings, and known gaps

Bindings — How the env binding surface works
Stateful Actor SQL — The private, per-instance SQLite database
KV — Key-value storage for read-heavy lookups
CLI reference — The full telnyx-edge command surface

Quick Start

Source: https://developers.telnyx.com/docs/edge-compute/sqldb/quick-start.md

Prerequisites

The telnyx-edge CLI, authenticated (telnyx-edge auth api-key set <YOUR_API_KEY>), on a release that includes storage sqldb.
A Telnyx API key, if calling the REST API directly.
An Edge Compute function project with a telnyx.toml (or func.toml) manifest, and Node.js for npm.

1. Create a Database

A database is an isolated SQLite database with its own schema. Create one with the CLI or the API.

telnyx-edge storage sqldb create --name my-app-db

curl -X POST https://api.telnyx.com/v2/storage/sqldbs \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-app-db"}'

The response carries the database id — a UUID, and the only durable handle. Names are not resolution keys:

{
  "data": {
    "record_type": "storage_sqldb",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "my-app-db",
    "status": "pending",
    "created_at": "2026-07-29T14:52:03Z",
    "updated_at": "2026-07-29T14:52:03Z"
  }
}

A name may contain lowercase letters, numbers, and hyphens, and must be unique within the organization — a duplicate returns 409, and the API rejects an empty or upper-case name with 422 (the CLI stops an empty name before any request is made). Hyphen placement is not constrained — a leading hyphen is accepted — but avoid one: that name then reads as a flag when passed to CLI commands, so you are left addressing the database by id. Keep names short: past 255 characters the create fails with a 500 instead of a validation error. A new database starts at status: "pending". SQL sent to it from outside a function — execute, migrations, or the REST query endpoint — returns 409 ("Database is not ready (status: pending)") until provisioning finishes, typically in 2 to 11 seconds. If scripting, poll until the status is provision_ok rather than sleeping a fixed interval:

telnyx-edge storage sqldb get 550e8400-e29b-41d4-a716-446655440000
# or
curl https://api.telnyx.com/v2/storage/sqldbs/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer $TELNYX_API_KEY"

2. Create the Schema

Create your tables from the terminal, before any code exists. execute takes exactly one of --command or --file, and --remote is required — there is no local emulation.

telnyx-edge storage sqldb execute 550e8400-e29b-41d4-a716-446655440000 --remote \
  --command "CREATE TABLE links (
    id INTEGER PRIMARY KEY,
    slug TEXT NOT NULL UNIQUE,
    target TEXT NOT NULL,
    created_at TEXT NOT NULL DEFAULT (datetime('now'))
  )"
# ✓ Statement executed — no rows returned

Longer schemas belong in a file. The file is submitted as one multi-statement script — the engine splits it, the CLI does not:

telnyx-edge storage sqldb execute 550e8400-e29b-41d4-a716-446655440000 --remote --file schema.sql

Add --json to get the raw result object instead of the rendered table. For scripting note one wrinkle: the current CLI writes the JSON to stderr, so capture it with 2>&1 >/dev/null rather than piping stdout. execute is for one-off statements and inspection. For schema changes intended to be kept and replayed on another database, use Migrations — numbered .sql files with a tracking table inside the database itself.

3. Bind the Database to a Function

Declare the database in the function’s manifest. The manifest itself — and the [edge_compute] identity in it — comes from the function, not from this guide: telnyx-edge new-func registers the function and writes func_id when it scaffolds a project. Starting from nothing, run telnyx-edge new-func -n links-api -l ts first and work in the project it creates (it writes a classic func.toml; for the umbrella telnyx.toml form shown here, copy the generated [edge_compute] block across). The only part this step adds is the [storage.sqldb.DB] block. The example below is a telnyx.toml; the [storage.sqldb.<NAME>] block parses the same way in a func.toml project, though a classic func.toml project’s entry point has a different shape from the export default { fetch } handler in step 5:

name = "links-api"
main = "src/index.ts"
compatibility_date = "2026-05-14"

[storage.sqldb.DB]
id = "550e8400-e29b-41d4-a716-446655440000"  # Database ID from step 1

[edge_compute]
func_id = "<written by new-func — do not edit>"
func_name = "links-api"

The block key — DB here — is a name of your choosing, and it is what the code sees on env: this manifest produces env.DB. It must be a valid identifier (letters, digits, underscores; no leading digit, no __) and unique across every binding in the manifest. id must be the database UUID. Binding by name, or creating a database from the manifest, is rejected before deploy. Declare as many [storage.sqldb.<NAME>] blocks as needed; two bindings that carry different ids are two different databases, and neither can see the other’s tables.

4. Generate Types

npm install @telnyx/edge-runtime   # 0.9.0 or newer — the first release exporting SqlDatabase
telnyx-edge types                  # writes telnyx-env.d.ts
# env.DB → SqlDatabase

telnyx-edge types reads the manifest — plus the @telnyx/edge-runtime version declared in package.json — and nothing else: it runs offline and needs no authentication. Re-run it after adding, renaming, or removing a binding. Types are for the compiler only. The binding itself resolves at runtime from the manifest, so a stale telnyx-env.d.ts does not change what the deployed function sees — in either direction.

5. Write the Function

Bindings live on the env imported from @telnyx/edge-runtime — not on the second argument to fetch(req, env). Reading env.DB off that argument type-checks cleanly and is undefined at runtime.

import { env } from "@telnyx/edge-runtime";

type Link = { id: number; slug: string; target: string };

export default {
  async fetch(req: Request): Promise<Response> {
    if (req.method === "POST") {
      const { slug, target } = (await req.json()) as { slug: string; target: string };

      // RETURNING hands back the generated id
      const inserted = await env.DB.prepare(
        `INSERT INTO links (slug, target) VALUES (?, ?) RETURNING id`,
      )
        .bind(slug, target)
        .run<{ id: number }>();

      return Response.json({ id: inserted.results[0]!.id }, { status: 201 });
    }

    const slug = new URL(req.url).searchParams.get("slug");

    const { results } = slug
      ? await env.DB.prepare(`SELECT id, slug, target FROM links WHERE slug = ?`)
          .bind(slug)
          .all<Link>()
      : await env.DB.prepare(
          `SELECT id, slug, target FROM links ORDER BY id DESC LIMIT 20`,
        ).all<Link>();

    return Response.json({ links: results });
  },
};

prepare() is synchronous and returns a statement. .bind() returns a new statement with the values attached — it never mutates the one it was called on. The terminal calls are async, and each resolves to a different shape: run() and all() give { results, success, meta }, first() gives a single row or null (first("col") gives that column’s value), and raw() gives an array of value-arrays. run() and all() are the same call: both return rows, including the rows a RETURNING clause produces. Bind every value that comes from a request with ? placeholders rather than building SQL by concatenation. Ordered ?NNN placeholders work too. A failing statement — a syntax error, a UNIQUE violation, a missing table — rejects with a plain Error. There is no typed error class or error-code taxonomy: the SQLite message is nested inside a longer transport string on error.message.

6. Ship and Call It

telnyx-edge ship

ship bundles the project, uploads it, and prints the function host — {func-name}-{func-id-prefix}.telnyxcompute.com, without a scheme; add https:// when calling it.

B=https://links-api-<func-id-prefix>.telnyxcompute.com

curl -sS -X POST $B -H 'content-type: application/json' \
  -d '{"slug":"docs","target":"https://developers.telnyx.com"}'
# → {"id":1}

curl -sS $B
# → {"links":[{"id":1,"slug":"docs","target":"https://developers.telnyx.com"}]}

curl -sS "$B?slug=docs"
# → {"links":[{"id":1,"slug":"docs","target":"https://developers.telnyx.com"}]}

7. Query It Without Deploying

The rows the function wrote are readable from the terminal against the same database:

telnyx-edge storage sqldb execute 550e8400-e29b-41d4-a716-446655440000 --remote \
  --command "SELECT id, slug, target FROM links ORDER BY id DESC LIMIT 5"

The CLI renders the rows as a table followed by a row count. This is the same database the function holds on env.DB, reached through the same primary — the CLI is not a second writer, and no schema or data is duplicated. Use it to inspect state, apply a fix-up statement, or seed a table without redeploying.

8. Query It From Any Language

The CLI is a wrapper over one HTTP endpoint. Anything that can make a request can reach the same database — a Go or Python function, a backfill script, a CI job:

curl -sS -X POST \
  https://api.telnyx.com/v2/storage/sqldbs/550e8400-e29b-41d4-a716-446655440000/actions/query \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sql": "SELECT id, slug FROM links ORDER BY id DESC LIMIT 5"}'

{ "data": { "results": [ { "id": 2, "slug": "home" }, { "id": 1, "slug": "docs" } ] } }

The body takes exactly one key, sql. Any other key — including params — is rejected with 400 Invalid request body. The response carries results and nothing else: no meta, no row counts, no duration. A script may hold several ;-separated statements, and the rows returned are the last statement’s. This endpoint has no parameter binding. There is no way to send values separately from the statement, so any value that varies has to be written into the SQL text itself. Never interpolate a string that came from a request, a user, or any other untrusted source into a statement sent this way — that is a SQL injection, and the endpoint gives you nothing to defend with. Use this path for schema, migrations, backfills, and inspection, where the SQL is written by you and fixed in advance. For request-path queries whose values come from callers, use a TypeScript function and the env binding, where prepare().bind() keeps the statement and the data separate. Binary columns come back as JSON arrays of byte values ([9, 8, 7]), not base64. Errors arrive in the standard Telnyx envelope: a SQL failure is a 422 whose detail embeds the SQLite message inside the same longer transport string described in step 5, a database that has not finished provisioning is a 409, and an unknown or other-organization id is a 404.

Next Steps

How SQL Databases Work — the shared-database model, consistency, and what env.DB is talking to
Migrations — numbered .sql files and the in-database tracking table
Runtime API — the full SqlDatabase surface, including batch() and exec()
CLI Commands — create, list, get, delete, execute, migrations
Limits — database and value size, bound parameters, and query performance
Bindings — how the env binding surface works across storage products

Concepts

How SQL Databases Work

Source: https://developers.telnyx.com/docs/edge-compute/sqldb/concepts/how-sqldb-works.md

A SQL database is stock SQLite, addressed by UUID, living outside any function. Everything in the model follows from one property: a database has exactly one primary, and every caller goes through it.

A Database Is a Standalone Resource

Create a database with the CLI or the REST API and it comes back immediately with status pending; it reaches provision_ok a few seconds later — typically 2 to 11, since provisioning is picked up by a poll loop rather than done inline. A query issued while it is still pending returns HTTP 409 Database is not ready. In a script, poll get until the status is provision_ok rather than sleeping a fixed interval. The UUID is the only durable handle. A telnyx.toml binding takes an id, never a name:

[storage.sqldb.DB]
id = "0198c2c5-8f1e-7a3d-9b21-6e4a0d5f1c88"

The name is a label, unique within the organization, matching ^[a-z0-9-]+$. It exists so humans can find a database in a list; the CLI resolves a name to an id locally as a convenience, while REST calls and manifests take the id. There is no rename, and deleting a database frees its name for a new, empty database with a different id. Nothing is deployed per database, and nothing about a database is derived from a function. Shipping, rolling back, or deleting a function does not touch the data. The engine is stock SQLite — 3.51.3 in production today — so the dialect and the built-in functions are SQLite’s, not a subset invented for the edge. Foreign keys are on and enforced, which is worth knowing if you are arriving from a SQLite build that leaves them off: a REFERENCES violation fails the statement.

One Primary, Serialized Writes

Today every read and every write for a given database funnels through a single primary, so a caller never contends with a second writer: not another region, not a replica, not a second connection opened by a different caller. That is the current topology rather than a promise about future ones; what you can design against is that statements against one database are serialized, and that every access path sees the same data. Two consequences, both worth designing around:

Writes are serialized. Concurrent writers queue behind one another instead of contending for the database. Lost-update anomalies are still possible at the application level — two callers that each read, compute, and write can still clobber each other — which is what batch() exists for.
Statements run one at a time. The database is single-threaded. A slow statement occupies it and other callers wait behind it. That is the cost of the property above.

Keep statements bounded. A simple SELECT 1 round-trips in about 10 ms warm and a 5,000-row read in about 160 ms, so the cost that matters is the one a slow statement imposes on everything queued behind it. Long analytical scans belong in a warehouse, not here — see Limits. Indexes matter for the same reason they matter in any SQLite deployment, and more so because the cost is paid by every other caller:

CREATE INDEX IF NOT EXISTS links_by_slug ON links(slug);

Two Access Paths, One Database

A database is reachable from inside a function through its binding, and from outside through REST or the CLI. These are not two systems kept in sync — both run against the same primary.

	`env` binding	REST API and CLI
Where	Inside a TypeScript edge function	Anywhere; no function needs to exist
Auth	Injected by the runtime	`TELNYX_API_KEY` bearer token
Entry point	`env.DB.prepare(sql)`, `.batch()`, `.exec()`	`POST /v2/storage/sqldbs/{id}/actions/query`, `telnyx-edge storage sqldb execute`
Typical use	Reads and writes on the request path	Schema, migrations, backfills, inspection — SQL you wrote yourself, since this path has no parameter binding

Visibility between them is immediate and needs no coordination. A row inserted by a function is returned by the very next sqldb execute; a table created by sqldb execute is visible to the next request that runs. That is what makes schema management work before any code exists: create the database, apply migrations from a terminal, then ship a function that binds it. Inside a function the binding is read off the env imported from @telnyx/edge-runtime, not off the second argument to fetch(request, env). That argument does not carry storage bindings, so env.DB read from it is undefined at runtime even though it type-checks. Requires @telnyx/edge-runtime 0.9.0 or later.

import { env } from "@telnyx/edge-runtime";

export default {
  async fetch(request: Request): Promise<Response> {
    const { results } = await env.DB
      .prepare("SELECT url FROM links WHERE slug = ?")
      .bind(new URL(request.url).pathname.slice(1))
      .all<{ url: string }>();

    return results.length
      ? Response.redirect(results[0].url, 302)
      : new Response("not found", { status: 404 });
  },
};

A database is not owned by the function that first wrote to it. Any number of functions can declare a binding to the same id, and each one sees the same tables and the same rows. The binding name is a local alias, declared per function. One function can call the database DB and another can call the same id SHARED; both statements land in the same place.

# links-api/telnyx.toml
[storage.sqldb.DB]
id = "0198c2c5-8f1e-7a3d-9b21-6e4a0d5f1c88"

# analytics-worker/telnyx.toml
[storage.sqldb.SHARED]
id = "0198c2c5-8f1e-7a3d-9b21-6e4a0d5f1c88"

Because the alias is local, nothing in the schema records which function created a table. Coordination between functions is ordinary database work: agree on a schema, own it in migrations, and use batch() where a sequence has to be atomic. The id is validated when a function ships. An id that does not exist, belongs to another organization, or is not yet provision_ok fails the deploy rather than producing a function with a dead binding — though the failure currently surfaces as a generic API error (HTTP 500) that never names the binding, so if a ship starts failing right after a [storage.sqldb] edit, re-check the id and the database’s status before believing the retry-later advice. The check reads the database record rather than opening a connection, so it is not a promise that the first query will succeed — only that the id resolves to a database this organization owns.

Isolation

Isolation runs along two lines, both enforced by the platform rather than by convention.

Database to database. Two bindings in the same function are two separate databases. env.DB cannot see env.DB2’s tables and env.DB2 cannot see env.DB’s — each direction fails with no such table. There is no cross-database query: each statement addresses exactly one id, and one database cannot be joined to another.
Organization to organization. A database belongs to the organization that created it. An id from another organization returns 404 — the same response as an id that never existed, so existence cannot be probed. A function can only ever reach its own organization’s databases.

Consistency and Durability

Because there is one primary and no replicas, consistency is the simple kind:

A write that resolves has committed. When all(), run(), batch(), or exec() resolves without throwing, the transaction has committed on the primary and every later reader sees it.
Reads reflect prior writes. Both access paths reach the same primary, so there is no replica lag to design around and no eventual-consistency window between the function path and the REST path.
Data outlives functions. Rows written before a deploy are there after it — across redeploys of the functions that bind the database, across CLI and REST sessions, and across the creation of other databases in the same organization.

Deletion is asynchronous: for a few seconds the record reports status: deleting — queries return 409 and the name is still held — and then the id turns 404 and the name frees. Re-creating the same name after that produces a new, empty database under a new id, so poll get until the 404 before re-creating. Keep the schema in version-controlled migration files.

Choosing Between SQL, KV, and Per-Actor SQLite

Three storage surfaces, three different scopes. They can be used together in one application.

	SQL Database	KV	Per-actor SQLite
Data model	Relational tables, full SQL	Key to opaque bytes	Relational tables, full SQL
Scope	One dataset shared by every function bound to its id	One namespace in a single global store	One private database per actor instance
Reached from	Any bound function, the CLI, the REST API	Any function, the CLI, the REST API	Only inside that one actor instance
Call shape	`await env.DB.prepare(...).all()`	`await env.KV.get(key)`	`ctx.storage.sql.exec(...)` — synchronous
Concurrency	One primary; statements serialized	Last-write-wins per key	The actor instance is the lock
Reach for it when	Data is relational and more than one caller reads it	Lookups are by key and reads dominate	State belongs to one entity and nothing else reads it

The distinction that catches people is the last column. Per-actor SQLite is the same engine but a private database per instance — it cannot be queried from the CLI, cannot be joined across instances, and has no REST path. A SQL database is the opposite: queryable from anywhere, but no caller ever holds it exclusively.

Quick Start — Create a database, apply a schema, bind it, query it
Runtime API — The SqlDatabase binding surface method by method
Type Conversion — What bind() accepts and what queries hand back
Migrations — Versioned schema changes
Limits — Size and duration ceilings, and known gaps
Bindings — How env bindings resolve
Stateful Actor SQL — The private, per-instance SQLite database

Migrations

Source: https://developers.telnyx.com/docs/edge-compute/sqldb/migrations.md

A migration is a numbered .sql file on disk. telnyx-edge storage sqldb migrations creates those files, applies the ones that have not run yet, and records what it applied — in a table inside the database, not in a state file beside your code. Three commands cover the whole workflow:

Command	What it does	Network
`migrations create <database> <name>`	Writes a new numbered file	None — fully offline
`migrations list <database> --remote`	Marks each local file `pending` or `applied`	Reads the database
`migrations apply <database> --remote`	Runs every pending file, in order	Writes the database

--remote is required on list and apply. There is no local database to run against — local execution is not supported, and there is no --local flag. create is the exception: it only writes a file, so it needs no authentication and no network.

A Worked Example

Start with a provisioned database named links-db. Create the first migration:

telnyx-edge storage sqldb migrations create links-db create_links

✓ Created migrations/links_db/0001_create_links.sql

The file is a stub with a header comment. Fill in the schema:

-- Migration 0001_create_links.sql

CREATE TABLE links (
  id   INTEGER PRIMARY KEY,
  slug TEXT NOT NULL UNIQUE,
  url  TEXT NOT NULL
);

Add a second migration the same way:

telnyx-edge storage sqldb migrations create links-db add_click_count

✓ Created migrations/links_db/0002_add_click_count.sql

-- Migration 0002_add_click_count.sql

ALTER TABLE links ADD COLUMN clicks INTEGER NOT NULL DEFAULT 0;
CREATE INDEX links_by_slug ON links(slug);

Before applying, check what is outstanding:

telnyx-edge storage sqldb migrations list links-db --remote

MIGRATION                  STATUS
------------------------   --------
0001_create_links.sql      pending
0002_add_click_count.sql   pending

Apply them:

telnyx-edge storage sqldb migrations apply links-db --remote

✓ Applied 0001_create_links.sql
✓ Applied 0002_add_click_count.sql

2 migration(s) applied

list now reflects the new state:

MIGRATION                  STATUS
------------------------   --------
0001_create_links.sql      applied
0002_add_click_count.sql   applied

Running apply again does nothing — it only ever runs what is pending:

No pending migrations

The Ledger Lives in the Database

Applied state is tracked in a table called sqldb_migrations, created inside the database on the first apply:

CREATE TABLE IF NOT EXISTS sqldb_migrations (
  id         INTEGER PRIMARY KEY,
  name       TEXT NOT NULL,
  applied_at TEXT NOT NULL
)

Read it like any other table:

telnyx-edge storage sqldb execute links-db --remote \
  --command "SELECT id, name, applied_at FROM sqldb_migrations ORDER BY id"

applied_at             id    name
----------             ---   ----
2026-07-29T15:04:11Z   1     0001_create_links.sql
2026-07-29T15:04:12Z   2     0002_add_click_count.sql

2 row(s)

name is the filename, not the label — renaming a file after it has been applied makes it pending again.
applied_at is an RFC 3339 UTC timestamp generated by the CLI at apply time, so it reflects the clock of the machine that ran the command.
id is assigned by SQLite in apply order.

Because the ledger is a table in the database, there is no external state file to commit, share, or lose. Any checkout of the migration files, on any machine, sees the same applied set. Dropping the table makes every file pending again. list never creates the table — it is read-only, and treats a missing sqldb_migrations as “nothing applied yet”. Only apply creates it.

Apply Is Not All-or-Nothing

Each file is submitted as one script in one call: the migration body, then the INSERT into sqldb_migrations that records it. A script is applied atomically: if any statement in it fails, the whole script rolls back — a script that creates a table, inserts a row, and then hits a bad statement leaves no table behind. So a migration file either applies completely and is recorded, or changes nothing and is not recorded. There is no state in between for a single file. Across the batch there is no atomicity at all. If the third of five migrations fails, the first two stay applied and the command stops:

✓ Applied 0001_create_links.sql
✓ Applied 0002_add_click_count.sql
✗ 0003_add_owner.sql failed: ❌ API error (HTTP 422): Unprocessable Entity - actor invocation … {"error":"method_failed","message":"Error: duplicate column name: owner","name":"Error"}

The ✗ line relays the API error verbatim, so the SQLite message — duplicate column name: owner here — arrives embedded in a longer transport string rather than on its own. The command exits non-zero with an error that begins migration 0003_add_owner.sql failed after applying 2 migration(s):, followed by the same relayed API error. The database is left partway through the batch — schema changes from 0001 and 0002 are live, and 0003 is not recorded, so apply will try it again. Recover by fixing forward:

Run migrations list <database> --remote to see exactly where the batch stopped.
Correct the file that failed. It is still pending, and apply runs pending files in numeric order, so the next run reaches it before anything numbered after it — a later migration cannot reconcile around it. Edit that file until it succeeds, or empty it out if the change is no longer wanted.
Run apply --remote again. Only the still-pending files run, beginning with the one that failed.
Prefer statements that are safe to retry — CREATE TABLE IF NOT EXISTS, CREATE INDEX IF NOT EXISTS, INSERT OR IGNORE — because a retry re-runs the failed file from the top.

Never edit a migration that has already been applied. The ledger only knows the filename, so an edited file stays applied and its new contents never run. Nothing coordinates two apply runs against the same database. apply reads the ledger and then submits each pending file as its own call, so two runs started at the same time — two CI jobs, or a pipeline racing an operator — can both see a file as pending and run it twice. Run migrations from one place, and write them so that a second run is harmless. Foreign keys are on and enforced. A migration that rebuilds or drops a referenced table has to order its statements so no statement leaves a dangling reference — a foreign-key violation fails the file like any other error.

Files and Directories

create numbers files with a 4-digit zero-padded, auto-incrementing prefix (0001_, 0002_, …), taking the next number from the highest prefix already in the directory. The label is the name argument with every run of non-alphanumeric characters collapsed to _, and leading or trailing runs dropped. Files land in migrations/<database> by default, with the same collapsing applied to the database argument — links-db becomes migrations/links_db:

migrations/
└── links_db/
    ├── 0001_create_links.sql
    └── 0002_add_click_count.sql

Per-database directories keep two databases from sharing one file sequence. The directory name is derived from the argument as given, so passing the id to one command and the name to another points at two different directories — pick one form and use it consistently. Collapsing can also map two different names onto one directory: app-db and app--db both resolve to migrations/app_db. Give one of them an explicit --migrations-dir so their files stay apart. Override the location with --migrations-dir:

telnyx-edge storage sqldb migrations apply links-db --remote --migrations-dir ./db/migrations

Any file matching a numeric prefix, an underscore, and a .sql suffix is picked up, whatever the digit count. Files run in numeric-prefix order, then filename order.

Machine-Readable Output

apply --json always emits the same shape, including on a no-op run ({"applied": []}), and emits no JSON at all on failure. One wrinkle in the current CLI: the JSON — for apply and list both — is written to stderr, not stdout, so capture it with 2>&1 >/dev/null rather than piping stdout:

telnyx-edge storage sqldb migrations apply links-db --remote --json

{
  "applied": [
    "0001_create_links.sql",
    "0002_add_click_count.sql"
  ]
}

list --json emits one entry per local file:

[
  {
    "name": "0001_create_links.sql",
    "status": "applied"
  },
  {
    "name": "0002_add_click_count.sql",
    "status": "pending"
  }
]

CLI — the full storage sqldb command surface
Quick Start — create a database, bind it, query it
Limits — the ~4 MiB script ceiling and query duration
How SQL Databases Work — one primary per database

Reference

Overview

Source: https://developers.telnyx.com/docs/edge-compute/sqldb/reference.md

The types in this reference are exported from @telnyx/edge-runtime (TypeScript) and describe version ≥ 0.9.0 — the first release that exports SqlDatabase and wires the env binding. They describe the env binding, the in-function surface. Running SQL from outside a function — schema changes, ad-hoc queries, migrations — goes over a separate REST path, covered in the CLI reference. The SQL Databases Runtime API is a single binding type plus the statement and result types its methods return. A database declared as [storage.sqldb.<NAME>] in telnyx.toml resolves on env.<NAME> as a SqlDatabase.

Surface	Where it lives	What it’s for
`SqlDatabase`	`env.<BINDING>`	The binding handle — `prepare`, `batch`, `exec`.
`SqlPreparedStatement`	returned by `prepare()`	`bind()`, then one terminal: `first`, `run`, `all`, `raw`.
`SqlQueryResult<T>`	resolved by `run()`, `all()`, and each entry of `batch()`	`{ results, success, meta }` — the rows plus their envelope.
`SqlQueryResultMeta`	`SqlQueryResult.meta`	`duration`, `rows_read`, `rows_written`, `last_row_id`, `changes` — the statement’s own accounting.
`SqlExecResult`	resolved by `exec()`	`{ count, duration }` — how many statements ran. Returns no rows.

Getting the Binding

import { env } from "@telnyx/edge-runtime";

// env.DB is a SqlDatabase, from [storage.sqldb.DB] in telnyx.toml
const { results } = await env.DB
  .prepare("SELECT id, email FROM users WHERE id = ?")
  .bind(1)
  .all<{ id: number; email: string }>();

Read the binding off the imported env — not the env argument of fetch(request, env). The object handed to fetch carries actor bindings only: env.DB on it is undefined, and the call fails at runtime with Cannot read properties of undefined (reading 'prepare') even though it type-checks cleanly. The generated types deliberately declare the binding in both places, so the compiler will not catch this. Declaring the binding is covered in the Quick Start. The binding resolves at runtime from telnyx.toml; run telnyx-edge types after editing the manifest to regenerate telnyx-env.d.ts, which types env.<NAME> as a SqlDatabase. That command checks the @telnyx/edge-runtime version declared in package.json and fails with @telnyx/edge-runtime <version> does not export SqlDatabase (requires >= 0.9.0) when the floor is not met.

SqlDatabase — the method-by-method reference
Quick Start — create a database, bind it, query it
How SQL Databases Work — one primary per database, and what that means for consistency
Bindings — how bindings resolve on env
CLI — telnyx-edge storage sqldb for provisioning, ad-hoc SQL, and migrations
Limits — database and value size, bound parameters, and query performance
Stateful Actor SQL — a different product: the private embedded SQLite at ctx.storage.sql, visible to one actor instance only and called synchronously

SqlDatabase

Source: https://developers.telnyx.com/docs/edge-compute/sqldb/reference/sql-database.md

env.<BINDING> (a SqlDatabase) is the in-function handle to a SQL database. The runtime routes the call for you, so function code holds no API key. Every database is served by one primary that serializes writes, and the binding, the CLI, and the REST query endpoint all funnel through that same primary — a row written from a function is immediately readable from the CLI, and the reverse.

interface SqlDatabase {
  prepare(query: string): SqlPreparedStatement;
  batch<T>(statements: SqlPreparedStatement[]): Promise<SqlQueryResult<T>[]>;
  exec(query: string): Promise<SqlExecResult>;
}

interface SqlPreparedStatement {
  bind(...values: unknown[]): SqlPreparedStatement;
  first<T>(column: string): Promise<T | null>;
  first<T>(): Promise<T | null>;
  run<T>(): Promise<SqlQueryResult<T>>;
  all<T>(): Promise<SqlQueryResult<T>>;
  raw<T>(options?: { columnNames?: boolean }): Promise<T[]>;
}

interface SqlQueryResult<T> {
  results: T[];
  success: boolean;
  meta: SqlQueryResultMeta;
}

interface SqlQueryResultMeta {
  duration: number;
  rows_read: number;
  rows_written: number;
  last_row_id: number;
  changes: number;
}

interface SqlExecResult {
  count: number;
  duration: number;
}

Every generic above has a default in the shipped types, so each method is usable without an explicit type argument — all() and run() hand back rows typed as plain records, and raw() hands back arrays of values. Key behaviors:

prepare is synchronous; every terminal is async. prepare builds a statement locally — nothing crosses the wire until first, run, all, raw, batch, or exec is awaited.
bind returns a new statement. It never mutates the statement it was called on, so a prepared statement can be reused with different values.
run() is an alias for all(). Both send the same request and return the same SqlQueryResult, rows included — run() on a SELECT returns rows. This matches Cloudflare D1.
batch() is atomic. All statements commit together or none do.
exec() returns no rows — only a statement count. Use it for schema scripts.
success is always true on a resolved promise. Failures reject; they are never reported through the flag.
Errors throw plain Error objects. There is no typed error class and no error-code taxonomy. See Errors.
Transaction control statements are rejected. SQL containing BEGIN, COMMIT, ROLLBACK, or SAVEPOINT fails when it runs — through a prepared statement or through exec() — with SqlTransactionControlError in the message. Transaction boundaries belong to the runtime; use batch() for all-or-nothing writes.

Reading What a Write Touched

meta reports the statement’s own accounting — last_row_id, changes, rows_read, rows_written, and duration. RETURNING is the more precise option, and worth preferring for anything you branch on. It names the rows the statement actually touched, so it survives concurrency: every caller of a database shares one connection, and meta describes the statement that most recently ran on it.

// The id of a new row
const row = await env.DB
  .prepare("INSERT INTO users(email) VALUES (?) RETURNING id")
  .bind("alice@example.com")
  .first<{ id: number }>();
const newId = row?.id;

// Exactly which rows an UPDATE touched, not just how many
const { results } = await env.DB
  .prepare("UPDATE users SET active = 0 WHERE last_seen < ? RETURNING id")
  .bind(cutoff)
  .run<{ id: number }>();
const changed = results.length;

SQLite accepts RETURNING on INSERT, UPDATE, and DELETE, and the rows it hands back are exactly the rows the statement touched. SELECT changes() reports the count instead, but it reads whichever statement most recently ran on the shared connection, so a concurrent write can land in between. When a bare count is all you need, issue it in the same batch() as the write so nothing can interleave:

const [, counted] = await env.DB.batch<{ n: number }>([
  env.DB.prepare("DELETE FROM sessions WHERE expires_at < ?").bind(Date.now()),
  env.DB.prepare("SELECT changes() AS n"),
]);
const deleted = counted.results[0].n;

`prepare(query)`

Build a statement. Synchronous, and safe to call once and reuse.

const stmt = env.DB.prepare("SELECT id, email FROM users WHERE org = ?");
const acme = await stmt.bind("acme").all<{ id: number; email: string }>();
const globex = await stmt.bind("globex").all<{ id: number; email: string }>();

A query string may hold several ;-separated statements. All of them execute in order, and the rows that come back are the final statement’s — the same rule Cloudflare’s Durable Object SQL storage follows. Bound parameters apply to that final statement only: place placeholders nowhere else, because the earlier statements run without bindings and a ? in one of them fails.

`bind(...values)`

Attach values to the placeholders in the query and get back a new statement. Always bind user input — never build SQL by string concatenation.

const stmt = env.DB
  .prepare("INSERT INTO events(name, at, payload) VALUES (?, ?, ?)")
  .bind("signup", Date.now(), null);

Placeholders are positional: anonymous ? and ordered ?NNN (1-indexed) both work, and values are consumed in argument order.

Type Conversion

How values cross between JavaScript and SQLite, in both directions — what bind() accepts on the way in, and what the terminal methods hand back on the way out. Four JavaScript types reach SQLite — null, number, string, and ArrayBuffer — plus undefined, which is accepted and stored as NULL. Every other value throws, and it throws when the statement runs rather than at the bind() call, because bind() performs no validation.

JavaScript value	Bound as	Read back as
`number`	`REAL` affinity — see below	`number`
`string`	`TEXT`	`string`
`null`	`NULL`	`null`
`undefined`	`NULL` (accepted; D1 rejects it)	`null`
`ArrayBuffer`	`BLOB`	`ArrayBuffer` over the binding; a JSON array of byte values over REST and the CLI
`boolean`	throws `Provided value cannot be bound to SQLite parameter N`	—
`Uint8Array` and other typed-array views	throws `Unknown named parameter` — pass the underlying `ArrayBuffer`	—
`bigint`	throws `Do not know how to serialize a BigInt`	—
plain object	throws `Unknown named parameter`	—

Store a boolean as 0/1 and binary as an ArrayBuffer:

const bytes = new Uint8Array([9, 8, 7]);
await env.DB
  .prepare("INSERT INTO flags(active, blob) VALUES (?, ?)")
  .bind(isActive ? 1 : 0, bytes.buffer) // .buffer, not the view
  .run();

.buffer is the whole backing store, not the view. For a view that does not span its buffer, slice first: bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength). One bound value is capped at 2 MiB (2,097,152 bytes). A larger ArrayBuffer or string is rejected with SqlParameterTooLargeError before the statement runs. This is a ceiling of the storage engine SQL Databases share with per-actor SQLite, and it applies only to values sent through .bind() — a value produced inside SQL, such as randomblob(), is not bound and is not checked. Split larger payloads, or keep them in object storage and bind the key. A bound number arrives with REAL affinity — SELECT typeof(?) on a bound 42 returns real. Inserted into a column declared INTEGER, it still lands as an integer (typeof(col) reads back integer); the affinity only shows in untyped or expression contexts. In a STRICT table the check is exact, so binding 3.5 into an INTEGER column correctly fails with cannot store REAL value in INTEGER column. Reading an integer larger than 2^53 − 1 throws RangeError: Value is too large to be represented as a JavaScript number. SQLite stores 64-bit integers, but result columns come back as JavaScript numbers — a value past Number.MAX_SAFE_INTEGER (9007199254740991) can be written and compared in SQL, but the read fails loudly rather than losing precision. Store large ids, snowflake keys, and nanosecond timestamps as TEXT.

`first()` and `first(column)`

Return the first row, or a single column of it. No meta.

// Whole row, or null when the query matched nothing
const user = await env.DB
  .prepare("SELECT id, email FROM users WHERE id = ?")
  .bind(1)
  .first<{ id: number; email: string }>();

// One column, as a bare value
const total = await env.DB.prepare("SELECT COUNT(*) AS n FROM users").first<number>("n");

first() resolves to null when there are no rows. first(column) returns the value at that key; if the column is not in the result set it also resolves to null rather than throwing — a divergence from D1, which raises D1_COLUMN_NOTFOUND.

`run()` and `all()`

Run the statement and return the full envelope. The two methods are identical.

const { results, success } = await env.DB
  .prepare("SELECT id, email FROM users WHERE org = ?")
  .bind("acme")
  .all<{ id: number; email: string }>();

// results -> [{ id: 1, email: "alice@example.com" }, ...]

results holds the rows as objects keyed by column name. For an INSERT, UPDATE, or DELETE it is an empty array unless the statement carries a RETURNING clause. The generic is a compile-time assertion only — it is not validated against the columns the query actually returns.

`raw(options?)`

Return rows as arrays of values instead of objects, for callers that already know the column order or that feed a columnar consumer. The rows are converted after they arrive, so this is a shape convenience, not a smaller response.

const rows = await env.DB.prepare("SELECT id, email FROM users").raw();
// [[1, "alice@example.com"], [2, "bob@example.com"]]

const withHeader = await env.DB.prepare("SELECT id, email FROM users").raw({ columnNames: true });
// [["id", "email"], [1, "alice@example.com"], [2, "bob@example.com"]]

{ columnNames: true } prepends one row of column names. An empty result set returns [] with no header row, so check the length before treating the first entry as headers. Rows are converted from the same objects all() returns, so two result columns with the same name collapse into one — alias them (SELECT a.id AS a_id, b.id AS b_id) when joining.

`batch(statements)`

Run several prepared statements as one atomic unit. Results come back in the order the statements were passed.

const [debited] = await env.DB.batch<{ cents: number }>([
  env.DB
    .prepare("UPDATE accounts SET cents = cents - ? WHERE id = ? RETURNING cents")
    .bind(500, "a"),
  env.DB.prepare("UPDATE accounts SET cents = cents + ? WHERE id = ?").bind(500, "b"),
]);
const remaining = debited.results[0]?.cents;

The whole batch commits together: if any statement fails, every earlier statement in the same batch is rolled back and the promise rejects. A batch whose middle statement violates a UNIQUE constraint leaves the table exactly as it was. Every statement must come from the same database’s prepare(). Passing a statement built by a different binding throws env.<DB>.batch() accepts only statements created by this database's prepare(). batch() is the transaction primitive for parameterized, all-or-nothing writes: explicit BEGIN is rejected, so a transaction cannot be opened by hand.

`exec(query)`

Run a raw SQL script. Takes no bound parameters and returns no rows.

const { count } = await env.DB.exec(`
  CREATE TABLE IF NOT EXISTS users(id INTEGER PRIMARY KEY, email TEXT UNIQUE);
  CREATE INDEX IF NOT EXISTS users_by_email ON users(email);
`);
// count -> 2

count is the number of statements in the script. Passing bind arguments throws env.<DB>.exec() takes no bound params — use prepare().bind() for parameterized statements. Use exec for schema and one-shot maintenance work, and prepare().bind() for anything that takes user input. A script is atomic: if any statement in it fails, every statement in that script rolls back. A script that creates a table, inserts a row, and then hits an error leaves no table behind. So exec() either applies a whole script or changes nothing.

Errors

Every failure — syntax error, missing table, constraint violation, bad bind — rejects with a plain Error. There is no typed error class, no cause chain, and no error-code taxonomy equivalent to D1’s D1_ERROR / D1_TYPE_ERROR / D1_COLUMN_NOTFOUND. error.message is a long transport string with the SQLite message embedded near the end:

actor invocation <org>__telnyx_sqldb/<database-id>.sql returned 500: error invoke actor
method: rpc error: code = Internal desc = ... (500) {"error":"method_failed",
"message":"Error: UNIQUE constraint failed: users.email","name":"Error"}

Match on the SQLite text as a substring. Do not parse the envelope — its shape is not part of the contract, and the surrounding transport detail changes.

try {
  await env.DB
    .prepare("INSERT INTO users(email) VALUES (?)")
    .bind(email)
    .run();
} catch (err) {
  const message = err instanceof Error ? err.message : String(err);
  if (message.includes("UNIQUE constraint failed")) {
    return new Response("email already registered", { status: 409 });
  }
  throw err;
}

Long-running statements fail differently: no SQLite message comes back at all. Statements running for tens of seconds complete, but past the caller’s own budget — a function invocation tops out around 60 seconds — the call was observed to hang rather than fail with anything identifying the statement. The database stays healthy afterwards. See Limits.

Overview — the SQL Databases Runtime API surface at a glance
Quick Start — declare the binding and type it
How SQL Databases Work — one primary per database, and where the data lives
Migrations — versioned schema changes from the CLI
Limits — statement size, parameter, and duration ceilings
Stateful Actor SQL — the per-actor embedded SQLite at ctx.storage.sql, private to one instance and synchronous

CLI

Source: https://developers.telnyx.com/docs/edge-compute/sqldb/cli.md

Manage SQL databases using the telnyx-edge CLI. Every command in this family reaches a database through the same primary as the env binding, so the CLI is not a second writer — SQL run from a terminal and SQL run from a deployed function are serialized together. The storage sqldb family requires CLI v0.3.0 or newer — the first release to carry any SQL surface. On v0.2.5 and earlier telnyx-edge storage sqldb fails as an unknown command. Check with telnyx-edge --version.

Database Management

# List databases
telnyx-edge storage sqldb list

# Create a database (name: lowercase letters, numbers, hyphens)
telnyx-edge storage sqldb create --name links-db

# Get one database by id
telnyx-edge storage sqldb get <database-id>

# Delete a database by id — no confirmation prompt
telnyx-edge storage sqldb delete <database-id>

create returns immediately with status: pending; provisioning finishes in the background, typically in 2 to 11 seconds:

✓ SQL database 'links-db' created — provisioning runs in the background
FIELD          VALUE
------------   ------------------------------
SQLDB ID       550e8400-e29b-41d4-a716-446655440000
Name           links-db
Status         pending
Created At     Jul 29, 2026, 14:52

Use 'telnyx-edge storage sqldb get 550e8400-e29b-41d4-a716-446655440000' to check when it is ready.

Poll get until the status is provision_ok:

FIELD          VALUE
------------   ------------------------------
SQLDB ID       550e8400-e29b-41d4-a716-446655440000
Name           links-db
Status         provision_ok
Created At     Jul 29, 2026, 14:52
Updated At     Jul 29, 2026, 14:52

list paginates, newest first:

SQLDB ID                               NAME                   STATUS            CREATED AT
------------------------------------   --------------------   ---------------   -----------------
7c9e6679-7425-40de-944b-e07fc1f90ae7   analytics              provision_ok      Jul 29, 2026, 15:11
550e8400-e29b-41d4-a716-446655440000   links-db               provision_ok      Jul 29, 2026, 14:52

Page 1 of 1 (showing 2 of 2 total SQL databases)

delete takes effect immediately and asks nothing first — there is no confirmation prompt and no --yes flag:

✓ SQL database '550e8400-e29b-41d4-a716-446655440000' deletion started

The record disappears shortly afterwards: get and any query against that id return 404. Delete removes the database record and makes the data unreachable through every path; it is not a guaranteed erase of the stored bytes, so it does not satisfy a data-destruction requirement on its own. It also does not touch functions that still declare the id in a [storage.sqldb.<NAME>] block: those functions stay deployed and their queries start failing. Remove the block and redeploy them.

`list` Flags

Flag	Description
`--page`	Page number, 1-based (default `1`)
`--page-size`	Items per page, `1`–`250` (default `20`)

get and delete take the database id only. execute and the migrations subcommands accept either the id or the database name — see Addressing a Database.

Running SQL

execute runs SQL against a database without deploying anything — to create a schema, load seed data, or inspect what a function wrote.

# One statement, inline
telnyx-edge storage sqldb execute links-db --remote \
  --command "CREATE TABLE links (id INTEGER PRIMARY KEY, slug TEXT UNIQUE, url TEXT NOT NULL)"

# A whole file — submitted as one multi-statement script
telnyx-edge storage sqldb execute links-db --remote --file ./schema.sql

# Read rows back
telnyx-edge storage sqldb execute links-db --remote \
  --command "SELECT id, slug, url FROM links ORDER BY id"

A statement that returns no rows prints a confirmation:

✓ Statement executed — no rows returned

A read prints a table and a row count:

id    slug   url
---   ----   ---
1     docs   https://developers.telnyx.com
2     home   https://telnyx.com

2 row(s)

Columns are ordered alphabetically rather than by their order in the SELECT list, and a SQL NULL renders as NULL. To learn a new row’s id, or to count the rows a write touched, add RETURNING to the statement and count the rows it prints. SELECT changes() in a separate call reads a counter on a connection shared with every other caller of the database, so another write can land in between. --json prints the raw result object instead of a table — on stderr in the current CLI, so scripts should capture it with 2>&1 >/dev/null rather than piping stdout. results holds the rows and is the only field the service returns — a statement that produces no rows prints {}:

telnyx-edge storage sqldb execute links-db --remote \
  --command "SELECT slug FROM links ORDER BY id" --json

{
  "results": [
    {
      "slug": "docs"
    },
    {
      "slug": "home"
    }
  ]
}

BLOB columns cross this boundary as a JSON array of byte values — a three-byte blob comes back as [9, 8, 7], not base64 and not an object. Decode it as bytes on the client. Writing binary this way means a SQL hex literal (X'090807'), since this path has no parameter binding; from a function, bind an ArrayBuffer instead.

`execute` Flags

Flag	Description
`--command`, `-c`	SQL to run inline. Mutually exclusive with `--file`; exactly one of the two is required
`--file`, `-f`	Path to a `.sql` file, submitted verbatim as a single multi-statement script
`--remote`	Required. Runs against the remote database — local execution is not supported
`--json`	Print the raw result object instead of a table

--remote is mandatory. Omitting it fails with --remote is required before any network call: there is no local SQLite emulation to run against, and no --local flag. The SQL text is submitted verbatim — the CLI never splits statements itself. A script may hold several ;-separated statements; all of them run in order, and the rows returned are the last statement’s rows. The whole script must fit under the ~4 MiB script ceiling (see Limits). A database that has not finished provisioning rejects execute with 409 — Database is not ready (status: pending). Wait for provision_ok.

Migrations

Versioned schema changes live in numbered .sql files and are tracked in a sqldb_migrations table inside the database itself.

# Create a numbered migration file (offline — no auth, no network)
telnyx-edge storage sqldb migrations create links-db create_links

# Show which files are applied and which are pending
telnyx-edge storage sqldb migrations list links-db --remote

# Apply everything outstanding, in order
telnyx-edge storage sqldb migrations apply links-db --remote

✓ Applied 0001_create_links.sql
✓ Applied 0002_add_click_count.sql

2 migration(s) applied

`migrations` Flags

Flag	Description
`--migrations-dir`	Directory holding the migration files (default `migrations/<database>`, with every run of non-alphanumeric characters in the database argument collapsed to `_` and leading or trailing runs dropped)
`--remote`	Required on `list` and `apply`; `create` is offline and does not accept it
`--json`	Machine-readable output — `apply` emits `{"applied": [...]}`; `list` accepts it too

The full workflow — file naming, the ledger table, and what happens when a migration fails midway — is covered in Migrations.

Generating Types

telnyx-edge types reads the manifest and writes telnyx-env.d.ts, so env.<BINDING> is typed at compile time. It runs fully offline — no authentication, no network.

[storage.sqldb.DB]
id = "550e8400-e29b-41d4-a716-446655440000"

telnyx-edge types

✓ Generated binding types for 1 binding(s) at telnyx-env.d.ts
    env.DB → SqlDatabase

Two things are checked before anything is written: the id must be a well-formed UUID (inline creation and binding by name are rejected), and @telnyx/edge-runtime in package.json must be 0.9.0 or newer — the first version that exports SqlDatabase. An older pin fails with @telnyx/edge-runtime <declared version> does not export SqlDatabase (requires >= 0.9.0), quoting the range exactly as package.json declares it.

Addressing a Database

execute, migrations list, and migrations apply take a <database> argument that resolves either way:

An exact id match always wins.
A name resolves when exactly one database in the organization carries it.
A name shared by several databases errors with Multiple SQL databases are named "..." — pass the id instead.
No match errors with No SQL database found matching "...".

Names are unique within an organization, so an ambiguous match should not occur in practice — the CLI guards against it anyway. get and delete do not resolve names; they take the id.

Quick Start — create a database, bind it, query it
Migrations — versioned schema changes and the sqldb_migrations ledger
Limits — request body size, query duration, and what is not enforced
SqlDatabase — the env binding surface
CLI Reference — every telnyx-edge command

Limits

Source: https://developers.telnyx.com/docs/edge-compute/sqldb/limits.md

Limits

Limit	Value	Behavior past it
Database size	1 GiB	Writes fail the way SQLite fails on a full disk
One bound value	2 MiB	`SqlParameterTooLargeError`, before the statement runs
Bound parameters per statement	32,766	SQLite’s variable limit
SQL script, REST and CLI	~4 MiB	`422` — the transport rejects the request with `stream too large`; past 8 MiB, `413` — `SQL body exceeds the maximum size`
Rows returned by one statement	~4 MiB	The query fails with a `ResourceExhausted … larger than max` error — on the REST path and the `env` binding alike
Expression tree depth	1,000	`Expression tree is too large`
Database name	`^[a-z0-9-]+$`, up to 255 characters	Character-set violations return `422`; past 255 characters the create fails with `500`; a duplicate name returns `409`

The ~4 MiB script ceiling covers the whole SQL script sent over the REST query path — which is also what telnyx-edge storage sqldb execute --file and migrations apply use. The service advertises an 8 MiB gate and returns the 413 past it, but the transport underneath rejects anything over roughly 4 MiB (4,194,304 bytes, less a few hundred bytes of envelope) with a 422 whose detail ends in stream too large — so ~4 MiB is the number to plan against, and a large seed file needs splitting across several calls. Result sets are capped at the same ~4 MiB, per statement. A query whose rows exceed it fails with a ResourceExhausted … trying to send message larger than max error, through REST and through the env binding alike. Only shipping the rows is capped — computing over the same data server-side (length(), aggregates) is fine — so page through large reads instead of selecting them whole. The 2 MiB cap applies only to values passed through .bind(). A value produced inside SQL is never bound and never checked, which is why randomblob(100000000) stores without complaint. Keep anything approaching either figure — images, archives, model weights — in object storage and bind the key instead. Database size and bound-value size come from the SQLite storage engine that SQL Databases share with per-actor SQLite, so the same numbers apply on both surfaces.

Query Performance

A database is served by one primary, and statements run one at a time. A long statement delays everything else queued against that database, so the useful discipline is keeping individual statements short.

Query	Typical
Simple statement, warm	~10 ms round trip
5,000-row read	~160 ms

Add indexes on the columns you filter and order by, page through large result sets instead of selecting them whole, and maintain a summary table on write rather than aggregating across millions of rows on read. Long analytical scans belong in a warehouse, not here.

CREATE INDEX IF NOT EXISTS links_by_slug ON links(slug);

SqlDatabase — the binding surface: methods, type conversion, and errors
How SQL Databases Work — one primary per database
Migrations — versioned schema changes
CLI — execute, migrations, and database management
Stateful Actor SQL — the separate per-actor SQLite database
Edge Compute Limits — function request timeout, memory, and body sizes

​Telnyx Storage: SQL (Beta) — Full Documentation

​Get Started

​SQL Databases

​Two Ways to Reach a Database

​SQL Databases vs Per-Actor SQL

​Next Steps

​Related Resources

​Quick Start

​Prerequisites

​1. Create a Database

​2. Create the Schema

​3. Bind the Database to a Function

​4. Generate Types

​5. Write the Function

​6. Ship and Call It

​7. Query It Without Deploying

​8. Query It From Any Language

​Next Steps

​Concepts

​How SQL Databases Work

​A Database Is a Standalone Resource

​One Primary, Serialized Writes

​Two Access Paths, One Database

​Sharing Across Functions

​Isolation

​Consistency and Durability

​Choosing Between SQL, KV, and Per-Actor SQLite

​Related Resources

​Migrations

​A Worked Example

​The Ledger Lives in the Database

​Apply Is Not All-or-Nothing

​Files and Directories

​Machine-Readable Output

​Related

​Reference

​Overview

​Getting the Binding

​Related Resources

​SqlDatabase

​Reading What a Write Touched

​prepare(query)

​bind(...values)

​Type Conversion

​first() and first(column)

​run() and all()

​raw(options?)

​batch(statements)

​exec(query)

​Errors

​Related

​CLI

​Database Management

​list Flags

​Running SQL

​execute Flags

​Migrations

​migrations Flags

​Generating Types

​Addressing a Database

​Related

​Limits

​Limits

​Query Performance

​Related

Telnyx Storage: SQL (Beta) — Full Documentation

Get Started

SQL Databases

Two Ways to Reach a Database

SQL Databases vs Per-Actor SQL

Next Steps

Related Resources

Quick Start

Prerequisites

1. Create a Database

2. Create the Schema

3. Bind the Database to a Function

4. Generate Types

5. Write the Function

6. Ship and Call It

7. Query It Without Deploying

8. Query It From Any Language

Next Steps

Concepts

How SQL Databases Work

A Database Is a Standalone Resource

One Primary, Serialized Writes

Two Access Paths, One Database

Sharing Across Functions

Isolation

Consistency and Durability

Choosing Between SQL, KV, and Per-Actor SQLite

Related Resources

Migrations

A Worked Example

The Ledger Lives in the Database

Apply Is Not All-or-Nothing

Files and Directories

Machine-Readable Output

Related

Reference

Overview

Getting the Binding

Related Resources

SqlDatabase

Reading What a Write Touched

`prepare(query)`

`bind(...values)`

Type Conversion

`first()` and `first(column)`

`run()` and `all()`

`raw(options?)`

`batch(statements)`

`exec(query)`

Errors

Related

CLI

Database Management

`list` Flags

Running SQL

`execute` Flags

Migrations

`migrations` Flags

Generating Types

Addressing a Database

Related

Limits

Limits

Query Performance

Related