Saropa Drift Advisor — VS Code Extension

Full IDE integration for saropa_drift_advisor, the debug-only SQLite/Drift database inspector for Flutter and Dart apps.

Requirements

Your Flutter/Dart app must be running with the Drift debug server started. See the Dart package README for setup (two lines of code).

Features

Database Explorer

A database icon in the activity bar opens a tree view:

• Tables with row counts
• Columns with type icons (key, number, string, blob)
• Foreign key relationships
• Right-click: View Data, Copy Name, Export CSV, Watch Table
• Auto-refreshes when the app writes to the database
• Mutation Stream panel — real-time semantic INSERT/UPDATE/DELETE feed with schema column filtering and row navigation

Code Intelligence

Works in Dart files with Drift table definitions:

• Go to Definition (F12) — jump from SQL table/column names to their definitions; the same lookup is available from the Database tree (context menu Go to … Definition (Dart) opens the table or column getter when found)
• CodeLens — row counts and quick actions on Drift table classes
• Hover Preview — see recent rows when hovering over table class names
• Schema Linter — diagnostics with quick-fix code actions for missing indexes and anomalies
• File Badges — row count badges on Drift table files in the explorer

Query Tools

• SQL Notebook (Ctrl+Shift+Q) — multi-statement editor with autocomplete, results grid, and inline charts
• EXPLAIN Panel — color-coded query plan tree with index suggestions
• Live Watch — monitor queries with diff highlighting; persists across sessions

Schema & Migration

• Scan Dart schema definitions — Command Palette: lists tables, columns, indexes, and uniqueKeys from Dart sources only; no connected server required (Output → Drift Dart schema)
• Schema Diff — compare code-defined tables vs runtime schema
• Schema Diagram — ER-style visualization of tables and FK relationships
• Generate Dart — scaffold Drift table classes from the runtime schema
• Isar-to-Drift Generator — scan workspace or pick files to convert Isar @collection classes (Dart source or JSON schema) to Drift table definitions with configurable embedded/enum strategies
• Migration Preview — preview migration DDL from database comparison

Data Management

• Import Data — 3-step wizard for JSON, CSV, or SQL files
• Data Editing — track cell edits, row inserts/deletes; generate SQL from pending changes
• Export SQL Dump — full schema + data to .sql
• Download Database — save the raw .db file

Debugging

• Query Performance — debug sidebar with slow query stats and timing
• Snapshot Timeline — capture snapshots, compare to current state, view diffs
• Database Comparison — diff two databases (schema match, row count differences)
• Size Analytics — storage dashboard with table sizes, indexes, journal mode
• Terminal Links — clickable SQLite error messages
• Pre-launch Tasks — health check, anomaly scan, index coverage

Sessions

• Share Session — snapshot state, copy shareable URL
• Open Session — view a shared session by ID
• Annotate Session — add notes to shared sessions

Configuration

Design: extension enablement

Drift Advisor has a master switch: driftViewer.enabled (default true). When false, the extension does not discover or connect to servers and all Drift Advisor features are off; the Database view shows “Saropa Drift Advisor is disabled” and the status bar shows “Drift: Disabled”. When true, activation is as before (onLanguage:dart). About, About Saropa, and Save Current Filter use onCommand activation so they work from the Database view or Command Palette even before a Dart file is opened; individual features can still be turned off via other settings. Use Add package to project to add the Dart package to your app so the extension and package stay in sync.

Server Discovery

The extension automatically scans ports 8642-8649 for running debug servers. When no server is found and a Flutter/Dart debug session is active (e.g. app on Android emulator), it tries to forward the port with adb forward and retries discovery so the host can connect. You can also run Saropa Drift Advisor: Forward Port (Android Emulator) manually. When multiple servers are found, use Saropa Drift Advisor: Select Server from the command palette.

Troubleshooting: Use Show Connection Log (Output → Saropa Drift Advisor), Diagnose Connection (writes a snapshot and optional clipboard copy), or Refresh Connection UI if the sidebar looks wrong while the app is running. If you see a connection but the Database tree stays empty (REST schema error), use the named action rows under DATABASE — they run the same commands as the welcome text but via native tree clicks, which is more reliable than welcome links in some editors.

The status bar shows connection state:

• Drift: :8642 — connected to a single server
• Drift: 3 servers — multiple servers found (click to select)
• Drift: Searching... — scanning for servers
• Drift: Offline — no servers found (click to retry)

Commands

All commands are available via the command palette (Ctrl+Shift+P):

Development

cd extension && npm install && npm run compile

Run/debug: Run > Run Extension (F5) in VS Code.

cd extension && npm test