# 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