ispectify_db adds passive database observability to the ISpect toolkit. It traces SQL statements, ORM operations, and KV-store calls through a single dbTrace extension with timing, row counts, slow-query detection, and redaction.

• Works with any driver. sqflite, drift, Isar, ObjectBox, shared_preferences, hive, and the rest. Wrap the call and the tracing is automatic.
• Argument redaction by configured keys.
• A slow-query threshold emits a separate log entry so perf outliers stand out.
• Optional stack trace capture on errors, paid for only when an error happens.
• Pure Dart. No Flutter binding required.

Install

dependencies:
  ispectify: ^5.0.0-dev58
  ispectify_db: ^5.0.0-dev58

Quick start

Configure once at startup:

import 'package:ispectify_db/ispectify_db.dart';

ISpectDbCore.config = const ISpectDbConfig(
  sampleRate: 1.0,
  redact: true,
  attachStackOnError: true,
  slowThreshold: Duration(milliseconds: 400),
);

Then wrap each storage call with dbTrace:

import 'package:sqflite/sqflite.dart';

final rows = await ISpect.logger.dbTrace<List<Map<String, Object?>>>(
  source: 'sqflite',
  operation: 'query',
  statement: 'SELECT * FROM users WHERE id = ?',
  args: [userId],
  table: 'users',
  run: () => db.rawQuery('SELECT * FROM users WHERE id = ?', [userId]),
  projectResult: (rows) => {'rows': rows.length},
);

source and operation become the grouping key in the log viewer. projectResult lets you record "just the counts" instead of dumping row contents.

Configuration

Field	Default	What it does
sampleRate	1.0	Fraction of calls to log. 0.1 keeps 10% of them.
redact	true	Mask sensitive keys in args and statement.
redactKeys	built-in set	Override the redaction key list.
attachStackOnError	true	Capture and log a stack trace on failure.
slowThreshold	null	Re-emit durations above the threshold as a db-slow-query entry. (Renamed from slowQueryThreshold in 5.0.)

ISpectDbCore.config = const ISpectDbConfig(
  redact: true,
  redactKeys: ['password', 'token', 'secret'],
  slowThreshold: Duration(milliseconds: 250),
);

The ISpect toolkit

ISpect is a modular monorepo. Pick the packages your project needs. Each one works on its own.

Package	What it does
ispect	Flutter UI: debug panel, log viewer, navigation observer, inspector integration.
ispect_layout	Visual layout inspector with sizes, constraints, decorations, compare mode, and a color picker.
ispectify	Pure-Dart logging core: typed log entries, filtering, tracing, observers.
ispectify_dio	Dio HTTP interceptor with automatic redaction.
ispectify_http	http package interceptor with automatic redaction.
ispectify_ws	WebSocket traffic capture with automatic redaction.
ispectify_db	Database operation tracing for SQL, ORMs, and KV stores.
ispectify_bloc	BLoC event, state, transition, and error observer.

Contributing

Contributions are welcome. See CONTRIBUTING.md for guidelines, and open issues or pull requests at the ISpect repository.

License

MIT. See LICENSE.

---