saropa_drift_advisor library

Debug-only HTTP server that exposes SQLite/Drift table data as JSON and a minimal web viewer.

Architecture: The package is dependency-injection friendly: it does not depend on drift. You supply a DriftDebugQuery that runs SQL; the server uses it for table listing, table data, schema, and optional read-only SQL runner. One server per process; DriftDebugServer.stop clears state so DriftDebugServer.start can be called again (e.g. in tests).

Use from any Flutter or Dart app that has a SQLite (or Drift) database. Add the package (from pub.dev or a path dependency), then start the server with DriftDebugServer.start, passing a DriftDebugQuery callback that runs SQL and returns rows as maps.

Public API

See the package README for HTTP endpoints, UI features, and optional auth for dev tunnels.

Classes

DeclaredColumn
One column in a host-declared Drift schema (the schema as written in code, independent of the live SQLite file). Served by GET /api/schema/declared so the web viewer can show code-declared tables and (stretch) flag divergence from the runtime database.
DeclaredRelationship
One declared relationship edge: fromTable.fromColumn references toTable.toColumn. Descriptive only — the advisor reads it to know the link exists; it never enforces it (no PRAGMA foreign_keys, no constraint, no migration). This is how a host that links by convention (a shared UUID/_id column) instead of SQLite foreign keys makes its relationships visible to tooling, turning the web wizard's column-name heuristic into a fact.
DeclaredTable
One table in a host-declared Drift schema, with its columns and any declared index names. indexes may be empty when the host cannot supply them.
DriftDebugErrorLogger
Best-practice error and message logger for the Drift debug server.

Enums

DriftDebugErrorKind
Classifies errors the server reports via the error callback so host apps can route user-input mistakes differently from genuine server failures.

Mixins

DriftDebugServer
Debug-only HTTP server (stub when dart:io unavailable).

Extensions

StartDriftViewerExtension on Object
Convenience API for Drift apps: await myDb.startDriftViewer(...).

Typedefs

DeclaredRelationships = List<DeclaredRelationship>
The full host-declared relationship manifest: an ordered list of edges.
DeclaredRelationshipsCallback = DeclaredRelationships Function()
Host-supplied callback returning the relationship manifest. When null the GET /api/schema/relationships endpoint reports available: false and the metadata fold falls back to PRAGMA foreign_key_list (same opt-in posture as DeclaredSchemaCallback).
DeclaredSchema = List<DeclaredTable>
The full code-declared schema: an ordered list of tables.
DeclaredSchemaCallback = DeclaredSchema Function()
Host-supplied callback returning the code-declared Drift schema. When null the GET /api/schema/declared endpoint reports the feature as unavailable (same opt-in posture as declaredTableNames for the orphan check).
DriftDebugGetDatabaseBytes = Future<List<int>> Function()
Optional callback that returns the raw SQLite database file bytes.
DriftDebugLoggerCallbacks = ({_ErrorCallback error, _LogCallback log})
Type for the pair of log and error callbacks returned by DriftDebugErrorLogger.callbacks.
DriftDebugOnClassifiedError = void Function(Object error, StackTrace stack, DriftDebugErrorKind kind)
Like DriftDebugOnError but includes an error classification so the host can route user-input mistakes (warning log) differently from server bugs (halt / crash report). When both DriftDebugOnError and this callback are set, only this one fires.
DriftDebugOnError = void Function(Object error, StackTrace stack)
Optional callback for errors (and optional stack trace).
DriftDebugOnLog = void Function(String message)
Optional callback for log messages.
DriftDebugQuery = Future<List<Map<String, dynamic>>> Function(String sql)
Callback that runs a single SQL query and returns rows as list of maps.
DriftDebugQueryWithBindings = Future<List<Map<String, dynamic>>> Function(String sql, {Map<String, Object?>? namedArgs, List<Object?>? positionalArgs})
Optional read callback that receives declared positional/named bindings.
DriftDebugReportActivity = void Function(String message)
Shape of the host-statement reporting hook for the Heartbeat screen's live capture (Feature 80, phase 2). The host wires drift's logStatements output or a QueryInterceptor to DriftDebugServer.reportActivity (which matches this signature). Not wiring it is fine — the heartbeat screen then degrades gracefully to phase 1 signals (advisor traffic + detected row-count changes).
DriftDebugWriteQuery = Future<void> Function(String sql)
Optional callback for write queries (INSERT/UPDATE/DELETE). Debug-only: used exclusively by the import endpoint.
DriftDebugWriteQueryWithBindings = Future<void> Function(String sql, {Map<String, Object?>? namedArgs, List<Object?>? positionalArgs})
Optional write callback that receives declared positional/named bindings.