knex-connections

name	knex-connections
description	Use when configuring connection pools, executing raw SQL, or tapping observability streams on knex_dart driver clients.
metadata	{"knex_dart_version":"1.2.1"}

This skill covers pool configuration, raw SQL execution, observability, and teardown. For basic driver setup and first queries, see knex-driver-setup.

Pool Configuration

Pass a PoolConfig to any connect(...) factory to tune the connection pool.

import 'package:knex_dart/knex_dart.dart';
import 'package:knex_dart_postgres/knex_dart_postgres.dart';

final db = await KnexPostgres.connect(
  host: 'db.example.com',
  port: 5432,
  database: 'myapp',
  username: 'app',
  password: 'secret',
  useSSL: true,
  poolConfig: const PoolConfig(
    min: 2,
    max: 10,
    acquireTimeoutMillis: 30000,
  ),
);

PoolConfig defaults: min: 2, max: 10, acquireTimeoutMillis: 60000.

Raw SQL Execution

db.rawSql(sql, [bindings]) is the canonical driver-wrapper API for executing a parameterized SQL string directly.

Some wrappers also keep legacy aliases such as raw() or executeRaw(). Prefer rawSql() in new code so examples transfer cleanly between drivers.

// No bindings
final rows = await db.rawSql('SELECT current_timestamp AS ts');

// Positional bindings
final users = await db.rawSql(
  'SELECT id, email FROM users WHERE created_at > \$1',
  [DateTime(2024).toIso8601String()],
);

For raw SQL fragments inside a query builder (not execution), use db.queryBuilder().client.raw(sql, bindings). Do not assume wrapper-level raw() always creates a fragment; on some wrappers it is a raw execution alias.

Observability

All driver wrappers accept an interceptors list. Attach a custom QueryInterceptor to observe every future-based query and every streaming query — its SQL, bindings, timing, and errors — without any dependency on a specific driver.

Override both intercept (future queries) and interceptStream (streaming queries) to cover all execution paths:

import 'package:knex_dart/knex_dart.dart';
import 'package:knex_dart_postgres/knex_dart_postgres.dart';

class LoggingInterceptor extends QueryInterceptor {
  @override
  Future<T> intercept<T>(
    QueryExecutionContext ctx,
    Future<T> Function() next,
  ) async {
    print('[SQL] ${ctx.querySummary}  bindings=${ctx.parameters}');
    final sw = Stopwatch()..start();
    try {
      final result = await next();
      print('[DONE] elapsed=${sw.elapsed}');
      return result;
    } catch (e) {
      print('[ERROR] ${ctx.querySummary} → $e');
      rethrow;
    }
  }

  @override
  Stream<T> interceptStream<T>(
    QueryExecutionContext ctx,
    Stream<T> Function() next,
  ) {
    print('[STREAM] ${ctx.querySummary}');
    final sw = Stopwatch()..start();
    return next().handleError((Object e) {
      print('[STREAM ERROR] ${ctx.querySummary} elapsed=${sw.elapsed} → $e');
      throw e;
    }).transform(
      StreamTransformer.fromHandlers(
        handleDone: (sink) {
          print('[STREAM DONE] ${ctx.querySummary} elapsed=${sw.elapsed}');
          sink.close();
        },
        handleData: (row, sink) => sink.add(row),
      ),
    );
  }
}

final db = await KnexPostgres.connect(
  host: 'localhost',
  database: 'myapp',
  username: 'user',
  password: 'pass',
  interceptors: [LoggingInterceptor()],
);

For structured telemetry (spans, metrics, trace context), use KnexOtelInterceptor from package:knex_dart_otel/knex_dart_otel.dart instead of a hand-rolled interceptor.

Teardown

// On KnexPostgres / KnexSQLite wrappers
await db.close();       // closes the pool
await db.destroy();     // alias for close()

// On PostgresClient / SQLiteClient directly
await client.close();

Always await teardown in main() or a finally block to drain the pool cleanly before process exit.

SSL and Special Dialects

// CockroachDB — port 26257, wire-compatible with PostgreSQL
final crdb = await KnexPostgres.cockroachdb(
  host: 'localhost',
  database: 'defaultdb',
  username: 'root',
  useSSL: false,
);

// Amazon Redshift — port 5439, no RETURNING / LATERAL support
final rs = await KnexPostgres.redshift(
  host: 'my-cluster.us-east-1.redshift.amazonaws.com',
  database: 'dev',
  username: 'awsuser',
  password: 'secret',
);

Docs

• Connections: https://docs.knex.mahawarkartikey.in/raw/connections/connections.md
• Streaming: https://docs.knex.mahawarkartikey.in/raw/connections/streaming.md
• OpenTelemetry: https://docs.knex.mahawarkartikey.in/raw/tooling/opentelemetry.md
• Quick start: https://docs.knex.mahawarkartikey.in/raw/getting-started/quick-start.md