saropa_drift_viewer 0.2.1

Debug-only HTTP server that exposes SQLite/Drift table data as JSON and a minimal web viewer. Use from any Drift (or raw SQLite) app via an injectable query callback.

saropa_drift_viewer

Debug-only HTTP server that exposes SQLite/Drift table data as JSON and a minimal web UI. Use from any Flutter/Dart app that has a Drift (or other SQLite) database.

---

Features

• Table list with row counts; click a table to view rows as JSON
• Pagination (limit/offset) and client-side filter
• Collapsible schema panel; export table as CSV
• Light/dark theme (saved in localStorage)
• Read-only SQL runner with table/column autofill, templates, and query history (localStorage)
• Export schema-only (schema.sql), full dump (schema + data), or raw SQLite file (when getDatabaseBytes is set)
• Live refresh via long-poll when data changes
• Snapshot / time travel — in-memory snapshot, compare to now, export diff
• Database diff — compare to another DB (e.g. staging) when queryCompare is set; schema + row count diff, export report
• Optional auth — token or HTTP Basic for secure dev tunnels
• Bind address (loopback or any), CORS, health endpoint (GET /api/health), and DriftDebugServer.stop()

Editor integration: Run Task → Open Drift Viewer (VS Code/Cursor) or use the Drift Viewer extension in extension/.

Flutter overlay: In debug builds, wrap your app with DriftViewerOverlay to show a floating button that opens the viewer in the browser or in an in-app WebView. See Flutter overlay below.

---

Quick start

1. Add the dependency

From pub.dev:

# pubspec.yaml
dependencies:
  saropa_drift_viewer: ^0.1.0

Path dependency (local or monorepo):

dependencies:
  saropa_drift_viewer:
    path: ../path/to/saropa_drift_viewer

Run flutter pub get or dart pub get.

2. Start the viewer

Drift (one line):

import 'package:saropa_drift_viewer/saropa_drift_viewer.dart';

await myDb.startDriftViewer(enabled: kDebugMode);

This package does not depend on drift; it uses runtime wiring (customSelect(sql).get()). For compile-time type safety, use the callback API below.

Callback API (Drift or raw SQLite):

import 'package:saropa_drift_viewer/saropa_drift_viewer.dart';

await DriftDebugServer.start(
  query: (String sql) async {
    final rows = await myDb.customSelect(sql).get();
    return rows.map((r) => Map<String, dynamic>.from(r.data)).toList();
  },
  enabled: kDebugMode,
);

3. Open in a browser

Open http://127.0.0.1:8642.
From VS Code/Cursor: Run Task → Open Drift Viewer, or use the Drift Viewer extension (extension/) for a command-palette shortcut.

Example app: example/ — from repo root: flutter run -d windows, then open http://127.0.0.1:8642. See example/README.md.

4. Flutter overlay (optional)

In Flutter apps, add a floating button in debug builds that opens the viewer in the browser or in an in-app WebView:

import 'package:saropa_drift_viewer/flutter.dart';

void main() {
  runApp(DriftViewerOverlay(
    child: MaterialApp(home: MyHomePage()),
  ));
}

Start the server as usual (e.g. await myDb.startDriftViewer(enabled: kDebugMode);). The overlay shows a small button (e.g. bottom-right); tap it for a menu: Open in browser or Open in WebView. The button is only visible when kDebugMode is true and the server is running. For custom layout, use DriftViewerFloatingButton inside your own Stack.

---

API summary

API	Use when
db.startDriftViewer(enabled: ...)	Drift app; one-line setup (runtime wiring).
DriftDebugServer.start(query: ..., enabled: ...)	Drift or raw SQLite; you supply the query callback.

Common parameters

Parameter	Description
enabled	Typically kDebugMode. If false, server is not started.
port	Default 8642.
loopbackOnly	Bind to loopback only (default false).
corsOrigin	CORS header: '*', specific origin, or null to disable.
authToken	Optional; requests require Bearer token or ?token=. Use for tunnels.
basicAuthUser / basicAuthPassword	Optional; HTTP Basic auth when both set.
getDatabaseBytes	Optional; when set, GET /api/database serves raw SQLite file for download.
queryCompare	Optional; enables database diff vs another DB (e.g. staging).
onLog, onError	Optional; for your logger or debugPrint / print.

• Only one server per process; calling start again when running is a no-op. Use DriftDebugServer.stop() to shut down and restart (e.g. tests or graceful shutdown).
• Health: GET /api/health → {"ok": true}.
• Live refresh: GET /api/generation; use ?since=N to long-poll until generation changes (30s timeout).

---

Security

Debug only. Do not enable in production.

• Default bind: 0.0.0.0; use loopbackOnly: true to bind to 127.0.0.1 only.
• Read-only: table listing and table data; SQL runner accepts read-only SQL (SELECT / WITH ... SELECT only); writes and DDL are rejected. Table/column endpoints use allow-lists; table names and limit/offset are validated.

Secure dev tunnel (ngrok, port forwarding): use authToken or basicAuthUser / basicAuthPassword:

await DriftDebugServer.start(
  query: runQuery,
  enabled: kDebugMode,
  authToken: 'your-secret-token',  // open https://your-tunnel.example/?token=your-secret-token
  // or: basicAuthUser: 'dev', basicAuthPassword: 'pass',
);

With token auth, open https://your-tunnel.example/?token=your-secret-token; the page uses the token for all API calls. You can also send Authorization: Bearer your-secret-token.

---

Publishing

From repo root:

python scripts/publish_pub_dev.py

Manual: Bump version in pubspec.yaml, then git tag v0.1.0 and git push origin v0.1.0. GitHub Actions publishes to pub.dev.

• Package on pub.dev