# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

**dbsetup** is a Go helper module for database connection pool initialization with OpenTelemetry (OTEL) instrumentation. It wraps database connections with OTEL to automatically add SQL queries to tracing spans.

- Module path: `gitea.unbound.se/unboundsoftware/dbsetup`
- Primary dependencies: sqlx, goose (migrations), otelsqlx (OTEL wrapper)

## Common Commands

```bash
# Download dependencies
go mod download

# Run tests with race detection and coverage
CGO_ENABLED=1 go test -race -coverprofile=coverage.txt ./...

# Generate coverage report
go tool cover -html=coverage.txt -o coverage.html

# Check for security vulnerabilities
go install golang.org/x/vuln/cmd/govulncheck@latest
govulncheck ./...

# Run pre-commit hooks (add all files first)
git add -A && pre-commit run --all-files
```

## Architecture

Single-package module with one source file (`database.go`):

- **DatabaseConfig**: Configuration struct with connection URL, driver name, and pool settings. Uses struct tags compatible with kong CLI parser.
- **Database**: Main handler providing:
  - `SetupDB()` - Validates database connection and returns Database instance
  - `Connect()` - Creates OTEL-wrapped connection pool via otelsqlx
  - `RunMigrations()` - Executes goose migrations from an `fs.FS` filesystem

## Code Quality

Pre-commit hooks enforce:
- gofumpt formatting (stricter than gofmt)
- golangci-lint
- go-imports with local path `gitea.unbound.se/unboundsoftware/`
- Conventional commits format (feat:, fix:, chore:, etc.)
- Gitleaks for secret detection

## CI/CD

GitLab CI pipeline runs: dependency download → tests with race detector → vulnerability scanning → Codecov upload.