Logging & Monitoring

UQL logs generated queries, per-query execution times, slow-query alerts, and migration activity.

Configuration

Logging is set per pool, usually in uql.config.ts. logger: true turns on every level through the built-in DefaultLogger:

import { PgQuerierPool } from 'uql-orm/postgres';

export const pool = new PgQuerierPool(
  {/* connection options */},
  {
    // Enable all log levels with colored output
    logger: true,
    // Threshold in ms to log slow queries
    slowQuery: 200,
  },
);

Advanced Configuration

An array enables levels selectively:

import type { ExtraOptions } from 'uql-orm';

const options: ExtraOptions = {
  // Only log errors and warnings at the regular query level
  logger: ['error', 'warn'],
  // Independent of `logger`'s levels: any query at or past 200ms is logged as slow regardless
  slowQuery: 200,
};

slowQuery doesn’t need a matching entry in logger’s level array - setting the threshold is what turns slow-query alerts on, on top of whatever regular levels you’ve enabled.

For production, a common pattern is to go silent except for problems:

const options: ExtraOptions = {
  // No regular query/info logging at all
  logger: ['error', 'warn', 'migration'],
  // ...but still alert on anything past a second
  slowQuery: 1000,
};

Including Bound Values in Logs

Bound values are never logged by default - logValues defaults to false, so logs carry SQL text only, since query parameters may hold PII or other sensitive data. Opt in explicitly if you want them (e.g. in a local/dev environment):

const options: ExtraOptions = {
  logger: true,
  slowQuery: 500,
  logValues: true,
};

logValues applies uniformly to regular query logs and slow-query alerts alike; it isn’t tied to slowQuery specifically.

Log Levels

Level	Description
query	Each executed SQL statement/command, with its parameters and execution time.
error / warn	Error traces and warnings.
migration	Step-by-step history of schema changes.
skippedMigration	Unsafe schema changes blocked during sync.
schema / info	ORM initialization and sync events.

Output Format

The DefaultLogger writes colored output like this:

query: SELECT * FROM "user" WHERE "id" = $1 -- [123] [2ms]
slow query: UPDATE "post" SET "title" = $1 -- ["New Title"] [1250ms]
error: Failed to connect to database: Connection timeout
skipped migration: Cannot drop column "old_field" in safe mode

Custom Logger

logger also takes a function, for the query level alone:

{
  logger: (query, values, duration) => {
    console.log(`Executing ${query} with ${values}. Took ${duration}ms`);
  };
}

Or a class implementing Logger, whose methods - logQuery, logSlowQuery, logWarn, logError, logInfo, logSchema, logMigration, logSkippedMigration - are called independently, so slow queries can go somewhere regular ones do not:

import type { Logger } from 'uql-orm';

class MyLogger implements Logger {
  logQuery(query: string, values?: unknown[], duration?: number) {
    console.log(`query: ${query}`, values, duration);
  }
  logSlowQuery(query: string, values?: unknown[], duration?: number) {
    pagerduty.alert(`Slow query (${duration}ms): ${query}`);
  }
}

const options: ExtraOptions = { logger: new MyLogger(), slowQuery: 500 };

To keep DefaultLogger’s console output and only add alerting, extend it and override the one method:

import { DefaultLogger } from 'uql-orm';

class AlertingLogger extends DefaultLogger {
  override logSlowQuery(query: string, values?: unknown[], duration?: number) {
    super.logSlowQuery(query, values, duration); // still print to console
    pagerduty.alert(`Slow query (${duration}ms): ${query}`);
  }
}