> ## Documentation Index
> Fetch the complete documentation index at: https://docs.monocle.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Drizzle ORM

> Trace database queries made through Drizzle ORM

This guide shows how to instrument Drizzle for query monitoring. You will learn how to:

* Wrap your Drizzle database or underlying client
* Configure which query details are recorded

## Overview

`@monocle.sh/instrumentation-drizzle` creates OpenTelemetry spans for Drizzle queries. Initialize your OpenTelemetry SDK or agent before creating the database, then wrap the Drizzle instance with `instrumentDrizzleClient()`. The instrumentation is opt-in and is not enabled automatically by the Monocle agent.

## Installation

The package requires Drizzle ORM `0.28.0` or later. Install your database driver separately. This example uses `pg`.

```bash title="Terminal" theme={"theme":"vesper"}
npm install @monocle.sh/instrumentation-drizzle drizzle-orm pg
```

## Instrument your Drizzle database

Wrap the instance returned by `drizzle()` before using it. Set `dbSystem` so Monocle can identify the database in query details.

```typescript title="app/services/database.ts" theme={"theme":"vesper"}
import { drizzle } from "drizzle-orm/node-postgres";
import { instrumentDrizzleClient } from "@monocle.sh/instrumentation-drizzle";
import { Pool } from "pg";

const pool = new Pool({ connectionString: process.env.DATABASE_URL });

export const db = instrumentDrizzleClient(drizzle(pool), {
  dbSystem: "postgresql",
  dbName: "app",
});
```

Queries and prepared queries create database spans. Queries run inside a transaction are marked with `db.transaction`, and query errors are recorded on their spans.

If you want to instrument the underlying client directly, use `instrumentDrizzle()` before passing the client to Drizzle:

```typescript title="app/services/database.ts" theme={"theme":"vesper"}
import { drizzle } from "drizzle-orm/node-postgres";
import {
  instrumentDrizzle,
  type InstrumentDrizzleConfig,
} from "@monocle.sh/instrumentation-drizzle";
import { Pool } from "pg";

const config: InstrumentDrizzleConfig = { dbSystem: "postgresql" };
const pool = instrumentDrizzle(new Pool({ connectionString: process.env.DATABASE_URL }), config);

export const db = drizzle(pool);
```

Choose one entry point for a database. Wrapping both the Drizzle instance and its underlying client can create duplicate spans for a query.

## Configure query details

Pass these options to either instrumentation function:

* `dbSystem` identifies the database, for example `postgresql`, `mysql`, or `sqlite`. It defaults to `unknown`.
* `dbName`, `peerName`, and `peerPort` add database name and connection details to spans.
* `captureQueryText` includes SQL statements in spans by default. Set it to `false` to omit SQL text.
* `maxQueryTextLength` sets the maximum SQL statement length. It defaults to 1,000 characters.

The instrumentation creates `CLIENT` spans with database attributes such as the operation and table name when they can be read from the SQL statement. Transaction queries are marked with `db.transaction`.