Storage
D1
Run D1 databases on OpenOrange, where each database is one Rivet Actor with its own SQLite database.
Runs on Internal Rivet Actor per database, on the Durable Object SQL bridge
- Works
prepare(),batch(),exec(), sessions, andorange d1migrations, with JSON, FTS5, and window functions- Differs
meta.rows_readandmeta.rows_writtenare approximate, andATTACHand thePRAGMAs that D1 refuses run- Missing
DELETE ... LIMIT,UPDATE ... LIMIT, SQLite math functions such ascos(),query(),dump(), and read replicas- Migration
- Migration with downtime
orange migrate d1refuses writes during the move, and every query fails while Cloudflare exports the database. A 1 GB database froze writes for about 3 minutes. Migration guide
- Configure
d1_databases- Scales by
- Database
- Checks
- 1 pass
A D1 database on OpenOrange is one Rivet Actor with its own SQLite database. Your D1 code, migrations, and Wrangler configuration run unchanged.
Quickstart
-
Bind the database
Add a
d1_databasesentry towrangler.jsonc. Keep your Cloudflaredatabase_id: Orange uses it as the database’s name.{ "name": "d1-migrations", "main": "src/index.ts", "compatibility_date": "2026-09-03", "d1_databases": [ { "binding": "DB", "database_name": "comments", "database_id": "d1-migrations-comments" } ] } -
Write a migration
Put numbered SQL files in
migrations/, as for Wrangler. This one creates the table and adds three rows.-- migrations/0001_create_comments_table.sql CREATE TABLE IF NOT EXISTS comments ( id INTEGER PRIMARY KEY NOT NULL, author TEXT NOT NULL, content TEXT NOT NULL ); INSERT INTO comments (author, content) VALUES ('Kristian', 'Congrats!'), ('Serena', 'Great job!'), ('Max', 'Keep up the good work!'); -
Query it from your Worker
interface Env { DB: D1Database; } export default { async fetch(request, env): Promise<Response> { if (request.method === "POST") { const { author, content } = await request.json<{ author: string; content: string }>(); const comment = await env.DB.prepare( "INSERT INTO comments (author, content) VALUES (?, ?) RETURNING *", ) .bind(author, content) .first(); return Response.json(comment, { status: 201 }); } const { results } = await env.DB.prepare("SELECT * FROM comments ORDER BY id").all(); return Response.json({ comments: results }); }, } satisfies ExportedHandler<Env>; -
Apply the migration
orange d1 migrations apply DBIt lists each new migration and marks it ✅ when it applies.
-
Run it
orange devshows the database as a Rivet Actor.orange dev Binding Resource Runs on env.DB D1 Database Rivet ActorA
GETreturns the three rows from the migration. APOSTadds one:curl localhost:8787/comments -d '{"author":"Ada","content":"Nice work"}' {"id":4,"author":"Ada","content":"Nice work"}
How it works
- Each database is one Rivet Actor with its own SQLite database. Result shapes,
meta, and error text matchwrangler dev. - Under
orange dev, it lives in your project’s.open-orangedirectory, so rows survive a restart. Afterorange deploy, it runs on your Rivet cluster. - One actor serves each database. For more throughput, split the data into more databases, such as one per tenant.
AI context Compatibility, limits and details
Written for LLMs and coding agents: every edge case, measurement, and known deviation. You do not need it to use the feature.
Compatibility
| Feature | Status | Notes |
|---|---|---|
prepare(), bind(), first(), all(), run(), and raw() | Supported | Same result shapes and meta fields. |
batch() | Supported | One transaction. If one statement fails, none of them apply. |
exec() | Supported | Each line runs as one statement. |
withSession() and bookmarks | Supported | The bookmark advances after each query. |
meta.rows_read and meta.rows_written | Partial | rows_read counts returned rows, not scanned rows. rows_written counts changed rows, without index and trigger writes. |
DELETE ... LIMIT and UPDATE ... LIMIT | Not supported | Fail with near "LIMIT": syntax error. |
SQLite math functions, such as cos(), sqrt(), and floor() | Not supported | Fail with no such function. abs() and round() work. |
query() | Not supported | Needs the d1_binding_jsrpc compatibility flag, which Orange does not apply. |
dump() | Not supported | Fails with D1_DUMP_ERROR, as in wrangler dev. |
| Read replication | Not supported | Every query reaches the one database. |
orange d1 execute, orange d1 migrations apply, and orange d1 migrations list | Supported | Local by default, or --remote. |
Other wrangler d1 commands, such as export | Not supported | They print that the command is not implemented. |
Your D1 code runs unchanged, except for the SQL above. Three differences reach most projects:
DELETE ... LIMITandUPDATE ... LIMITfail. Select the rows in a subquery instead, which runs on Cloudflare too:DELETE FROM t WHERE rowid IN (SELECT rowid FROM t WHERE ... LIMIT 1).- chanfana before 3.1.0 fails every
D1DeleteEndpointwith a 500, because it deletes withDELETE ... RETURNING * LIMIT 1. Upgrade chanfana to 3.1.0 or later.orange doctorflags an older chanfana in a project with a D1 database. - Everything in the SQLite section of the compatibility page applies to D1. It runs on the same SQLite as Durable Objects.
Limits
| What | Limit | What happens over it |
|---|---|---|
| Queries on one database | What one Rivet Actor serves | Split the data into more databases, for example one per tenant. |
One query or batch() | 128 MiB of changed SQLite pages, Rivet’s limit for one commit | The call fails. |
| A long query | Runs on the one Node.js runtime thread | The other Workers and objects in that process wait until it ends. |
What Orange reads
On Orange, database_id only names the database, so a Cloudflare database ID
works as it is.
In wrangler.jsonc | On Orange |
|---|---|
database_id | Names the database. Under orange dev, a preview_database_id wins, as in wrangler dev. With neither, the binding name names it. orange serve, --remote, and a deployed Worker skip preview_database_id, as wrangler deploy does. |
The same database_id on two bindings | One database, also for every Worker of one orange dev session. See Multiple Workers. |
migrations_dir, migrations_pattern, migrations_table | Read by orange d1 migrations, as Wrangler reads them. The defaults are migrations and d1_migrations. |
Commands
These run on the same local database that orange dev uses. Name the database
by its binding or its database_name.
orange d1 migrations list DB
orange d1 migrations apply DB
orange d1 execute DB --command "SELECT * FROM comments"
orange d1 execute DB --file ./seed.sql --jsonWith --remote, they run on the database of the deployed orange serve,
through the Rivet Engine in RIVET_ENDPOINT. Run them in the project, with the
Worker name and --env of the deployment. The deployment must be up.
RIVET_ENDPOINT=https://<namespace>:<token>@api.rivet.dev orange d1 migrations apply DB --remoteAPI details
- The client is a port of workerd’s D1 binding, and the backend follows the
local D1 backend of
wrangler dev, so result shapes,meta, and error text match. - Each request to the database runs as one transaction on its actor.
- Errors use D1’s prefixes, with SQLite’s message and result code:
D1_ERROR: no such table: users: SQLITE_ERROR, andD1_ERROR: UNIQUE constraint failed: notes.body: SQLITE_CONSTRAINT (extended: SQLITE_CONSTRAINT_UNIQUE). bind()takes numbers, strings,null, booleans as1and0, byte arrays,ArrayBuffer, and typed arrays as BLOBs. ADataViewbinds as an empty BLOB, as in workerd. Any other value fails withD1_TYPE_ERROR: Type '<type>' not supported for value '<value>'.- A BLOB column reads back as an array of byte values. An integer outside the safe range is a lossy number, as in workerd.
first(column)with an unknown column fails withD1_COLUMN_NOTFOUND: Column not found (<column>).exec()splits its input by line. A failing line fails withD1_EXEC_ERROR: Error in line <n>: <line>: <message>, and an empty input withNo SQL statements detected.metahaschanged_db,changes,duration,last_row_id,rows_read,rows_written,size_after,served_by,served_by_primary: true, andtimings.sql_duration_ms.- A session bookmark is a timestamp and a counter, and only has to increase, because every query reaches the one database.
query()always fails withD1_ERROR: D1Database.query() requires the d1_binding_jsrpc compatibility flag.
SQLite
D1 runs on RivetKit’s SQLite 3.46.0, a different build from workerd’s. It is
built from its amalgamation without SQLITE_ENABLE_UPDATE_DELETE_LIMIT, so its
parser has no LIMIT on DELETE and UPDATE, with or without RETURNING and
ORDER BY. The full error is
D1_ERROR: near "LIMIT": syntax error at offset <n>: SQLITE_ERROR.
- JSON, FTS5,
RETURNING, upsert, window functions, CTEs,STRICTtables, and generated columns run. Foreign keys are enforced by default. - SQL that names a
_cf_or_rivet_table fails withnot authorized. - Orange leaves its
_rivet_tables out ofsqlite_master,sqlite_schema, andPRAGMA table_list, so a tool that dumps every listed table works. A query that renames thenameandtbl_namecolumns, or only counts rows, still sees them. ATTACH,PRAGMAs, and internal functions that D1 refuses run, against the database itself. Orange blocks only the reserved names and transaction control.- A prepared statement with several statements runs them all and returns the
last statement’s rows.
wrangler devrejects it. Bindings on it fail withOpenOrange does not yet support bindings on multi-statement SQL. BEGIN,COMMIT,END,ROLLBACK,SAVEPOINT, andRELEASEfail, as on Cloudflare. Usebatch().
Command details
- Each
orange d1command starts the Orange runtime for a moment and writes the same database thatorange devuses. - Migrations come from
migrations_dir, filtered bymigrations_pattern, and run in the order of their leading number. Themigrations_tablerecords each applied migration. - Each migration runs as one batch with its record, so a failed migration rolls back, and the later ones do not run.
orange d1 migrations applydoes not ask for confirmation, and it does not capture a backup.orange d1 executetakes--commandor--file, not both. With--json, or when the output is not a terminal, it prints the results as JSON.--remotereadsRIVET_ENDPOINT, not a Cloudflare account. Without it, the command fails with--remote needs RIVET_ENDPOINT, such as https://<namespace>:<token>@api.rivet.dev. The Engine runs the database on the deployed runner.--localis accepted, and is the default.--previewand--persist-tofail. Orange keeps local data under.open-orange.
Debug a database
| Symptom | Cause | Fix |
|---|---|---|
D1_ERROR: no such table: <name> | The migrations have not run on this database | Run orange d1 migrations apply DB, or add --remote for the deployed database. |
D1_ERROR: near "LIMIT": syntax error | DELETE ... LIMIT or UPDATE ... LIMIT | Use the subquery under Compatibility. |
D1_ERROR: no such function: cos | SQLite math functions are not in this build | Compute in JavaScript, or store the value in a column. |
D1_ERROR: The D1 database could not answer (status <n>): <group>.<code>: ... | The database’s actor could not be reached | Check the Rivet Engine and the runner. |
This D1 database has an unfinished copy from Cloudflare, so Orange won't serve its partial data. | An orange migrate d1 stopped before it ended | Finish it with orange migrate d1, or replace the copy with orange migrate d1 --replace. See Migrate from Cloudflare. |
Deviations
These add to the differences under Compatibility.
meta.rows_readandmeta.rows_writtencome from the returned rows and SQLite’s change count, so a query that scans 5 rows and returns 1 reports 1. Do not build cost limits on them.
Conformance
tests/cli/d1.test.tsapplies migrations withorange d1, including a failed migration that rolls back, and reads the result throughorange dev.tests/bindings/bindings.test.tsdrives D1 through a realorange dev: result shapes,meta, BLOB and boolean bindings, batch rollback, error text, sessions, overlapping inserts, and persistence across restarts. The same Worker returns identical results underwrangler dev.tests/cli/orange-serve.test.tsrunsorange d1 migrations apply --remoteagainstorange serve, and checks thatorange serveskipspreview_database_id.tests/rpc-and-websockets/session-shared-storage.test.tschecks that the Workers of one session share a database by ID, and that another ID stays separate.- The
sqlite-surfaceprobe runsbatch()order,cos(), andDELETE ... LIMITthrough the D1 binding, next to its Durable Object SQL checks. - workerd’s upstream D1 tests are not part of the conformance corpus.
Recorded results
Recorded results from the conformance run of 2026-11-10 (Orange ea40348), 1,670 of 1,851 tests passing across every area. Each check is works when every result passed and partial when some did. The full feature matrix is on the compatibility page.
D1
| Check | Status | Results |
|---|---|---|
| D1 | Works |
|