Skip to content

Search the guides, deployment pages, and API reference.

View as Markdown

D1DatabaseDriver

import { D1DatabaseDriver } from "@pitlane/data-table-d1";

A DatabaseDriver backed by a Cloudflare D1 binding.

Statements are compiled by the same SQLite compiler @remix-run/data-table uses, then executed through D1's async prepared-statement API. Pass it to Database, or use createD1Database to get one already wired.

Implements

  • DatabaseDriver<"sqlite">

Constructors

Constructor

new D1DatabaseDriver(d1, options?): D1DatabaseDriver;

Parameters

d1

D1Binding

options?

D1DriverOptions = {}

Returns

D1DatabaseDriver

Accessors

capabilities

Get Signature

get capabilities(): Readonly<{


  migrationLock: false;


  returning: true;


  savepoints: false;


  transactionalDdl: false;


  upsert: true;


}>;

Immutable feature flags used by shared query and migration behavior.

Returns

Readonly<{ migrationLock: false; returning: true; savepoints: false; transactionalDdl: false; upsert: true; }>

Implementation of

DatabaseDriver.capabilities

dialect

Get Signature

get dialect(): "sqlite";

Stable identifier for the SQL dialect.

Returns

"sqlite"

Implementation of

DatabaseDriver.dialect

Methods

batch()

batch(statements): Promise<D1BatchResult[]>;

Runs statements together, atomically, through D1's batch().

This is the answer to "several writes must land together" on a database with no transactions. batch() is D1's only atomic primitive: it takes every statement up front and commits them as a unit, which is why it cannot back transaction() but can back this.

Statements are SqlStatements, so sql from remix/data-table parameterises them and there is no reaching for the raw binding:

await db.batch([


    sql`insert into post (title) values (${title})`,


    sql`update counter set posts = posts + 1`,


]);

Parameters

statements

SqlStatement[]

The statements to run, in order.

Returns

Promise<D1BatchResult[]>

One result per statement, in the same order.

beginTransaction()

beginTransaction(_options?): Promise<TransactionToken>;

Opens a transaction, if the caller accepted that it will not be one.

No BEGIN is sent, because D1 rejects it. The token exists so Database has something to carry; statements inside the scope run and commit exactly as they would outside it.

Parameters

_options?

TransactionOptions

Returns

Promise<TransactionToken>

Implementation of

DatabaseDriver.beginTransaction

close()

close(): void;

A binding is owned by the runtime; there is no connection to release.

Returns

void

Implementation of

DatabaseDriver.close

commitTransaction()

commitTransaction(_token): Promise<void>;

Nothing to commit: every statement in the scope already did.

Parameters

_token

TransactionToken

Returns

Promise<void>

Implementation of

DatabaseDriver.commitTransaction

createSavepoint()

createSavepoint(_token, _name): Promise<void>;

Creates a savepoint inside an open transaction.

Parameters

_token

TransactionToken

_name

string

Returns

Promise<void>

Implementation of

DatabaseDriver.createSavepoint

execute()

execute(request): Promise<DataManipulationResult>;

Executes a data-manipulation request.

Parameters

request

DataManipulationRequest

Returns

Promise<DataManipulationResult>

Implementation of

DatabaseDriver.execute

executeScript()

executeScript(sql, _transaction?): Promise<void>;

Executes a raw SQL script that may contain multiple statements.

Parameters

sql

string

_transaction?

TransactionToken

Returns

Promise<void>

Implementation of

DatabaseDriver.executeScript

hasColumn()

hasColumn(


   table,


   column,


_transaction?): Promise<boolean>;

Checks whether a column exists on a table.

Parameters

table

TableRef

column

string

_transaction?

TransactionToken

Returns

Promise<boolean>

Implementation of

DatabaseDriver.hasColumn

hasTable()

hasTable(table, _transaction?): Promise<boolean>;

Checks whether a table exists.

Parameters

table

TableRef

_transaction?

TransactionToken

Returns

Promise<boolean>

Implementation of

DatabaseDriver.hasTable

releaseSavepoint()

releaseSavepoint(_token, _name): Promise<void>;

Releases a previously created savepoint.

Parameters

_token

TransactionToken

_name

string

Returns

Promise<void>

Implementation of

DatabaseDriver.releaseSavepoint

rollbackToSavepoint()

rollbackToSavepoint(_token, _name): Promise<void>;

Rolls back to a previously created savepoint.

Parameters

_token

TransactionToken

_name

string

Returns

Promise<void>

Implementation of

DatabaseDriver.rollbackToSavepoint

rollbackTransaction()

rollbackTransaction(_token): Promise<void>;

Nothing to roll back. This is the cost of unsafe-nonatomic, and it is silent by necessity: Database calls this while unwinding a failed callback, and throwing here would replace the caller's error with an AggregateError about a rollback that was never possible.

Parameters

_token

TransactionToken

Returns

Promise<void>

Implementation of

DatabaseDriver.rollbackTransaction

wipe()

wipe(): Promise<void>;

Drops every table the application owns.

D1 keeps its own bookkeeping in _cf_* tables and SQLite keeps sqlite_*; dropping either breaks the binding, so both are left alone. There is no file to delete the way the SQLite driver deletes one.

Returns

Promise<void>

Implementation of

DatabaseDriver.wipe