@stacknext/drizzle 0.8.0 → 0.10.0

package/docs/configuration.md

@@ -0,0 +1,70 @@
+---
+title: Configuration
+description: Configure the Drizzle adapter, transport and database settings.
+---
+
+# Configuration
+
+## Adapter options
+
+```ts
+import { createStackNextDrizzleLogger } from '@stacknext/drizzle'
+
+const logger = createStackNextDrizzleLogger({
+  databaseSystem: 'postgresql',
+})
+```
+
+| Option | Required | Default | Notes |
+| --- | --- | --- | --- |
+| `databaseSystem` | No | `'sql'` | Use the engine name, for example `sqlite`, `postgresql` or `mysql`. |
+| `transport` | No | Process-wide transport | Must expose `enqueueDatabaseQuery`. |
+| `onError` | No | none | Receives telemetry failures; they never reach Drizzle. |
+
+## Connect the logger
+
+```ts
+import { drizzle } from 'drizzle-orm/better-sqlite3'
+import { createStackNextDrizzleLogger } from '@stacknext/drizzle'
+
+export const db = drizzle(client, {
+  logger: createStackNextDrizzleLogger({ databaseSystem: 'sqlite' }),
+})
+```
+
+The logger is registered when the Drizzle client is created. There is no
+automatic global registration and no monkey-patching.
+
+## `stacknext.config.json`
+
+```json
+{
+  "database": { "drizzle": true, "prisma": false }
+}
+```
+
+`database.drizzle` is setup intent used by `stacknext init` and
+`stacknext doctor`. Setting it does **not** attach the logger. The adapter must
+be passed to `drizzle(...)` explicitly.
+
+## Environment
+
+The adapter uses the active transport. `stacknext dev` exports
+`STACKNEXT_COLLECTOR_URL` and `STACKNEXT_TOKEN`; outside that environment the
+global transport is absent and the logger is inert.
+
+Optional adapter overrides for tests are passed through `options.transport`, not
+environment variables.
+
+## Captured fields
+
+See [the package overview](index.md#what-is-recorded). There is no option to
+enable bind-parameter capture, SQL parameter logging or query bodies.
+
+## Verify
+
+1. Start `stacknext dev` and make a request that queries the database.
+2. Run `stacknext coverage`; the database category should show observed
+   evidence.
+3. Open the dashboard Database page or call `list_database_queries` through MCP.
+4. Confirm durations are `null` and marked unmeasured. That is expected.

package/docs/index.md

@@ -0,0 +1,94 @@
+---
+title: "@stacknext/drizzle"
+description: Drizzle ORM query logging adapter for StackNext, without bind-parameter capture.
+---
+
+# @stacknext/drizzle
+
+`@stacknext/drizzle` is a Drizzle `Logger` adapter. It sends redacted SQL events
+to the active StackNext transport so queries appear in request timelines and
+diagnostics.
+
+## Who should read this
+
+Applications using Drizzle. This is a **public, optional integration package**.
+It is not required unless the project uses Drizzle.
+
+## Installation
+
+```bash
+pnpm add @stacknext/drizzle
+```
+
+`drizzle-orm >=0.30.0` is an optional peer dependency. The adapter does not
+import Drizzle at runtime; it accepts any object matching
+`{ logQuery(query, params) }`.
+
+## Usage
+
+```ts
+import { drizzle } from 'drizzle-orm/better-sqlite3'
+import { createStackNextDrizzleLogger } from '@stacknext/drizzle'
+
+export const db = drizzle(client, {
+  logger: createStackNextDrizzleLogger({ databaseSystem: 'sqlite' }),
+})
+```
+
+## API
+
+### `createStackNextDrizzleLogger(options?)`
+
+Returns a `DrizzleLoggerLike` with `logQuery(query, params)`.
+
+`StackNextDrizzleLoggerOptions`:
+
+| Option | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `databaseSystem` | string | `'sql'` | Value reported as `db.system.name`. |
+| `transport` | `Pick<StackNextTransport, 'enqueueDatabaseQuery'>` | global transport | Override for tests or custom setups. |
+| `onError` | `(error: unknown) => void` | none | Called when the telemetry sink throws. |
+
+<!-- coderabbit-ai-generated:v1 -->
+
+<!-- coderabbit-ai-generated-section:v1:92e6ad51fd00b5bd40b76d93991b902366deea6ad1bb299cee86b066438eac33 -->
+
+Telemetry failures are caught, but a throwing `onError` callback can propagate
+its error to Drizzle. Callers must ensure `onError` does not throw. If no transport is active, the
+logger is a no-op.
+
+<!-- /coderabbit-ai-generated:v1 -->
+
+## What is recorded
+
+- redacted SQL text (capped at 20,000 characters);
+- inferred operation (`select`, `insert`, `update`, `delete`, `with`, and so
+  on);
+- active trace/span ids when a valid OTel context exists;
+- `databaseSystem`, `success: true`, `source: 'drizzle'`;
+- `db.query.parameter_count` (the count only);
+- `db.duration.measured: false`.
+
+## Duration is null
+
+Drizzle's `Logger` interface does not expose query duration. StackNext stores
+`durationMs: null` and marks it unmeasured. It is never converted to zero.
+
+Do not compare Drizzle durations with Prisma durations or rank them as if they
+were fast.
+
+## Privacy
+
+`params` is used only for `Array.isArray(params) ? params.length : 0`. The
+values are never read, logged or transmitted. SQL text passes through
+`redactSql`.
+
+## Documentation map
+
+- [Configuration](configuration.md)
+- [Troubleshooting](troubleshooting.md)
+
+## Related packages
+
+- `@stacknext/core` owns the transport and redaction.
+- `@stacknext/cli` runs the collector.

package/docs/troubleshooting.md

@@ -0,0 +1,48 @@
+---
+title: Troubleshooting
+description: Diagnose missing Drizzle queries, null durations and adapter registration problems.
+---
+
+# Troubleshooting
+
+## No Drizzle queries appear
+
+1. Confirm `createStackNextDrizzleLogger()` is passed to the same Drizzle client
+   that serves requests.
+2. Confirm the app is running under `stacknext dev`, which supplies the
+   transport environment.
+3. Make a request that actually executes a query.
+4. Run `stacknext coverage`; `database` evidence should become observed.
+5. Check `stacknext doctor` for adapter/config warnings.
+
+## Queries appear without a trace
+
+The adapter records trace/span ids only when a valid OpenTelemetry context is
+active. Queries from scripts, workers or background jobs may have no request
+root. They are still stored, but they are not attributed to a request.
+
+## Duration is null
+
+Expected. Drizzle's logger does not expose duration. StackNext stores `null` and
+sets `db.duration.measured: false`.
+
+Do not treat `null` as zero, and do not compare Drizzle and Prisma durations.
+
+## SQL is redacted or truncated
+
+SQL passes through `redactSql` and is capped at 20,000 characters. Bind
+parameters are not included, so a value passed as `?` or `$1` cannot leak.
+
+## The adapter throws?
+
+It should not. `logQuery` catches sink errors and forwards them to `onError` if
+provided. If an error escapes, check the Drizzle logger contract and the
+`enqueueDatabaseQuery` implementation supplied through `options.transport`.
+
+## Verify
+
+```bash
+stacknext status --json
+stacknext coverage --json
+stacknext diagnose --category database
+```

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@stacknext/drizzle",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "Drizzle ORM query logging adapter for StackNext",
   "license": "MIT",
   "type": "module",
   "files": [
-    "dist"
+    "dist",
+    "docs"
   ],
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -18,7 +19,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@stacknext/core": "0.8.0",
+    "@stacknext/core": "0.10.0",
     "@opentelemetry/api": "1.9.0"
   },
   "devDependencies": {