uzdb/README.md

# uzdb - Lightweight Database Client

A modern, lightweight database management tool inspired by DBeaver and Navicat, built with Wails (Go + React).

## 🚀 Features

- **Multi-Database Support**: MySQL, PostgreSQL, SQLite
- **Modern UI**: Clean interface with dark/light themes
- **SQL Editor**: Syntax highlighting, autocomplete, query history
- **Data Grid**: Sortable, filterable, editable data view
- **Connection Management**: Secure credential storage with encryption
- **Fast & Lightweight**: Minimal resource usage, quick startup

## 🛠️ Tech Stack

### Frontend
- **Framework**: React 18 + TypeScript
- **Build Tool**: Vite
- **Styling**: CSS Variables + Modern CSS
- **Icons**: Lucide Icons

### Backend
- **Language**: Go 1.23+
- **Web Framework**: Gin
- **ORM**: GORM
- **Database**: SQLite3 (for app data)
- **Logging**: Zap
- **Desktop**: Wails v2

## 📁 Project Structure

```
uzdb/
├── frontend/              # React application
│   ├── src/
│   │   ├── components/    # UI components
│   │   ├── mock/          # Mock data for development
│   │   └── index.css      # Global styles
│   └── package.json
├── internal/              # Go backend (private packages)
│   ├── app/               # Wails bindings
│   ├── config/            # Configuration management
│   ├── models/            # Data models
│   ├── database/          # Database connections
│   ├── services/          # Business logic
│   ├── handler/           # HTTP handlers
│   ├── middleware/        # HTTP middleware
│   └── utils/             # Utility functions
├── doc/                   # Design documentation
│   ├── features.md        # Feature specifications
│   ├── design-system.md   # Visual design system
│   ├── wireframes.md      # UI wireframes
│   ├── user-flows.md      # User interaction flows
│   └── layout-design.md   # Layout specifications
├── main.go                # Application entry point
└── go.mod                 # Go dependencies
```

## 🚦 Getting Started

### Prerequisites

- **Go** 1.23 or higher
- **Node.js** 18 or higher
- **Wails CLI** (`go install github.com/wailsapp/wails/v2/cmd/wails@latest`)

### Installation

1. **Clone the repository**
```bash
git clone https://github.com/your-org/uzdb.git
cd uzdb
```

2. **Install Go dependencies**
```bash
go mod tidy
```

3. **Install frontend dependencies**
```bash
cd frontend
npm install
cd ..
```

### Development

#### Option 1: Run with Wails Dev Server (Recommended)
```bash
wails dev
```

This starts both the Go backend and React frontend with hot reload.

#### Option 2: Run Components Separately

**Frontend only:**
```bash
cd frontend
npm run dev
```

**Backend HTTP API only:**
```bash
go run . -http-port 8080
```

Then access API at `http://localhost:8080/api`

### Building for Production

```bash
wails build
```

The compiled binary will be in `build/bin/`.

## 📖 Usage

### Connecting to a Database

1. Click **"New Connection"** in the left sidebar
2. Select database type (MySQL, PostgreSQL, or SQLite)
3. Fill in connection details:
   - **Name**: Friendly name for the connection
   - **Host**: Database server hostname
   - **Port**: Database port (default: 3306 for MySQL, 5432 for PostgreSQL)
   - **Username/Password**: Authentication credentials
   - **Database**: Default database name
4. Click **"Test Connection"** to verify
5. Click **"Save & Connect"**

### Executing Queries

1. Select a connection from the left sidebar
2. Open a new query tab (Ctrl+T)
3. Write your SQL query
4. Press **Ctrl+Enter** or click **Run** to execute
5. View results in the data grid below

### Keyboard Shortcuts

| Action | Shortcut |
|--------|----------|
| New Connection | Ctrl+N |
| New Query Tab | Ctrl+T |
| Execute Query | Ctrl+Enter |
| Save Query | Ctrl+S |
| Find | Ctrl+F |
| Close Tab | Ctrl+W |
| Settings | Ctrl+, |

## 🔌 API Reference

The application exposes both Wails bindings (for the desktop app) and HTTP API (for debugging/integration).

### Wails Bindings (JavaScript)
```javascript
// Get all connections
const connections = await window.go.app.GetConnections();

// Execute a query
const result = await window.go.app.ExecuteQuery(connectionId, sql);

// Get table data
const data = await window.go.app.GetTableData(connectionId, tableName, limit, offset);
```

### HTTP API
See [API_TEST.md](./API_TEST.md) for detailed API documentation.

## 🔒 Security

- All database passwords are encrypted using AES-256-GCM before storage
- Encryption key is derived from a master password (future feature) or system keyring
- No credentials stored in plain text
- SSL/TLS support for database connections

## 📊 Supported Databases

| Database | Version | Status |
|----------|---------|--------|
| MySQL | 5.7+, 8.0+ | ✅ Supported |
| PostgreSQL | 12+ | ✅ Supported |
| SQLite | 3.x | ✅ Supported |
| MariaDB | 10.3+ | 🔄 Planned |
| SQL Server | 2019+ | 🔄 Planned |

## 🤝 Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

### Development Guidelines

- Follow existing code style
- Add tests for new features
- Update documentation as needed
- Ensure linting passes (`go vet`, `npm run lint`)

## 📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

## 🙏 Acknowledgments

- [Wails](https://wails.io/) - Desktop framework
- [Gin](https://gin-gonic.com/) - Web framework
- [GORM](https://gorm.io/) - ORM library
- [React](https://react.dev/) - UI library
- [DBeaver](https://dbeaver.io/) - Inspiration
- [Navicat](https://www.navicat.com/) - Inspiration

## 📞 Support

- **Issues**: [GitHub Issues](https://github.com/your-org/uzdb/issues)
- **Discussions**: [GitHub Discussions](https://github.com/your-org/uzdb/discussions)
- **Documentation**: `/doc` directory

---

**Built with ❤️ using Go + React**