Skip to content
Active Record
Esc
↑↓navigate↵open⌘Jpreview
On this page

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: Headers
The **`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 | null
The **`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 | undefined
Called once for every statement sent to D1, with D1's `meta`.
onQuery
: ({ model: string
The 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: JSON
An 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.
@paramvalue A JavaScript value, usually an object or array, to be converted.@paramreplacer A function that transforms the results.@paramspace Adds indentation, white space, and line break characters to the return-value JSON text to make it easier to read.@throws{TypeError} If a circular reference or a BigInt value is found.
stringify
({
requestId: stringrequestId, model: stringmodel, ms: numberms: var Math: Math
An intrinsic object that provides basic mathematics functionality and constants.
Math
.Math.round(x: number): number
Returns a supplied numeric expression rounded to the nearest integer.
@paramx The value to be 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>) => void
Hears 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>) => void
Hears 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: string
The 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: string
The 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): string
Returns a string representing a number in fixed-point notation.
@paramfractionDigits Number of digits after the decimal point. Must be in the range 0 - 20, inclusive.
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 | undefined
Called 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 Model
The 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>) => void
Hears 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 Model
The 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: QueryListener
An 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>) => void
Hears 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: string
The 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: string
The 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): string
Returns a string representing a number in fixed-point notation.
@paramfractionDigits Number of digits after the decimal point. Must be in the range 0 - 20, inclusive.
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 | undefined
Called 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: Headers
The **`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): void
The **`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): string
Returns a string representing a number in fixed-point notation.
@paramfractionDigits Number of digits after the decimal point. Must be in the range 0 - 20, inclusive.
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.

Last updated on