Database and Seeding
Imported from "void/db". The db export is a Drizzle ORM instance for the configured database dialect: Cloudflare D1 by default, PostgreSQL with "database": "pg", or MySQL with "database": "mysql".
db
Default Drizzle instance, pre-wired with your schema from db/schema.ts.
import { users } from '@schema';
import { db } from 'void/db';
const allUsers = await db.select().from(users).all();db uses your configured dialect and schema.
- D1 projects resolve the
DBbinding and exposeDrizzleD1Database<Schema>. - PostgreSQL projects use
DATABASE_URLduring local development and Hyperdrive'sconnectionStringin production, exposingNodePgDatabase<Schema>. - MySQL projects use the same connection sources and expose
MySql2Database<Schema>.
createDb(database)
Creates a Drizzle instance for the active dialect.
For D1 projects, pass a specific D1 binding. Use this when you have multiple D1 databases or need a non-default binding.
import { env } from 'cloudflare:workers';
import { createDb } from 'void/db';
const db = createDb(env.MY_OTHER_DB);For a fresh D1 read, pass { session: 'first-primary' } and create the client inside the request. The default, 'first-unconstrained', allows the first query to use a replica. Both keep your schema and query types. See Avoid stale reads with a primary-first session.
The session option also accepts a D1 bookmark from a previous request. Use getBookmark(client) after queries to obtain the bookmark to return to your client. See Using createDb for an example.
For PostgreSQL and MySQL projects, pass a connection string.
import { createDb } from 'void/db';
const db = createDb('postgres://user:password@host:5432/app');Signature:
// D1
function createDb(
d1: D1Database,
options?: { session?: D1SessionConstraint | D1SessionBookmark },
): DrizzleD1Database<Schema>;
// PostgreSQL
function createDb(connectionString: string): NodePgDatabase<Schema>;
// MySQL
function createDb(connectionString: string): MySql2Database<Schema>;setSession(start)
D1 only. Set the starting bookmark or constraint for the default request's db. Call it in middleware before the first use of db; calling it after that throws. It does not change explicitly created clients or later requests.
function setSession(start: D1SessionConstraint | D1SessionBookmark): void;getBookmark(client?)
D1 only. Return the default request session's bookmark, or pass a client returned by createDb() to read that client's bookmark. Returns null when no bookmark is available. Reading the default bookmark does not open a database session.
function getBookmark(client?: DrizzleD1Database<Schema>): D1SessionBookmark | null;setSession() and the no-argument getBookmark() require Void's request scope. For a framework-owned endpoint, such as an Astro API route, use an explicit client instead.
For cookie and header middleware, a browser fetch wrapper, and guidance on combining both transports, see See your writes in subsequent requests.
Query Operators
void/db re-exports commonly used Drizzle operators so you never need to depend on drizzle-orm directly:
import { db, eq, and, or, desc, like, inArray, sql } from 'void/db';Full list: sql, eq, ne, gt, gte, lt, lte, and, or, not, desc, asc, like, ilike, notLike, inArray, notInArray, isNull, isNotNull, between, notBetween, exists, notExists, count, sum, avg, min, max.
Use the exported Drizzle types SQL, SQLWrapper, AnyColumn, and BatchItem to type query helpers and batches:
import { posts } from '@schema';
import { db, sql, type BatchItem, type SQL, type SQLWrapper } from 'void/db';
function contains(column: SQLWrapper, text: string): SQL {
return sql`instr(${column}, ${text}) > 0`;
}
// D1 only: `db.batch()` takes at least one query.
const writes: [BatchItem<'sqlite'>, ...Array<BatchItem<'sqlite'>>] = [
db.update(posts).set({ published: true }).where(contains(posts.title, 'void')),
];
await db.batch(writes);Seeding
Imported from "void/seed".
defineSeed(fn)
Identity helper for programmatic seed modules used by void db seed.
import { defineSeed } from 'void/seed';
export default defineSeed<typeof import('./schema')>(async ({ db, schema }) => {
await db.insert(schema.users).values([
{ name: 'Alice', email: 'alice@example.com' },
{ name: 'Bob', email: 'bob@example.com' },
]);
});The callback receives:
dialect:"sqlite","postgresql", or"mysql"db: a local Drizzle instance for the active dialectschema: the exports fromdb/schema.tsordb/schema/
Seed modules can export either default or a named seed function.