Logging
Log the SQL your Worker sends with an onQuery listener.
At a glance
| To | Write |
|---|---|
| log every query, app-wide | static override onQuery on ApplicationRecord |
| log one request’s queries, with its ID | withDatabase(connect(env.DB, { onQuery }), …) |
| send the database time to the browser | add up durationMs into a Server-Timing header |
| keep more attributes out of the logs | static override filterAttributes = [...Model.filterAttributes, "iban"] |
The Models
The examples use this Model, whose attributes come from its table through the schema active-record schema generates, and the app’s Worker:
import { ApplicationRecord } from "./application-record";
export class User extends ApplicationRecord {}import { Model, type QueryListener } from "@forestfuture/active-record";
import { schema } from "../db/schema";
export abstract class ApplicationRecord extends Model {
static override schema = schema;
// Every query, from every Model, whichever database runs it.
static override onQuery: QueryListener = ({ model, sql, durationMs, error }) => {
console.log(`${model} ${durationMs.toFixed(1)}ms ${sql}`, error ?? "");
};
// The defaults, plus an IBAN and a date of birth.
static override filterAttributes = [...Model.filterAttributes, "iban", /^dateOfBirth$/];
}import { User } from "./models/user";
// The app's Worker: here, one route that finds a user by email.
export const app = {
async fetch(request) {
const email = new URL(request.url).searchParams.get("email") ?? "";
const user = await User.findByOrThrow({ email });
return Response.json({ id: user.id });
},
} satisfies ExportedHandler<Env>;// Generated by `active-record schema` from migrations/ — don't edit.
// schema: cf0bc7e86bda
import { defineSchema, type TableAttributes } from "@forestfuture/active-record";
import { d1 } from "@forestfuture/active-record/d1";
/** users — last changed by 0001_create_tables.sql */
export const users = {
id: { type: "string", null: false, generateId: true },
email: { type: "string", null: false },
iban: "string",
dateOfBirth: "string",
} as const;
/** The database's adapter and binding, its tables (with their primary keys), and the Models built on them. */
export const schema = defineSchema({
adapter: d1({ binding: "DB" }),
tables: {
users: { attributes: users, primaryKey: "id" },
},
models: { User: "users" },
});
declare module "../models/user" {
interface User extends TableAttributes<typeof users, (typeof User)["attributes"]> {}
}CREATE TABLE users (
id TEXT PRIMARY KEY NOT NULL,
email TEXT NOT NULL,
iban TEXT,
date_of_birth TEXT
);CREATE TABLE users (
id UUID PRIMARY KEY,
email TEXT NOT NULL,
iban TEXT,
date_of_birth TEXT
);Receiving each query
An onQuery listener is called once for every statement, writes and batches included, with:
| Field | |
|---|---|
model |
The Model’s class name, such as "Product" |
sql, params |
The statement and its bound values |
durationMs |
How long it took; in a D1 batch, D1’s own timing for each statement |
meta |
The database’s result metadata, such as D1’s rows read and written |
error |
The database’s error, when it failed |
Send these wherever you like. A listener never changes a query’s outcome: one that throws is logged with console.error, and the query’s result stands.
Set a listener in one of two places:
| Where | Knows the request? | |
|---|---|---|
| Every query, app-wide | static override onQuery on your app’s base class |
No |
| One request’s queries | connect(env.DB, { onQuery }), run in withDatabase |
Yes |
If both are set, the request’s listener runs first, then the base class’s.
Logging every query
Set onQuery on your app’s base class, in application-record.ts, to see every statement of every Model:
import { Model, type QueryListener } from "@forestfuture/active-record";
import { schema } from "../db/schema";
export abstract class ApplicationRecord extends Model {
static override schema = schema;
// Every query, from every Model, whichever database runs it.
static override onQuery: QueryListener = ({ model, sql, durationMs, error }) => {
console.log(`${model} ${durationMs.toFixed(1)}ms ${sql}`, error ?? "");
};
// The defaults, plus an IBAN and a date of birth.
static override filterAttributes = [...Model.filterAttributes, "iban", /^dateOfBirth$/];
}
It can’t tell requests apart. A Model can set its own static override onQuery, which replaces the base class’s for that Model.
Logging one request’s queries
To group a request’s queries, open its database with a listener that knows the request, and run the request inside withDatabase:
import { function withDatabase<R>(databases: AnyDatabase | readonly AnyDatabase[], fn: () => R | Promise<R>): Promise<R>Runs `fn` with `databases` as the request's own: queries started from a Model inside it (and
everything it awaits) use the one on that Model's binding, with its Session and `onQuery`.
Usually called once per request, in middleware. Nested calls add to the outer ones.
Each call is a scope of its own, even with a Database another request shares. An adapter may
hold a connection for the scope (the PostgreSQL adapter does, from a connection string). A nested call with
the same Database shares the outer call's scope while that call is running. When `fn` settles,
the scope ends, and the adapter lets its connection go once the queries still running on it
finish. Work that outlives the scope, such as a `waitUntil` save, gets a connection of its own.withDatabase } from "@forestfuture/active-record";
import { function connect(binding: D1Database, options?: ConnectOptions): Databaseconnect } from "@forestfuture/active-record/d1";
import { const app: {
fetch(request: Request<unknown, IncomingRequestCfProperties<unknown>>): Promise<Response>;
}
app } from "./app";
// src/worker.ts: one request's queries, tagged with its ID, as JSON lines for Workers Logs.
export const const worker: {
fetch(request: Request<unknown, IncomingRequestCfProperties<unknown>>, env: Env): Promise<Response>;
}
worker = {
ExportedHandler<Env, unknown, unknown, unknown>.fetch?: ExportedHandlerFetchHandler<Env, unknown, unknown> | undefinedfetch(request: Request<unknown, IncomingRequestCfProperties<unknown>>request, env: Envenv) {
const const requestId: stringrequestId = request: Request<unknown, IncomingRequestCfProperties<unknown>>request.Request<unknown, IncomingRequestCfProperties<unknown>>.headers: HeadersThe **`headers`** read-only property of the Request interface contains the Headers object associated with the request.
[MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/headers)headers.Headers.get(name: string): string | nullThe **`get()`** method of the Headers interface returns a byte string of all the values of a header within a Headers object with a given name. If the requested header doesn't exist in the Headers object, it returns null.
[MDN Reference](https://developer.mozilla.org/docs/Web/API/Headers/get)get("cf-ray") ?? var crypto: Crypto[MDN Reference](https://developer.mozilla.org/docs/Web/API/Window/crypto)crypto.Crypto.randomUUID(): `${string}-${string}-${string}-${string}-${string}`The **`randomUUID()`** method of the Crypto interface is used to generate a v4 UUID using a cryptographically secure random number generator.
Available only in secure contexts.
[MDN Reference](https://developer.mozilla.org/docs/Web/API/Crypto/randomUUID)randomUUID();
const const db: Databasedb = function connect(binding: D1Database, options?: ConnectOptions): Databaseconnect(env: Envenv.Env.DB: D1DatabaseDB, {
ConnectOptions.onQuery?: QueryListener | undefinedCalled once for every statement sent to D1, with D1's `meta`.onQuery: ({ model: stringThe Model the statement is for: its class name (`"Product"`). It's `""` for an anonymous
class, and a bundler that renames classes changes it; Wrangler keeps names by default.model, sql: stringsql, params: unknown[]params, durationMs: numberdurationMs, error: unknownerror }) =>
var console: Consoleconsole.Console.log(...data: any[]): void (+1 overload)The **`console.log()`** static method outputs a message to the console.
[MDN Reference](https://developer.mozilla.org/docs/Web/API/console/log_static)log(
var JSON: JSONAn intrinsic object that provides functions to convert JavaScript values to and from the JavaScript Object Notation (JSON) format.JSON.JSON.stringify(value: any, replacer?: (this: any, key: string, value: any) => any, space?: string | number): string (+1 overload)Converts a JavaScript value to a JavaScript Object Notation (JSON) string.stringify({
requestId: stringrequestId,
model: stringmodel,
ms: numberms: var Math: MathAn intrinsic object that provides basic mathematics functionality and constants.Math.Math.round(x: number): numberReturns a supplied numeric expression rounded to the nearest integer.round(durationMs: numberdurationMs),
sql: stringsql,
params: unknown[]params, // a filtered attribute's value is "[FILTERED]"
error: string | undefinederror: error: unknownerror instanceof var Error: ErrorConstructorError ? error: Errorerror.Error.message: stringmessage : var undefinedundefined,
}),
),
});
// Every query from a Model inside (User.findBy, user.save(), …) goes through db.
return withDatabase<Response>(databases: AnyDatabase | readonly AnyDatabase[], fn: () => Response | Promise<Response>): Promise<Response>Runs `fn` with `databases` as the request's own: queries started from a Model inside it (and
everything it awaits) use the one on that Model's binding, with its Session and `onQuery`.
Usually called once per request, in middleware. Nested calls add to the outer ones.
Each call is a scope of its own, even with a Database another request shares. An adapter may
hold a connection for the scope (the PostgreSQL adapter does, from a connection string). A nested call with
the same Database shares the outer call's scope while that call is running. When `fn` settles,
the scope ends, and the adapter lets its connection go once the queries still running on it
finish. Work that outlives the scope, such as a `waitUntil` save, gets a connection of its own.withDatabase(const db: Databasedb, () => const app: {
fetch(request: Request<unknown, IncomingRequestCfProperties<unknown>>): Promise<Response>;
}
app.function fetch(request: Request<unknown, IncomingRequestCfProperties<unknown>>): Promise<Response>fetch(request: Request<unknown, IncomingRequestCfProperties<unknown>>request));
},
} satisfies interface ExportedHandler<Env = unknown, QueueHandlerMessage = unknown, CfHostMetadata = unknown, Props = unknown>ExportedHandler<Env>;Logged as JSON, each line can be filtered by requestId in Workers Logs. Turn them on with "observability": { "enabled": true } in your Wrangler config.
Logging only in development
Check a variable that only .dev.vars sets, such as LOG_SQL=1. For one request’s listener:
import { type type QueryListener<Meta = unknown> = (event: QueryEvent<Meta>) => voidHears each statement's `QueryEvent`. Declared as a method's type, so a listener typed for one
adapter's `meta` (a D1 app's base class) can be a Model's `static onQuery`, which any adapter calls.QueryListener, function withDatabase<R>(databases: AnyDatabase | readonly AnyDatabase[], fn: () => R | Promise<R>): Promise<R>Runs `fn` with `databases` as the request's own: queries started from a Model inside it (and
everything it awaits) use the one on that Model's binding, with its Session and `onQuery`.
Usually called once per request, in middleware. Nested calls add to the outer ones.
Each call is a scope of its own, even with a Database another request shares. An adapter may
hold a connection for the scope (the PostgreSQL adapter does, from a connection string). A nested call with
the same Database shares the outer call's scope while that call is running. When `fn` settles,
the scope ends, and the adapter lets its connection go once the queries still running on it
finish. Work that outlives the scope, such as a `waitUntil` save, gets a connection of its own.withDatabase } from "@forestfuture/active-record";
import { function connect(binding: D1Database, options?: ConnectOptions): Databaseconnect } from "@forestfuture/active-record/d1";
import { const app: {
fetch(request: Request<unknown, IncomingRequestCfProperties<unknown>>): Promise<Response>;
}
app } from "./app";
// src/worker.ts, with LOG_SQL=1 in .dev.vars: logging in development only, nothing in production.
export const const development: {
fetch(request: Request<unknown, IncomingRequestCfProperties<unknown>>, env: Env): Promise<Response>;
}
development = {
ExportedHandler<Env, unknown, unknown, unknown>.fetch?: ExportedHandlerFetchHandler<Env, unknown, unknown> | undefinedfetch(request: Request<unknown, IncomingRequestCfProperties<unknown>>request, env: Envenv) {
const const onQuery: QueryListener | undefinedonQuery: type QueryListener<Meta = unknown> = (event: QueryEvent<Meta>) => voidHears each statement's `QueryEvent`. Declared as a method's type, so a listener typed for one
adapter's `meta` (a D1 app's base class) can be a Model's `static onQuery`, which any adapter calls.QueryListener | undefined = env: Envenv.Env.LOG_SQL?: string | undefinedLOG_SQL
? ({ model: stringThe Model the statement is for: its class name (`"Product"`). It's `""` for an anonymous
class, and a bundler that renames classes changes it; Wrangler keeps names by default.model, sql: stringsql, durationMs: numberdurationMs }) => var console: Consoleconsole.Console.log(...data: any[]): void (+1 overload)The **`console.log()`** static method outputs a message to the console.
[MDN Reference](https://developer.mozilla.org/docs/Web/API/console/log_static)log(`${model: stringThe Model the statement is for: its class name (`"Product"`). It's `""` for an anonymous
class, and a bundler that renames classes changes it; Wrangler keeps names by default.model} ${durationMs: numberdurationMs.Number.toFixed(fractionDigits?: number): stringReturns a string representing a number in fixed-point notation.toFixed(1)}ms ${sql: stringsql}`)
: var undefinedundefined;
return withDatabase<Response>(databases: AnyDatabase | readonly AnyDatabase[], fn: () => Response | Promise<Response>): Promise<Response>Runs `fn` with `databases` as the request's own: queries started from a Model inside it (and
everything it awaits) use the one on that Model's binding, with its Session and `onQuery`.
Usually called once per request, in middleware. Nested calls add to the outer ones.
Each call is a scope of its own, even with a Database another request shares. An adapter may
hold a connection for the scope (the PostgreSQL adapter does, from a connection string). A nested call with
the same Database shares the outer call's scope while that call is running. When `fn` settles,
the scope ends, and the adapter lets its connection go once the queries still running on it
finish. Work that outlives the scope, such as a `waitUntil` save, gets a connection of its own.withDatabase(function connect(binding: D1Database, options?: ConnectOptions): Databaseconnect(env: Envenv.Env.DB: D1DatabaseDB, { ConnectOptions.onQuery?: QueryListener | undefinedCalled once for every statement sent to D1, with D1's `meta`.onQuery }), () => const app: {
fetch(request: Request<unknown, IncomingRequestCfProperties<unknown>>): Promise<Response>;
}
app.function fetch(request: Request<unknown, IncomingRequestCfProperties<unknown>>): Promise<Response>fetch(request: Request<unknown, IncomingRequestCfProperties<unknown>>request));
},
} satisfies interface ExportedHandler<Env = unknown, QueueHandlerMessage = unknown, CfHostMetadata = unknown, Props = unknown>ExportedHandler<Env>;The app-wide listener reads the variable from cloudflare:workers when a query runs:
import { class ModelThe library's base class: an app's base class extends it, and
methods, statics, callbacks and scopes declared there are shared by every Model built on it.
It has no table, so it's never used as a Model itself.Model, type type QueryListener<Meta = unknown> = (event: QueryEvent<Meta>) => voidHears each statement's `QueryEvent`. Declared as a method's type, so a listener typed for one
adapter's `meta` (a D1 app's base class) can be a Model's `static onQuery`, which any adapter calls.QueryListener } from "@forestfuture/active-record";
import { const env: Cloudflare.Envenv } from "cloudflare:workers";
import { const schema: {
readonly adapter: SchemaAdapter;
readonly tables: {
readonly users: {
readonly attributes: {
readonly id: {
readonly type: "string";
readonly null: false;
readonly generateId: true;
};
readonly email: {
readonly type: "string";
readonly null: false;
};
readonly iban: "string";
readonly dateOfBirth: "string";
};
readonly primaryKey: "id";
};
};
readonly models: {
readonly User: "users";
};
}
The database's adapter and binding, its tables (with their primary keys), and the Models built on them.schema } from "./db/schema";
// src/models/application-record.ts: logs only when LOG_SQL is set (in .dev.vars), read when a query runs.
export abstract class class ApplicationRecordApplicationRecord extends class ModelThe library's base class: an app's base class extends it, and
methods, statics, callbacks and scopes declared there are shared by every Model built on it.
It has no table, so it's never used as a Model itself.Model {
static override ApplicationRecord.schema: {
readonly adapter: SchemaAdapter;
readonly tables: {
readonly users: {
readonly attributes: {
readonly id: {
readonly type: "string";
readonly null: false;
readonly generateId: true;
};
readonly email: {
readonly type: "string";
readonly null: false;
};
readonly iban: "string";
readonly dateOfBirth: "string";
};
readonly primaryKey: "id";
};
};
readonly models: {
readonly User: "users";
};
}
The generated schema, on an app's base class (`static override schema = schema`): the
Models built on it have its tables' attributes, and query its binding.schema = const schema: {
readonly adapter: SchemaAdapter;
readonly tables: {
readonly users: {
readonly attributes: {
readonly id: {
readonly type: "string";
readonly null: false;
readonly generateId: true;
};
readonly email: {
readonly type: "string";
readonly null: false;
};
readonly iban: "string";
readonly dateOfBirth: "string";
};
readonly primaryKey: "id";
};
};
readonly models: {
readonly User: "users";
};
}
The database's adapter and binding, its tables (with their primary keys), and the Models built on them.schema;
static override ApplicationRecord.onQuery: QueryListenerAn app-wide query listener, as `connect(env.DB, { onQuery })` is a database's: called for
every statement of this Model (and those extending it), whichever database runs it, after
the database's own. Holds no request state, so it's safe on a class; a request's ID comes
from a database opened for it with `withDatabase` (#78).onQuery: type QueryListener<Meta = unknown> = (event: QueryEvent<Meta>) => voidHears each statement's `QueryEvent`. Declared as a method's type, so a listener typed for one
adapter's `meta` (a D1 app's base class) can be a Model's `static onQuery`, which any adapter calls.QueryListener = ({ model: stringThe Model the statement is for: its class name (`"Product"`). It's `""` for an anonymous
class, and a bundler that renames classes changes it; Wrangler keeps names by default.model, sql: stringsql, durationMs: numberdurationMs }) => {
if ((const env: Cloudflare.Envenv as { LOG_SQL?: string | undefinedLOG_SQL?: string }).LOG_SQL?: string | undefinedLOG_SQL) {
var console: Consoleconsole.Console.log(...data: any[]): void (+1 overload)The **`console.log()`** static method outputs a message to the console.
[MDN Reference](https://developer.mozilla.org/docs/Web/API/console/log_static)log(`${model: stringThe Model the statement is for: its class name (`"Product"`). It's `""` for an anonymous
class, and a bundler that renames classes changes it; Wrangler keeps names by default.model} ${durationMs: numberdurationMs.Number.toFixed(fractionDigits?: number): stringReturns a string representing a number in fixed-point notation.toFixed(1)}ms ${sql: stringsql}`);
}
};
}Timing queries in the browser
To see a request’s database time in the browser’s developer tools, add it up, and send it as a Server-Timing header:
import { function withDatabase<R>(databases: AnyDatabase | readonly AnyDatabase[], fn: () => R | Promise<R>): Promise<R>Runs `fn` with `databases` as the request's own: queries started from a Model inside it (and
everything it awaits) use the one on that Model's binding, with its Session and `onQuery`.
Usually called once per request, in middleware. Nested calls add to the outer ones.
Each call is a scope of its own, even with a Database another request shares. An adapter may
hold a connection for the scope (the PostgreSQL adapter does, from a connection string). A nested call with
the same Database shares the outer call's scope while that call is running. When `fn` settles,
the scope ends, and the adapter lets its connection go once the queries still running on it
finish. Work that outlives the scope, such as a `waitUntil` save, gets a connection of its own.withDatabase } from "@forestfuture/active-record";
import { function connect(binding: D1Database, options?: ConnectOptions): Databaseconnect } from "@forestfuture/active-record/d1";
import { const app: {
fetch(request: Request<unknown, IncomingRequestCfProperties<unknown>>): Promise<Response>;
}
app } from "./app";
// src/worker.ts: the request's database time, under its Timing in the browser's developer tools.
export const const timed: {
fetch(request: Request<unknown, IncomingRequestCfProperties<unknown>>, env: Env): Promise<Response>;
}
timed = {
async ExportedHandler<Env, unknown, unknown, unknown>.fetch?: ExportedHandlerFetchHandler<Env, unknown, unknown> | undefinedfetch(request: Request<unknown, IncomingRequestCfProperties<unknown>>request, env: Envenv) {
let let queries: numberqueries = 0;
let let total: numbertotal = 0;
const const db: Databasedb = function connect(binding: D1Database, options?: ConnectOptions): Databaseconnect(env: Envenv.Env.DB: D1DatabaseDB, {
ConnectOptions.onQuery?: QueryListener | undefinedCalled once for every statement sent to D1, with D1's `meta`.onQuery({ durationMs: numberdurationMs }) {
let queries: numberqueries += 1;
let total: numbertotal += durationMs: numberdurationMs;
},
});
const const response: Responseresponse = await withDatabase<Response>(databases: AnyDatabase | readonly AnyDatabase[], fn: () => Response | Promise<Response>): Promise<Response>Runs `fn` with `databases` as the request's own: queries started from a Model inside it (and
everything it awaits) use the one on that Model's binding, with its Session and `onQuery`.
Usually called once per request, in middleware. Nested calls add to the outer ones.
Each call is a scope of its own, even with a Database another request shares. An adapter may
hold a connection for the scope (the PostgreSQL adapter does, from a connection string). A nested call with
the same Database shares the outer call's scope while that call is running. When `fn` settles,
the scope ends, and the adapter lets its connection go once the queries still running on it
finish. Work that outlives the scope, such as a `waitUntil` save, gets a connection of its own.withDatabase(const db: Databasedb, () => const app: {
fetch(request: Request<unknown, IncomingRequestCfProperties<unknown>>): Promise<Response>;
}
app.function fetch(request: Request<unknown, IncomingRequestCfProperties<unknown>>): Promise<Response>fetch(request: Request<unknown, IncomingRequestCfProperties<unknown>>request));
const response: Responseresponse.Response.headers: HeadersThe **`headers`** read-only property of the Response interface contains the Headers object associated with the response.
[MDN Reference](https://developer.mozilla.org/docs/Web/API/Response/headers)headers.Headers.append(name: string, value: string): voidThe **`append()`** method of the Headers interface appends a new value onto an existing header inside a Headers object, or adds the header if it does not already exist.
[MDN Reference](https://developer.mozilla.org/docs/Web/API/Headers/append)append(
"server-timing",
`db;dur=${let total: numbertotal.Number.toFixed(fractionDigits?: number): stringReturns a string representing a number in fixed-point notation.toFixed(1)};desc="${let queries: numberqueries} queries"`,
);
return const response: Responseresponse;
},
} satisfies interface ExportedHandler<Env = unknown, QueueHandlerMessage = unknown, CfHostMetadata = unknown, Props = unknown>ExportedHandler<Env>;Keeping secrets out of the logs
Listeners see the values of passwords, tokens, keys, and emails as "[FILTERED]", while the database still gets the real values. Serialization lists the attributes filtered by default, and everywhere their values are hidden.
Filtering more attributes
Name them on your app’s base class, spreading in the defaults, as ApplicationRecord does with iban and dateOfBirth.
A string matches any attribute whose snake_case name contains it, so "iban" also covers ibanNumber. A string can be in camelCase or snake_case: "ibanNumber" and "iban_number" both match ibanNumber. Use a RegExp to match one name exactly.
Seeing a filtered attribute
To see one while debugging, leave it out of the list in development:
import { Model } from "@forestfuture/active-record";
import { schema } from "../db/schema";
export abstract class ApplicationRecord extends Model {
static override schema = schema;
static override filterAttributes = Model.filterAttributes.filter((entry) => entry !== "email");
}
Filtering sql fragments
A bare value inside an sql fragment has no attribute, so it’s logged as given. Write a secret as column("token").value(token), or compare it with a condition such as where({ token }), and it’s filtered. Otherwise, leave params out of what you log.