OrmConnection class

Represents a fully materialized ORM connection that exposes helpers, metadata, and instrumentation hooks.

Observability

OrmConnection provides a unified observability system inspired by Laravel's Connection class. The primary method for observing database operations is listen, which receives QueryExecuted events after every query.

// Register a query listener (like Laravel's listen)
connection.listen((event) {
  print('Query: ${event.sql} took ${event.time}ms');
});

// Listen for specific event types
connection.onEvent<TransactionBeginning>((event) {
  print('Transaction started');
});

connection.onEvent<TransactionCommitted>((event) {
  print('Transaction committed');
});

Query Logging

Built-in query logging accumulates QueryLogEntry objects for debugging:

connection.enableQueryLog();

// ... execute queries ...

for (final entry in connection.queryLog) {
  print('${entry.sql} (${entry.duration.inMilliseconds}ms)');
}

connection.flushQueryLog(); // Clear entries

Duration Handlers

Monitor cumulative query time with whenQueryingForLongerThan:

connection.whenQueryingForLongerThan(
  Duration(seconds: 2),
  (connection, event) {
    logger.warning('Slow queries detected: ${connection.totalQueryDuration}ms total');
  },
);