planDB Documentation - SQLite & SQLCipher Database Comparison Tool

Installation

planDB is available for Linux, macOS, and Windows. Choose your platform below:

Linux

Ubuntu / Debian (.deb)

wget https://github.com/planp1125-pixel/plandb_mvp/releases/download/plandb-v0.5.9/plandb_0.5.9_amd64.deb
sudo dpkg -i plandb_0.5.9_amd64.deb

Any Linux Distribution (AppImage)

wget https://github.com/planp1125-pixel/plandb_mvp/releases/download/plandb-v0.5.9/plandb_0.5.9_amd64.AppImage
chmod +x plandb_0.5.9_amd64.AppImage
./plandb_0.5.9_amd64.AppImage

Note: If you encounter dependency issues, install required packages:

sudo apt install libwebkit2gtk-4.0-37 libgtk-3-0

macOS

Installation Steps

Download planDB_aarch64.dmg from the releases page
Open the .dmg file
Drag planDB to your Applications folder
Launch from Applications

Mac Security Warning: If you see "planDB cannot be opened because the developer cannot be verified", run:

xattr -cr /Applications/planDB.app

Then try opening again.

Windows

MSI Installer (Recommended)

Download planDB_0.5.9_x64_en-US.msi
Double-click to run installer
Follow installation wizard
Launch from Start Menu

Portable .exe

Download planDB_0.5.9_x64-setup.exe and run directly. No installation required.

Getting Started

First Launch

When you first open planDB, you'll see the main comparison interface with two database selection panels.

Basic Workflow

Select Database 1: Click "Select Database" and choose your first SQLite/SQLCipher file
Select Database 2: Click "Select Database" for the second database
Enter Password (if encrypted): For SQLCipher databases, enter the encryption password
Compare: Click "Compare Databases" to see differences
Generate Patches: Review differences and generate SQL patches

Tip: planDB remembers your last used databases for quick access!

Features

Schema Comparison

planDB compares all schema elements between databases:

✅ Tables and columns
✅ Indexes (unique, composite, partial)

The comparison result shows:

Green: Items added in Database 2
Red: Items removed from Database 1
Yellow: Items modified
Gray: Unchanged items

Data Comparison

Compare actual data row-by-row:

Identify inserted records
Identify deleted records
Identify modified records with field-level diff
Handle large datasets efficiently

Patch Generation

planDB generates bidirectional SQL patches:

Forward Patch (Database 1 → Database 2)

Applies all changes from Database 1 to make Database 2 match it.

-- Example forward patch
ALTER TABLE users ADD COLUMN email TEXT;
INSERT INTO users (id, name, email) VALUES (3, 'Alice', 'alice@example.com');
UPDATE users SET status = 'active' WHERE id = 1;

Reverse Patch (Database 2 → Database 1)

Rollback patch to undo changes if needed.

-- Example reverse patch  
UPDATE users SET status = 'inactive' WHERE id = 1;
DELETE FROM users WHERE id = 3;
ALTER TABLE users DROP COLUMN email;

Best Practice: Always download the reverse patch before applying forward changes. This gives you a safety net for rollback!

SQLCipher Support

planDB has native SQLCipher encryption support:

✅ Compare encrypted databases directly
✅ No manual decrypt/re-encrypt workflow
✅ Supports all SQLCipher versions
✅ Password-protected comparison
✅ Generate patches while maintaining encryption

Working with Encrypted Databases

Select your SQLCipher database file
Enter the encryption password when prompted
planDB handles encryption/decryption automatically
Your password is never stored or transmitted

Troubleshooting

macOS: "App cannot be opened"

Error: "planDB cannot be opened because the developer cannot be verified"

Solution:

xattr -cr /Applications/planDB.app

This removes the quarantine attribute. Then try opening again.

Linux: Missing Dependencies

Error: Library errors on launch

Solution:

sudo apt install libwebkit2gtk-4.0-37 libgtk-3-0 libayatana-appindicator3-1

Windows: SmartScreen Warning

Error: "Windows protected your PC"

Solution: Click "More info" → "Run anyway"

SQLCipher: Wrong Password

Error: "Database is encrypted or is not a database"

Solution: Verify your password is correct. SQLCipher databases cannot be opened without the correct password.

Large Databases: Slow Comparison

Issue: Comparison takes a long time

Tips:

Use schema-only comparison first
Limit data comparison to specific tables
Ensure databases are indexed properly
Close other applications to free up memory

Frequently Asked Questions

Can I compare databases of different sizes?

Yes! planDB handles databases from kilobytes to gigabytes. The comparison is done efficiently using streaming to manage memory usage.

Does planDB work offline?

Yes, completely offline. Your databases never leave your machine. No internet connection required.

Can I compare SQLite with SQLCipher?

Yes! You can compare an unencrypted SQLite database with an encrypted SQLCipher database, or any combination.

How do I apply the generated patches?

You have two options:

Direct Apply: Use planDB's built-in apply feature
Manual Apply: Export the SQL patch and run it with sqlite3 or your preferred tool

Where can I get help?

📧 Email: support@planplabs.com
💬 GitHub Issues: Report bugs or request features
💡 GitHub Discussions: Ask questions

Additional Resources

Need more help? Feel free to reach out via email or open a discussion on GitHub. We're here to help!

Download planDB

📚 planDB Documentation