local_database_visual_debugger 0.0.1

A plug-and-play in-app database viewer and inspector for Flutter.

Local Database Visual Debugger

Open-source Postman for Local Flutter Databases.

A fully open-source Flutter developer tool to inspect, edit, export, import, and debug local databases directly inside the app during development.

🚀 Overview (The "Why")

When building Flutter apps with local databases, debugging requires writing custom UI screens, using fragile external tools, or pulling the raw DB files from the simulator/device.

Local Database Visual Debugger gives you a drop-in, on-device debugging UI. Simply wrap your app with our LocalDbViewer and get a beautiful interface to view tables, inspect rows, and modify data on the fly.

Launch fast. Improve later.

✨ Features

• 📊 Database Explorer: Display all tables with metadata and record counts.
• 🔍 Record Viewer: Browse records with pagination, filtering, search, and sorting.
• ✍️ Live Record Editor: Insert, update, and delete records directly inside the debug panel.
• 🪟 Floating Debugger Button: Instantly open the debugger UI via a draggable FAB.
• ⏱️ Time-Travel Snapshots: Instantly backup and restore database dumps to test varying states quickly.
• 🔐 QA/Dev PIN Lock: Restrict database access behind a clean 4-digit PIN lock screen so QA teams don't accidentally wipe data.
• 🖥️ Raw SQL Runner: Direct built-in terminal for running custom query executions against relational adapters.

📦 Supported Databases

• SQLite (SqliteAdapter)
• SharedPreferences (SharedPreferencesAdapter)
• Hive (HiveAdapter)
• Isar (IsarAdapter)
• Drift (DriftAdapter)
• ObjectBox (ObjectBoxAdapter)
• Floor (FloorAdapter)
• Realm (RealmAdapter)

📦 Installation

Add it to your pubspec.yaml:

dependencies:
  local_database_visual_debugger: ^0.0.1
  sqflite: ^2.3.0 # Or your supported database of choice

💻 Quick Start

Here is a simple example showing how to wrap your app and pass the SqliteAdapter.

import 'package:flutter/material.dart';
import 'package:sqflite/sqflite.dart';
import 'package:path/path.dart';
import 'package:local_database_visual_debugger/local_database_visual_debugger.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  // 1. Initialize your Database
  final dbPath = await getDatabasesPath();
  final db = await openDatabase(join(dbPath, 'my_app.db'));

  // 2. Instantiate the Adapter
  final adapter = SqliteAdapter(db);

  // 3. Wrap your App with LocalDbViewer
  runApp(MyApp(adapter: adapter));
}

class MyApp extends StatelessWidget {
  final DatabaseAdapter adapter;

  const MyApp({super.key, required this.adapter});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: LocalDbViewer(
        adapter: adapter,
        developerPin: '1234', // Optional: Lock UI behind a PIN
        child: const HomeScreen(),
      ),
    );
  }
}

Advanced Code-Generated ORMs (ObjectBox / Realm)

Since ObjectBox and Realm strictly rely on compiled, code-generated models, you must pass accessors to map your typed classes into dynamic maps so the visual debugger can paint them perfectly!

final adapter = ObjectBoxAdapter(
  store: myStore,
  accessors: {
    'User': ObjectBoxAccessor(
      getAllRecords: () async => userBox.getAll().map((u) => {'id': u.id, 'name': u.name}).toList(),
      putRecord: (data) async => userBox.put(User(id: data['id'], name: data['name'])),
      deleteRecord: (id) async => userBox.remove(id),
    ),
  },
);

🛠️ Architecture

This package uses the Adapter Pattern to support multiple databases while keeping a unified UI.

The core interface DatabaseAdapter defines all operations. By injecting your specific database instance into the matching Adapter, the Debugger inherits total read/write mapping instantly.

🤝 Contributing

100% Free forever. Fully open source. PRs are welcome!