sqluv TUI Database Client Development

Instructions for GitHub Copilot when working on sqluv, a terminal-based SQL client with Text User Interface (TUI) built in Golang.

Project Overview

sqluv is a cross-platform terminal application that provides:

The application cannot execute RDBMS connections and file loading simultaneously. No startup arguments = RDBMS mode; with arguments = file loading mode.

Architecture

The project follows **Clean Architecture** with clear dependency rules:

```

TUI → usecase (interfaces) → interactor (implementation)

↓

domain/repository (interfaces)

↓

infrastructure/memory + infrastructure/persistence

↓

domain/model

```

**Key principles:**

Directory Structure

| Directory | Purpose |

|-----------|---------|

| `config/` | Environment variables, startup arguments, configuration files (DB connections, themes, history) |

| `di/` | Dependency Injection using `github.com/google/wire` |

| `domain/model/` | Domain objects (Value Objects) |

| `domain/repository/` | Repository interfaces |

| `infrastructure/memory/` | Temporary storage implementations |

| `infrastructure/persistence/` | Persistence layer implementations |

| `infrastructure/mock/` | Repository mocks |

| `interactor/` | Use case implementations |

| `interactor/mock/` | Use case mocks |

| `usecase/` | Use case interfaces |

| `tui/` | Text User Interface components |

| `testdata/` | Test data |

| `docker/` | Dockerfile-related files |

| `doc/` | Documentation |

TUI Components

Built with `github.com/rivo/tview`, the TUI consists of:

Key Bindings

| Key | Action |

|-----|--------|

| Ctrl+d | Quit application |

| Ctrl+e | Execute SQL query |

| Ctrl+h | Show query history |

| Ctrl+c | Copy selected query |

| Ctrl+v | Paste text |

| Ctrl+x | Cut text |

| Ctrl+s | Save results to file |

| Ctrl+t | Change theme |

| / | Search table name (sidebar focused) |

| ESC | Clear search field (sidebar) |

| Space | Show/Hide columns (sidebar) |

| Enter | Show table DDL (sidebar) |

| F1 | Focus sidebar |

| F2 | Focus query text area |

| F3 | Focus results table |

| Tab | Next field |

| Shift+Tab | Previous field |

SQL Query History

Dependency Injection

Using `github.com/google/wire`:

1. Each package implementing interfaces has `wire.go`

2. Constructor functions passed to `wire.NewSet()`

3. All provider sets aggregated in `di` package via `NewSqluv()`

4. Run `make gen` to generate initialization code

Example:

```go

package config

import "github.com/google/wire"

var Set = wire.NewSet(

NewMemoryDB,

NewDBConfig,

NewColorConfig,

NewHistoryDB,

NewAWSConfig,

)

```

Infrastructure Layer

Handles RDBMS-specific and file-extension-specific implementations. For example:

Supported Data Sources

**RDBMS:**

**Files (loaded into in-memory SQLite3):**

Development Guidelines

1. **Follow Clean Architecture boundaries** — never bypass layers or reverse dependencies

2. **Single-method interfaces** — use Noun+Verb+"er" naming

3. **Value Objects for domain models** — always provide initialization functions

4. **RDBMS-agnostic interactors** — push vendor-specific logic to infrastructure layer

5. **Wire for DI** — add new dependencies via `wire.NewSet()` and run `make gen`

6. **TUI components are self-contained** — each component manages its own state and rendering

7. **Configuration lives in `config/`** — environment variables, startup arguments, and config files

Testing

Common Tasks

**Adding a new RDBMS:**

1. Implement RDBMS-specific logic in `infrastructure/persistence/`

2. Update `GetTables()` and other methods to handle new RDBMS type

3. Add connection logic in `config/`

**Adding a new TUI component:**

1. Create struct in `tui/` package

2. Implement initialization and rendering methods

3. Wire into `tui.home` component manager

4. Update key bindings in footer if needed

**Adding a new use case:**

1. Define interface in `usecase/`

2. Implement in `interactor/`

3. Add to DI wiring in `di/` package

4. Call from TUI layer