uzdb/doc/features.md

uzdb Feature Specification

Overview

uzdb is a lightweight database management tool built with Wails (Go + React). It provides essential database operations without the complexity of enterprise tools like DBeaver or Navicat.

---

Target Users

1. Developers - Need quick database access for debugging and development
2. Small Teams - Want a simple, fast tool for daily database tasks
3. Students/Learners - Need an easy-to-use SQL client for learning

---

Supported Databases (MVP)

Phase 1 (Initial Release)

• ✅ MySQL 5.7+ / 8.0+
• ✅ PostgreSQL 12+
• ✅ SQLite 3.x

Phase 2 (Future)

• ⏳ MariaDB 10.3+
• ⏳ Microsoft SQL Server
• ⏳ MongoDB (basic support)

---

Core Features

1. Connection Management

1.1 Create Connection

Priority: P0
Description: Users can create new database connections
Requirements:

• Support MySQL, PostgreSQL, SQLite
• Store connection details securely
• Test connection before saving
• Support SSH tunneling (Phase 2)

UI Components:

• Connection dialog with form fields
• Database type selector
• Test connection button
• Advanced options accordion

1.2 Connection List

Priority: P0
Description: View and manage saved connections
Requirements:

• Display all saved connections
• Show connection status (connected/disconnected)
• Quick connect double-click
• Right-click context menu

UI Components:

• Sidebar connection tree
• Status indicators
• Context menu

1.3 Edit/Delete Connection

Priority: P0
Description: Modify or remove existing connections
Requirements:

• Edit connection properties
• Duplicate connection
• Delete with confirmation
• Cannot delete active connection

---

2. Schema Explorer

2.1 Database Navigation

Priority: P0
Description: Browse database structure in sidebar
Requirements:

• Expand/collapse databases
• Show schemas (PostgreSQL)
• List tables, views, procedures
• Icon differentiation by object type

UI Components:

• Tree view component
• Lazy loading for large schemas
• Search/filter capability (Phase 2)

2.2 Table Metadata

Priority: P0
Description: View table structure and information
Requirements:

• Column list with types and constraints
• Indexes display
• Foreign keys relationships
• Triggers list

UI Components:

• Right sidebar panel
• Tabbed interface for different metadata types

---

3. Query Editor

3.1 SQL Editor

Priority: P0
Description: Write and execute SQL queries
Requirements:

• Syntax highlighting (SQL keywords, strings, comments)
• Line numbers
• Basic autocomplete (table/column names)
• Multiple tabs support
• Query history (Phase 2)

UI Components:

• Monaco Editor or CodeMirror
• Tab bar for multiple queries
• Toolbar with run/save buttons

3.2 Query Execution

Priority: P0
Description: Execute SQL and view results
Requirements:

• Execute selected text or full query
• Show execution time
• Display row count
• Cancel long-running queries
• Error message display with line number

Keyboard Shortcuts:

• Ctrl+Enter: Execute query
• Ctrl+R: Refresh results

3.3 Query Snippets

Priority: P2
Description: Save and reuse common queries
Requirements:

• Save query as snippet
• Organize snippets by category
• Insert snippet into editor
• Share snippets (Phase 3)

---

4. Data Grid

4.1 Results Display

Priority: P0
Description: Show query results in tabular format
Requirements:

• Virtual scrolling for large datasets
• Column resizing
• Sort by clicking headers
• Fixed header row
• Alternating row colors

Performance:

• Render 1000+ rows smoothly
• Load data in chunks (100 rows at a time)

4.2 Data Editing

Priority: P1
Description: Edit cell values inline
Requirements:

• Double-click to edit
• Validate data types
• Show NULL indicator
• Commit on blur or Enter
• Escape to cancel

Cell Editors:

• Text input for strings
• Number input for integers/decimals
• Date picker for dates
• Checkbox for booleans
• Dropdown for enums

4.3 Pagination & Navigation

Priority: P0
Description: Navigate through result sets
Requirements:

• Page size selector (25, 50, 100, 500)
• Jump to page input
• First/Previous/Next/Last buttons
• Total row count display
• Limit/offset in query

---

5. Data Export/Import

5.1 Export Data

Priority: P0
Description: Export table/query results to file
Requirements:

• Formats: CSV, JSON, SQL INSERT
• Select destination path
• Configure export options
• Show progress for large exports

Export Options (CSV):

• Delimiter selection (comma, semicolon, tab)
• Include/exclude headers
• Quote character
• Encoding (UTF-8 default)

Export Options (JSON):

• Pretty print vs compact
• Array of objects vs arrays

5.2 Import Data

Priority: P1
Description: Import data from files
Requirements:

• Import CSV/JSON to table
• Map columns
• Preview before import
• Handle errors gracefully
• Transaction support (rollback on error)

---

6. Additional Features

6.1 Find in Results

Priority: P1
Description: Search within query results
Requirements:

• Case-sensitive toggle
• Match whole word
• Highlight matches
• Navigate between matches

6.2 Query History

Priority: P2
Description: Track executed queries
Requirements:

• Store last 100 queries per connection
• Search history
• Re-execute from history
• Pin important queries

6.3 Bookmarks

Priority: P2
Description: Save frequently used queries
Requirements:

• Bookmark query with name
• Organize in folders
• Quick access from sidebar

---

Non-Functional Requirements

Performance

• App startup: < 2 seconds
• Connection open: < 1 second (local)
• Query results render: < 100ms for 100 rows
• Memory usage: < 200MB idle

Security

• Passwords stored encrypted (keyring/keystore)
• No plain-text credentials in config files
• SSL/TLS support for connections
• Sanitize SQL inputs to prevent injection in logs

Accessibility

• WCAG 2.1 AA compliance
• Keyboard navigation throughout
• Screen reader support
• High contrast mode (Phase 2)

Internationalization

• English (initial)
• Chinese (Simplified) (Phase 2)
• Spanish (Phase 3)

---

Technical Architecture

Frontend (React + TypeScript)

src/
├── components/
│   ├── Sidebar/
│   │   ├── ConnectionTree.tsx
│   │   └── SchemaExplorer.tsx
│   ├── Editor/
│   │   ├── QueryEditor.tsx
│   │   └── SQLEditor.tsx
│   ├── Grid/
│   │   ├── DataGrid.tsx
│   │   └── CellEditor.tsx
│   ├── Dialogs/
│   │   ├── ConnectionDialog.tsx
│   │   └── ExportDialog.tsx
│   └── common/
│       ├── Button.tsx
│       ├── Input.tsx
│       └── Modal.tsx
├── hooks/
│   ├── useQuery.ts
│   └── useConnection.ts
├── stores/
│   ├── connectionStore.ts
│   └── queryStore.ts
└── utils/
    ├── formatters.ts
    └── validators.ts

Backend (Go)

internal/
├── database/
│   ├── mysql.go
│   ├── postgres.go
│   ├── sqlite.go
│   └── connection.go
├── models/
│   ├── connection.go
│   ├── query.go
│   └── table.go
└── handlers/
    ├── connection_handler.go
    ├── query_handler.go
    └── export_handler.go

---

Out of Scope (for MVP)

❌ Visual query builder
❌ ER diagrams
❌ Database comparison/sync
❌ User management
❌ Backup/restore
❌ Query profiling/optimization
❌ Multi-tab result sets
❌ Stored procedure debugger
❌ Real-time collaboration

---

Success Metrics

1. Usability: New user can connect and run query in < 2 minutes
2. Performance: Query results load in < 500ms for typical queries
3. Stability: < 1 crash per 100 hours of usage
4. Adoption: 100+ GitHub stars in first month

---

Future Roadmap

Phase 2 (v0.2)

• MariaDB support
• SSH tunneling
• Query history
• Data import
• Dark theme

Phase 3 (v0.3)

• SQL Server support
• Visual query builder (basic)
• Snippet sharing
• Plugin system

Phase 4 (v1.0)

• MongoDB support
• ER diagram viewer
• Team features (shared connections)
• Auto-update