Struct D1Connection 

pub struct D1Connection { /* private fields */ }

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

There is no socket behind it and nothing to pool. Build one per request from the binding, with D1Connection::from_env or D1Connection::new.

Both &mut D1Connection and &D1Connection are sqlx executors. The binding is stateless, so a shared reference is enough to run a query, and one connection can serve concurrent queries within a request.

Implementations

impl D1Connection

pub fn execute_batch<'q, I>( &self, queries: I, ) -> impl Future<Output = Result<Vec<D1QueryResult>, Error>> + Send + '_

where I: IntoIterator<Item = Query<'q, D1, D1Arguments>>,

Runs queries as one D1 batch: in order, in one round trip, and atomically – if any statement fails, none of them take effect.

This is the D1 answer to a transaction, which it does not support across calls (see D1TransactionManager). Returns what each statement did, in the order given; for the rows each statement returns as well, see fetch_batch.

let results = conn
    .execute_batch([
        sqlx::query("UPDATE accounts SET balance = balance - ?1 WHERE id = ?2")
            .bind(amount)
            .bind(from),
        sqlx::query("UPDATE accounts SET balance = balance + ?1 WHERE id = ?2")
            .bind(amount)
            .bind(to),
    ])
    .await?;

Errors

When binding an argument fails, or when D1 rejects any statement – in which case the whole batch was rolled back.

pub fn fetch_batch<'q, I>( &self, queries: I, ) -> impl Stream<Item = Result<D1BatchResult, Error>> + Send + '_

where I: IntoIterator<Item = Query<'q, D1, D1Arguments>>,

Runs queries as one D1 batch, as execute_batch does, and streams each statement’s rows along with what it did, in the order given.

The shape sqlc’s :batchexec, :batchone and :batchmany queries take, each a stream with one item per statement – but atomic, and in one round trip. So unlike a loop of queries it is not lazy: the whole batch runs when the stream is first polled, and a failure is the one item it yields, with nothing applied.

use futures_util::TryStreamExt;
use sqlx::Row;

let names: Vec<String> = conn
    .fetch_batch([1_i64, 2, 3].map(|id| {
        sqlx::query("SELECT name FROM users WHERE id = ?").bind(id)
    }))
    .map_ok(|result| result.rows()[0].get("name"))
    .try_collect()
    .await?;

Rows come back keyed by name

D1’s batch() returns rows as objects, not the arrays the executor reads. Two columns with one name – SELECT a.id, b.id – collapse to the last, and a column named like an integer is ordered first. Alias such columns apart inside a batch.

Errors

The stream’s one item is an error when binding an argument fails, or when D1 rejects any statement – in which case the whole batch was rolled back.

impl D1Connection

pub fn new(db: D1Database) -> Self

Wraps a D1 binding.

pub fn from_env(env: &Env, binding: &str) -> Result<Self>

Looks up the D1 binding called binding in the Worker’s environment.

Errors

When there is no binding by that name, or it is not a D1 database.

pub fn database(&self) -> &D1Database

The binding this connection wraps, for anything this crate does not cover – dump, exec, sessions – while keeping the connection.

pub fn into_database(self) -> D1Database

The binding this connection wraps, giving up the connection. See database to borrow it instead.

Trait Implementations

impl<'c> Acquire<'c> for &'c mut D1Connection

type Database = D1

type Connection = &'c mut <D1 as Database>::Connection

fn acquire(self) -> BoxFuture<'c, Result<Self::Connection, Error>>

fn begin(self) -> BoxFuture<'c, Result<Transaction<'c, D1>, Error>>

impl Connection for D1Connection

fn begin( &mut self, ) -> impl Future<Output = Result<Transaction<'_, D1>, Error>> + Send + '_

Always fails – see D1TransactionManager.

type Database = D1

type Options = D1ConnectOptions

fn close(self) -> impl Future<Output = Result<(), Error>> + Send + 'static

Explicitly close this database connection.

fn ping(&mut self) -> impl Future<Output = Result<(), Error>> + Send + '_

Checks if a connection to the database is still valid.

fn shrink_buffers(&mut self)

Restore any buffers in the connection to their default capacity, if possible.

fn begin_with( &mut self, statement: impl SqlSafeStr, ) -> impl Future<Output = Result<Transaction<'_, Self::Database>, Error>> + Send

where Self: Sized,

Begin a new transaction with a custom statement.

fn is_in_transaction(&self) -> bool

Returns true if the connection is currently in a transaction.

fn transaction<'a, F, R, E>( &'a mut self, callback: F, ) -> impl Future<Output = Result<R, E>> + Send + 'a

where F: for<'c> FnOnce(&'c mut Transaction<'_, Self::Database>) -> Pin<Box<dyn Future<Output = Result<R, E>> + Send + 'c>> + 'a + for<'c> Send + for<'c> Sync, Self: Sized, R: Send, E: From<Error> + Send,

Execute the function inside a transaction.

fn connect( url: &str, ) -> impl Future<Output = Result<Self, Error>> + Send + 'static

where Self: Sized,

Establish a new database connection.

fn connect_with( options: &Self::Options, ) -> impl Future<Output = Result<Self, Error>> + Send

where Self: Sized,

Establish a new database connection with the provided options.

impl Debug for D1Connection

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'c> Executor<'c> for &'c D1Connection

fn execute<'e, 'q: 'e, E>( self, query: E, ) -> BoxFuture<'e, Result<D1QueryResult, Error>>

where E: 'q + Execute<'q, D1>, 'c: 'e,

Runs the query with run(), which reports rows_affected and last_insert_rowid but no rows.

fn fetch_many<'e, 'q: 'e, E>( self, query: E, ) -> BoxStream<'e, Result<Either<D1QueryResult, D1Row>, Error>>

where E: 'q + Execute<'q, D1>, 'c: 'e,

Yields the rows only, never a D1QueryResult: rows come from raw({ columnNames: true }), which reports nothing else. Use execute for what a statement changed.

type Database = D1

fn execute_many<'e, 'q: 'e, E>( self, query: E, ) -> BoxStream<'e, Result<D1QueryResult, Error>>

where E: 'q + Execute<'q, D1>, 'c: 'e,

Execute multiple queries and return the rows affected from each query, in a stream.

fn fetch_optional<'e, 'q: 'e, E>( self, query: E, ) -> BoxFuture<'e, Result<Option<D1Row>, Error>>

where E: 'q + Execute<'q, D1>, 'c: 'e,

Execute the query and returns at most one row.

fn prepare_with<'e>( self, sql: SqlStr, _parameters: &'e [D1TypeInfo], ) -> BoxFuture<'e, Result<D1Statement, Error>>

where 'c: 'e,

Prepare the SQL query, with parameter type information, to inspect the type information about its parameters and results.

fn fetch<'e, 'q, E>( self, query: E, ) -> Pin<Box<dyn Stream<Item = Result<<Self::Database as Database>::Row, Error>> + Send + 'e>>

where 'q: 'e, 'c: 'e, E: 'q + Execute<'q, Self::Database>,

Execute the query and return the generated results as a stream.

fn fetch_all<'e, 'q, E>( self, query: E, ) -> Pin<Box<dyn Future<Output = Result<Vec<<Self::Database as Database>::Row>, Error>> + Send + 'e>>

where 'q: 'e, 'c: 'e, E: 'q + Execute<'q, Self::Database>,

Execute the query and return all the generated results, collected into a Vec.

fn fetch_one<'e, 'q, E>( self, query: E, ) -> Pin<Box<dyn Future<Output = Result<<Self::Database as Database>::Row, Error>> + Send + 'e>>

where 'q: 'e, 'c: 'e, E: 'q + Execute<'q, Self::Database>,

Execute the query and returns exactly one row.

fn prepare<'e>( self, query: SqlStr, ) -> Pin<Box<dyn Future<Output = Result<<Self::Database as Database>::Statement, Error>> + Send + 'e>>

where 'c: 'e,

Prepare the SQL query to inspect the type information of its parameters and results.

impl<'c> Executor<'c> for &'c mut D1Connection

type Database = D1

fn execute<'e, 'q: 'e, E>( self, query: E, ) -> BoxFuture<'e, Result<D1QueryResult, Error>>

where E: 'q + Execute<'q, D1>, 'c: 'e,

Execute the query and return the total number of rows affected.

fn execute_many<'e, 'q: 'e, E>( self, query: E, ) -> BoxStream<'e, Result<D1QueryResult, Error>>

where E: 'q + Execute<'q, D1>, 'c: 'e,

Execute multiple queries and return the rows affected from each query, in a stream.

fn fetch_many<'e, 'q: 'e, E>( self, query: E, ) -> BoxStream<'e, Result<Either<D1QueryResult, D1Row>, Error>>

where E: 'q + Execute<'q, D1>, 'c: 'e,

Execute multiple queries and return the generated results as a stream from each query, in a stream.

fn fetch_optional<'e, 'q: 'e, E>( self, query: E, ) -> BoxFuture<'e, Result<Option<D1Row>, Error>>

where E: 'q + Execute<'q, D1>, 'c: 'e,

Execute the query and returns at most one row.

fn prepare_with<'e>( self, sql: SqlStr, parameters: &'e [D1TypeInfo], ) -> BoxFuture<'e, Result<D1Statement, Error>>

where 'c: 'e,

Prepare the SQL query, with parameter type information, to inspect the type information about its parameters and results.

fn fetch<'e, 'q, E>( self, query: E, ) -> Pin<Box<dyn Stream<Item = Result<<Self::Database as Database>::Row, Error>> + Send + 'e>>

where 'q: 'e, 'c: 'e, E: 'q + Execute<'q, Self::Database>,

Execute the query and return the generated results as a stream.

fn fetch_all<'e, 'q, E>( self, query: E, ) -> Pin<Box<dyn Future<Output = Result<Vec<<Self::Database as Database>::Row>, Error>> + Send + 'e>>

where 'q: 'e, 'c: 'e, E: 'q + Execute<'q, Self::Database>,

Execute the query and return all the generated results, collected into a Vec.

fn fetch_one<'e, 'q, E>( self, query: E, ) -> Pin<Box<dyn Future<Output = Result<<Self::Database as Database>::Row, Error>> + Send + 'e>>

where 'q: 'e, 'c: 'e, E: 'q + Execute<'q, Self::Database>,

Execute the query and returns exactly one row.

fn prepare<'e>( self, query: SqlStr, ) -> Pin<Box<dyn Future<Output = Result<<Self::Database as Database>::Statement, Error>> + Send + 'e>>

where 'c: 'e,

Prepare the SQL query to inspect the type information of its parameters and results.