110 lines
3.2 KiB
Markdown
110 lines
3.2 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
`pgd` is a CLI tool for managing project-scoped PostgreSQL instances running in Docker containers. Each project gets its own isolated Postgres instance, managed through a `pgd.toml` configuration file.
|
|
|
|
## Core Architecture
|
|
|
|
### Project-Oriented Design
|
|
|
|
- Each project has a `pgd.toml` file at its root that defines the Postgres configuration
|
|
- The project name is derived from the directory containing `pgd.toml`
|
|
- Each project gets its own Docker container
|
|
- State is tracked separately per instance to detect configuration drift
|
|
|
|
### Configuration Management
|
|
|
|
The `pgd.toml` file stores:
|
|
- `postgres_version`: PostgreSQL version to use
|
|
- `database_name`: Name of the database
|
|
- `user_name`: Database user
|
|
- `password`: Database password
|
|
- `port`: Host port to bind (auto-selected from available ports)
|
|
|
|
Values are auto-populated during `pgd init` with sensible defaults or random values where appropriate.
|
|
|
|
### State Tracking
|
|
|
|
The tool maintains separate state for each instance to detect configuration drift, such as:
|
|
- Container's actual Postgres version vs. config file version
|
|
- Running container state vs. expected state
|
|
- Port conflicts or changes
|
|
|
|
## Key Dependencies
|
|
|
|
- **clap** (with derive feature): CLI argument parsing and command structure
|
|
- **toml**: Parsing and serializing `pgd.toml` configuration files
|
|
- **bollard**: Docker daemon interaction for container lifecycle management
|
|
- **tokio** (with full feature set): Async runtime for Docker operations
|
|
- **tracing** + **tracing-subscriber**: Structured logging throughout the application
|
|
- **serde**: Serialization/deserialization for config and state
|
|
- **miette** (with fancy feature): Enhanced error reporting
|
|
- **prodash** (to be added): Terminal progress bars for long-running operations
|
|
|
|
## Development Commands
|
|
|
|
### Building
|
|
```bash
|
|
cargo build
|
|
cargo build --release
|
|
```
|
|
|
|
### Running
|
|
```bash
|
|
cargo run -- <command>
|
|
# Example: cargo run -- init
|
|
```
|
|
|
|
### Testing
|
|
```bash
|
|
cargo test
|
|
cargo test <test_name> # Run specific test
|
|
```
|
|
|
|
### Linting
|
|
```bash
|
|
cargo clippy
|
|
cargo clippy -- -W clippy::all
|
|
```
|
|
|
|
### Formatting
|
|
```bash
|
|
cargo fmt
|
|
cargo fmt -- --check # Check without modifying
|
|
```
|
|
|
|
## Command Structure
|
|
|
|
The CLI follows this pattern:
|
|
```
|
|
pgd <command> [options]
|
|
```
|
|
|
|
Key commands to implement:
|
|
- `pgd init`: Create pgd.toml with auto-populated configuration
|
|
- `pgd start`: Start the Postgres container for current project
|
|
- `pgd stop`: Stop the running container
|
|
- `pgd status`: Show instance status and detect drift
|
|
- `pgd destroy`: Remove container and clean up
|
|
|
|
## Implementation Notes
|
|
|
|
### Port Selection
|
|
|
|
Port assignment should scan for available ports on the system rather than using fixed defaults to avoid conflicts.
|
|
|
|
### Docker Container Naming
|
|
|
|
Container names should be deterministic based on project name to allow easy identification and prevent duplicates.
|
|
|
|
### Error Handling
|
|
|
|
Use `miette` for user-facing errors with context. Docker operations and file I/O are the primary error sources.
|
|
|
|
### Async Operations
|
|
|
|
Docker operations via `bollard` are async. Use `tokio` runtime with `#[tokio::main]` on the main function.
|