Skip to content
Back to top
View this page

# Database Editors

Viper provides two GUI applications for exploring and managing databases:

Tool | Purpose | Use When
--- | --- | ---
cdbe.py | CommitDatabase Editor | Working with versioned data (undo/redo, sync, history)
dbe.py | Database Editor | Simple exploration without commit history

Both tools are built with PySide6 and share common components from `ds_components/`.

## cdbe.py - CommitDatabase Editor

Full-featured GUI for exploring and managing CommitDatabases with version history.

cdbe.py showing commit history, document browser, and database inspector.

### Launch

    python3 tools/cdbe.py                      # Open file dialog
    python3 tools/cdbe.py project.cdb          # Open specific database

### Panels

Access panels via keyboard shortcuts:

Panel | Shortcut | Description
--- | --- | ---
Commits | `Cmd+1` | Browse commit history (DAG visualization)
Documents | `Cmd+2` | Browse documents by attachment
Program | `Cmd+3` | View Program in selected commit
Settings | `Cmd+4` | Configure synchronization source
Undo | `Cmd+5` | Undo/redo stack visualization
Sync Log | `Cmd+6` | Synchronization activity log
Blobs | `Cmd+7` | Browse blob storage
Actions | `Cmd+8` | Pending actions queue

### Synchronization

cdbe.py supports synchronizing with a remote CommitDatabase server.

Connection Settings:

- TCP: `host:port` (e.g., `server.local:54321`)

- Unix socket: `/path/to/socket`

Sync Operations:

Action | Description
--- | ---
Fetch | Pull commits from remote server
Push | Push local commits to remote
Sync | Full sync (Fetch + Push)

Live Mode:

Enable automatic synchronization at configurable intervals:

- Live Mode: Auto-sync on timer

- Manager Mode: Auto-merge heads during live sync

### Inspecting Commits

1. Open the Commits panel (`Cmd+1`)

2. Click a commit to select it

3. Open Commands panel (`Cmd+3`) to see mutations

4. Double-click a document to inspect its content

### Undo/Redo

cdbe.py maintains an undo stack for local operations:

- Undo: `Cmd+Z`

- Redo: `Cmd+Shift+Z`

View the undo stack in the Undo panel (`Cmd+5`).

## dbe.py - Database Editor

Simplified GUI for exploring Database files (without commit history).

dbe.py showing document browser and database inspector.

### Launch

    python3 tools/dbe.py                       # Open file dialog
    python3 tools/dbe.py project.vpr           # Open specific database

### Features

Feature | Description
--- | ---
Document Browser | Browse documents by attachment
Blob Viewer | Inspect binary blob content
Database Inspector | View UUID, codec, definitions
Network Connection | Connect to remote Database server

### When to Use dbe.py vs cdbe.py

Scenario | Tool
--- | ---
Explore versioned data with history | cdbe.py
Simple database inspection | dbe.py
Synchronize with remote server | cdbe.py
Debug blob storage | Either

## ds_components - Shared GUI Library

Both editors use `ds_components/`, a PySide6 widget library:

Component | Description
--- | ---
`DSDocumentsCommitStore` | Document browser for CommitStore
`DSDocumentsDatabasing` | Document browser for Database
`DSCommitsDialog` | Commit history panel
`DSValueProgramDialog` | Program viewer
`DSInspectDialog` | Database inspector
`DSBlobsDialog` | Blob storage viewer
`DSSettings` | User preferences management

These components can be reused in custom applications built on Viper.

## What’s Next

- Server - Running a CommitDatabase server

- dsm_util - Creating databases from DSM