Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
226 changes: 224 additions & 2 deletions docs/guide/database/d1.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,15 @@ await db.batch([

Void enables [D1 read replication](https://developers.cloudflare.com/d1/best-practices/read-replication/) when it provisions a database. To enable it on an existing database, run `void deploy --platform cloudflare --provision`. Queries through `db` from `void/db` use a D1 session for each Void request, so reads can run near the request and later queries in that request see at least the same data. Framework handlers without Void's request scope start each database operation on the primary. `createDb` starts a replica-capable session for the binding you pass it.

Replicas can lag between requests. Authentication checks use the primary so a lagging replica can't accept a revoked session. For other reads that need the latest primary data, create a client inside the request:
::: warning
Replicas can lag between requests. [Carry a bookmark](#cross-request-bookmarks) to preserve previously observed database state, or use a [primary-first session](#reading-from-the-primary) when you need the latest primary data.
:::

For raw D1 calls or another query library, use `withSession()` to read from replicas. A bare D1 binding reads from the primary.

### Avoid stale reads with a primary-first session {#reading-from-the-primary}

Authentication checks use the primary so a lagging replica can't accept a revoked session. For other reads that need the latest primary data, create a client inside the request:

```ts
import { users } from '@schema';
Expand All @@ -59,7 +67,221 @@ export const GET = defineHandler(async () => {

With `session: 'first-primary'`, the first query reads from the primary and later queries see at least the same data. The default, `'first-unconstrained'`, allows the first query to use a replica.

For raw D1 calls or another query library, use `withSession()` to read from replicas. A bare D1 binding reads from the primary.
### See your writes in subsequent requests {#cross-request-bookmarks}

To make a read after a save see that save in a later request, carry a [D1 bookmark](https://developers.cloudflare.com/d1/best-practices/read-replication/#start-a-session-from-previous-context-bookmark) between requests. A bookmark allows D1 to use a replica that has caught up to at least the previously observed database state.

::: warning
Bookmarks do not affect cached responses. Disable ISR for pages that require fresh reads (`export const revalidate = 0` in the page's `.server.ts` file), and do not serve these requests from shared response caches.
:::

Use middleware to set the default `db` session before your handlers or Pages loaders run, and return its bookmark after their queries. For a browser app, a cookie carries it through redirects and navigation:

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Low — defer() queries miss the bookmark.

Pages defer() data streams after the response is returned, so the middleware reads getBookmark() before those queries finish. One sentence would cover it: queries inside defer() callbacks don't update the returned bookmark, so do writes that need read-your-writes before the loader returns.


Local server-side requests through `void/client` share that session. If middleware runs again, repeating an already satisfied session requirement preserves the session and its database progress. For an independent primary-first read or a newer bookmark after using `db`, use `createDb` instead.

::: warning
Concurrent responses can overwrite this cookie with an older bookmark. The [header-based recipe](#api-requests-with-concurrent-clients) retains the newest bookmark across concurrent API responses. Clearing or expiring bookmark storage starts a new bookmark chain.
:::

::: note
To use cookies and API headers together, see [Supporting both transports](#supporting-both-transports).
:::

```ts
// middleware/01.database.ts
import { getCookie, setCookie } from 'hono/cookie';
import { defineMiddleware } from 'void';
import { getBookmark, setSession } from 'void/db';

export default defineMiddleware(async (c, next) => {
setSession(getCookie(c, 'db-bookmark') ?? 'first-unconstrained');

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Low (not proven) — the bookmark comes from the client.

The cookie or header value goes straight to setSession(). Cloudflare's own examples do the same, so this isn't a blocker. But workerd keeps the bookmark that sorts highest, so a bad value that sorts above real ones never gets replaced and stays in the cookie. A short note (check the shape, fall back to 'first-unconstrained' on a bookmark error, or name the cookie per database) would help.

await next();

const bookmark = getBookmark();
if (bookmark) {
setCookie(c, 'db-bookmark', bookmark, {
httpOnly: true,
secure: new URL(c.req.url).protocol === 'https:',
sameSite: 'Lax',
path: '/',
});
}
c.header('Cache-Control', 'private, no-store');

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Medium — this recipe turns off ISR and shared caching for the whole app.

This is global middleware with no path filter. After next() it always sets Cache-Control: private, no-store (this replaces whatever the route set) and a Set-Cookie whenever there is a bookmark. In @void/isr, hasSharedCacheOptOut treats either one as an opt-out, so every ISR or cached route stops caching. The "Supporting both transports" recipe has the same problem.

Suggestion: limit it to the paths that need read-your-writes (as the header recipe does with /api/), don't replace a Cache-Control the handler already set, and say clearly that the routes it covers are not cached.

});
```

#### API requests with concurrent clients

For browser API requests, exchange an `X-DB-Bookmark` header and retain the newest bookmark. [D1 bookmarks are lexicographically sortable](https://developers.cloudflare.com/d1/reference/time-travel/#bookmarks), so an older response must not replace a newer bookmark from the same database.

For requests made through the browser fetch wrapper below, exchange bookmarks using this middleware:

::: warning
This recipe carries bookmarks only through the fetch wrapper below, not ordinary navigation, form submissions, or Pages requests. It does not share bookmarks with the cookie-based recipe.
:::

::: note
To use cookies and API headers together, see [Supporting both transports](#supporting-both-transports).
:::

```ts
// middleware/01.database.ts
import { defineMiddleware } from 'void';
import { getBookmark, setSession } from 'void/db';

export default defineMiddleware(async (c, next) => {
if (!c.req.path.startsWith('/api/')) {
await next();
return;
}

setSession(c.req.header('X-DB-Bookmark') ?? 'first-unconstrained');
await next();
const bookmark = getBookmark();
if (bookmark) {
c.header('X-DB-Bookmark', bookmark);
}
c.header('Cache-Control', 'private, no-store');
});
```

On the browser, send the saved bookmark and atomically retain the newest returned value using [Web Locks](https://developer.mozilla.org/en-US/docs/Web/API/Web_Locks_API). This requires HTTPS (or localhost), browser storage, and Web Locks support. Use a scope unique to the database and signed-in account; same-origin tabs with the same scope share progress.

```ts
// src/bookmark-fetch.ts
export function createBookmarkFetch(scope: string) {
const key = `d1-bookmark:${scope}`;

return async function bookmarkFetch(path: string, init: RequestInit = {}): Promise<Response> {
const url = new URL(path, location.origin);
if (url.origin !== location.origin || !url.pathname.startsWith('/api/')) {
throw new Error('bookmarkFetch requires a same-origin /api/ URL.');
}

const bookmark = localStorage.getItem(key);
const headers = new Headers(init.headers);
headers.delete('X-DB-Bookmark');
if (bookmark) headers.set('X-DB-Bookmark', bookmark);

const response = await fetch(url, {
...init,
headers,
credentials: 'same-origin',
cache: 'no-store',
redirect: 'error',
});

const returned = response.headers.get('X-DB-Bookmark');
if (returned) {
await navigator.locks.request(key, () => {
const current = localStorage.getItem(key);
if (current === null || returned > current) {
localStorage.setItem(key, returned);
}
});
}

return response;
};
}
```

Use the wrapper for each participating API request. For example, with an existing profile API:

```ts
import { createBookmarkFetch } from './bookmark-fetch';

export async function saveAndReadProfile(accountId: string, name: string) {
const api = createBookmarkFetch(`app-db:${accountId}`);
const saved = await api('/api/profile', {
method: 'POST',
headers: { 'Content-Type': 'text/plain' },
body: name,
});
if (!saved.ok) throw new Error(`Save failed: ${saved.status}`);

// Sends at least the completed save's bookmark.
const response = await api('/api/profile');
if (!response.ok) throw new Error(`Read failed: ${response.status}`);
return response.json();
}
```

The wrapper saves the newest bookmark before resolving, so subsequent requests inherit its progress even if concurrent responses arrive out of order.

Use API endpoints that return data, not redirects.

#### Supporting both transports

Use this single middleware with the fetch wrapper above to support API requests alongside browser navigation and forms. It selects the newest incoming bookmark for the same database and returns it through both transports.

::: warning
The fetch wrapper retains the newest bookmark across concurrent responses, but cookies can still be overwritten out of order. For a guaranteed fresh read on a redirect's destination page, use a primary-first session.
:::

```ts
// middleware/01.database.ts
import { getCookie, setCookie } from 'hono/cookie';
import { defineMiddleware } from 'void';
import { getBookmark, setSession } from 'void/db';

export default defineMiddleware(async (c, next) => {
const incoming: string[] = [];

// Cookie input: navigation, forms, and same-origin fetch requests.
// Remove for header-only use.
const cookieBookmark = getCookie(c, 'db-bookmark');
if (cookieBookmark) incoming.push(cookieBookmark);

// Header input: the fetch wrapper's saved progress.
// Remove for cookie-only use.
const headerBookmark = c.req.header('X-DB-Bookmark');
if (headerBookmark) incoming.push(headerBookmark);

// Bookmarks from the same database sort oldest to newest.
setSession(incoming.sort().at(-1) ?? 'first-unconstrained');
await next();

const bookmark = getBookmark();
if (bookmark) {
// Cookie output: progress for subsequent navigation and forms.
// Remove for header-only use.
setCookie(c, 'db-bookmark', bookmark, {
httpOnly: true,
secure: new URL(c.req.url).protocol === 'https:',
sameSite: 'Lax',
path: '/',
});

// Header output: progress for the fetch wrapper.
// Remove for cookie-only use.
c.header('X-DB-Bookmark', bookmark);
}

c.header('Cache-Control', 'private, no-store');
});
```

#### Using `createDb`

For another D1 binding or a framework-owned endpoint, such as an Astro API route, create a client with the incoming bookmark. After querying, return `getBookmark(client)` in the response header:

```ts
import { users } from '@schema';
import { createDb, getBookmark } from 'void/db';

export async function readUsers(request: Request, binding: D1Database) {
const client = createDb(binding, {
session: request.headers.get('X-DB-Bookmark') ?? 'first-unconstrained',
});
const result = await client.select().from(users).all();

const headers = new Headers({ 'Cache-Control': 'private, no-store' });
const bookmark = getBookmark(client);
if (bookmark) headers.set('X-DB-Bookmark', bookmark);
return Response.json(result, { headers });
}
```

## Alternative Query Layers

Expand Down
2 changes: 1 addition & 1 deletion docs/reference/api.md
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,7 @@ Import Void's app-facing APIs from these paths:
| `void/schema-pg` | Re-exports [`drizzle-orm/pg-core`](https://orm.drizzle.team/docs/column-types/pg) for PostgreSQL table and column builders |
| `void/schema-mysql` | Re-exports `drizzle-orm/mysql-core` for MySQL table and column builders |
| `void/database-provider` | `defineDatabaseProvider` and adapter types for `void db connect --provider` |
| `void/db` | `db` (Drizzle D1, PostgreSQL, or MySQL instance for the active dialect), `createDb`, query operators (`eq`, `and`, `or`, `desc`, `like`, `inArray`, etc.) |
| `void/db` | `db` (Drizzle D1, PostgreSQL, or MySQL instance for the active dialect), `createDb`, D1 session helpers (`setSession`, `getBookmark`), query operators (`eq`, `and`, `or`, `desc`, `like`, `inArray`, etc.) |
| `void/seed` | `defineSeed`, `SeedContext`, `SeedFn` for programmatic `void db seed` modules |
| `void/kv` | `kv`, `createKV`, typed KV client/map types |
| `void/storage` | `storage`, `createStorage` for the inferred R2 binding or a specific `R2Bucket` |
Expand Down
32 changes: 30 additions & 2 deletions docs/reference/api/database.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,9 @@ 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 [Read replication](../../guide/database/d1.md#read-replication).
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](../../guide/database/d1.md#reading-from-the-primary).

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`](../../guide/database/d1.md#using-createdb) for an example.

For PostgreSQL and MySQL projects, pass a connection string.

Expand All @@ -53,7 +55,7 @@ const db = createDb('postgres://user:password@host:5432/app');
// D1
function createDb(
d1: D1Database,
options?: { session?: D1SessionConstraint },
options?: { session?: D1SessionConstraint | D1SessionBookmark },
): DrizzleD1Database<Schema>;

// PostgreSQL
Expand All @@ -63,6 +65,32 @@ function createDb(connectionString: string): NodePgDatabase<Schema>;
function createDb(connectionString: string): MySql2Database<Schema>;
```

## `setSession(start)` {#setsession}

D1 only. Set the starting bookmark or constraint for the default request's `db`. Call it in middleware before the first use of `db`. It does not change explicitly created clients or later requests.

Passing `'first-unconstrained'` preserves any bookmark or primary-first requirement already configured, even before the first use of `db`. Other starting values replace the configuration until the session opens.

After the session opens, repeated calls preserve it when the requirement is already satisfied: the original starting value, `'first-unconstrained'`, or a bookmark no newer than the session's current bookmark. This lets middleware run again during a local server-side fetch without resetting database progress. Repeating `'first-primary'` does not force another primary read.

A newer bookmark or changing an opened session to `'first-primary'` throws. Configure these before using `db`, or use `createDb(binding, { session })` for an independent session.

```ts
function setSession(start: D1SessionConstraint | D1SessionBookmark): void;
```

## `getBookmark(client?)` {#getbookmark}

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.

```ts
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](../../guide/database/d1.md#using-createdb) instead.

For cookie and header middleware, a browser fetch wrapper, and guidance on combining both transports, see [See your writes in subsequent requests](../../guide/database/d1.md#cross-request-bookmarks).

## Query Operators {#query-operators}

`void/db` re-exports commonly used [Drizzle operators](https://orm.drizzle.team/docs/operators) so you never need to depend on `drizzle-orm` directly:
Expand Down
1 change: 1 addition & 0 deletions packages/void/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,7 @@
"type": "module",
"imports": {
"#self/_env": "./dist/runtime/env/runtime.mjs",
"#self/runtime/db-session": "./dist/runtime/db/session.mjs",
"#self/email": "./dist/runtime/email/index.mjs",
"#self/env": "./dist/runtime/env/public.mjs",
"#self/client": "./dist/runtime/client/index.mjs",
Expand Down
1 change: 1 addition & 0 deletions packages/void/skills/void/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,7 @@ Use `void deploy --skip-migrations` when database migrations run separately; it
| Server/API routing and middleware | `docs/guide/server-routing.md`, `docs/integrations/hono.md` |
| Pages mode, loader/action, forms, layouts | `docs/guide/pages-routing/*.md`, `docs/guide/type-safety.md` |
| Database and migrations | `docs/guide/database.md`, `docs/guide/type-safety.md` |
| D1 replicas, bookmarks, read-after-write | `docs/guide/database/d1.md`, `docs/reference/api/database.md` |
| Typed fetch and end-to-end typing | `docs/guide/typed-fetch.md`, `docs/guide/type-safety.md` |
| Authentication | `docs/guide/auth.md`, `docs/reference/api/auth.md`, `docs/guide/env-vars.md` |
| Cloudflare runtime bindings and config | `docs/integrations/cloudflare.md`, `docs/reference/config.md`, `docs/guide/env-vars.md` |
Expand Down
Loading
Loading