Crate sqlx_cloudflare_d1 

A Cloudflare D1 driver for sqlx.

D1 is an sqlx::Database over the Workers D1 binding, so code written against sqlx’s runtime API – sqlx::query, sqlx::query_as, #[derive(sqlx::FromRow)], Executor – runs inside a Rust Worker with the database type swapped.

use sqlx_cloudflare_d1::{D1Connection, D1};

#[derive(sqlx::FromRow)]
struct User {
    id: i64,
    name: String,
}

async fn user(env: &worker::Env, id: i64) -> Result<User, Box<dyn std::error::Error>> {
    // One connection per request, straight from the binding.
    let conn = D1Connection::from_env(env, "DB")?;

    let user = sqlx::query_as::<D1, User>("SELECT id, name FROM users WHERE id = ?")
        .bind(id)
        .fetch_one(&conn)
        .await?;

    Ok(user)
}

What D1 cannot do

Each of these fails loudly rather than pretending:

• Transactions. begin() returns an error; D1 cannot hold a transaction open across calls. D1Connection::execute_batch runs several statements atomically in one round trip instead.
• Integers beyond ±(2^53 − 1). D1 passes values as JavaScript numbers, so binding a wider i64 is an encode error rather than a rounded value. See types.
• query! and describe. sqlx’s macros only know its built-in drivers, and D1 cannot describe a statement without running it.

There is no sqlx::Pool either – a binding has nothing to pool – and no sqlx::migrate!: apply migrations with wrangler d1 migrations.

This crate only runs on wasm32-unknown-unknown, inside a Worker. It compiles on other targets so that docs, unit tests and cargo check work, but its Send impls lean on Workers being single-threaded: do not call it from a threaded host.

Modules

types

Encode, Decode and Type for the Rust types D1 can store.

Structs

D1

The Cloudflare D1 database driver: the type sqlx code names in Executor<'_, Database = D1>, sqlx::query_as::<D1, _> and so on.

D1Arguments

The parameters bound to one query, in placeholder order.

D1Column

A column of a D1 result.

D1ConnectOptions

The options type sqlx requires of every connection.

D1Connection

A connection to a D1 database: a Workers D1 binding.

D1DatabaseError

An error the database returned for a statement.

D1QueryResult

What a statement did.

D1Row

A row of a D1 result.

D1Statement

A “prepared” D1 statement: the SQL and nothing else.

D1TransactionManager

Refuses every transaction.

D1Value

A value read out of a D1 result, already converted from JavaScript.

D1ValueRef

A borrowed D1Value, which is what Decode implementations read.

Enums

D1ArgumentValue

One SQLite value on the Rust side of the JavaScript boundary, in either direction: a parameter a query binds, or a value a result row holds.

D1TypeInfo

The storage class of a single value, which is all these backends report.

Traits

D1Executor

An executor for D1: &D1Connection or &mut D1Connection.

Type Aliases

D1BatchResult

What one statement of a D1Connection::fetch_batch did, and the rows it returned.