go-doc/data/docs/go-mad-operations.md

<!-- go-doc:generated:begin source=go-mad:docs/operations.md signature=b649bc122c59343cfbc62626f6a7f52d generated=2026-10-05 18:14 UTC -->
Imported from docs/operations.md in the go-mad repository.

---

# Operations

## Migration Scripts

go-mad uses goose-style SQL migration scripts stored in `internal/migration/`. Each migration file contains `-- +goose Up` and `-- +goose Down` markers.

### Migration Format

```sql
-- +goose Up
CREATE TABLE users (
    id SERIAL PRIMARY KEY,
    tenant_id INTEGER REFERENCES tenants(id) ON DELETE CASCADE,
    username VARCHAR(255) NOT NULL UNIQUE
);

-- +goose Down
DROP TABLE IF EXISTS users CASCADE;
```

### Running Migrations

Migrations are automatically run at application startup via `database.Migrate()`. To run migrations manually or for a specific tenant:

```bash
# Using the API
curl -X POST http://localhost:8080/api/v1/databases/{id}/migrations

# Or via command line (if exposing migration tooling)
go run ./cmd/go-mad --migrate
```

### Creating New Migrations

```bash
# Create a new migration file
touch internal/migration/0004_permissions.sql

# Write up/down sections
-- +goose Up
CREATE TABLE permissions (
    id SERIAL PRIMARY KEY,
    name VARCHAR(255) NOT NULL UNIQUE
);

-- +goose Down
DROP TABLE IF EXISTS permissions CASCADE;
```

### Checking Migration Status

The application tracks applied migrations in a `schema_migrations` table. To check which migrations have been applied, query the database:

```sql
SELECT * FROM schema_migrations ORDER BY version;
```

## Backup and Restore

### PostgreSQL Backup

```bash
# Using docker exec
docker exec go-mad-postgres pg_dump -U mad -d mad > backup.sql

# Or using pg_dump directly
pg_dump -U mad -d mad > backup.sql
```

### Restore

```bash
psql -U mad -d mad < backup.sql
```

## Monitoring

The application exposes a `/health` endpoint for liveness and readiness probes:

```bash
curl http://localhost:8080/health
```

## Logs

```bash
# Docker compose logs
make compose-logs

# Or kubectl
kubectl logs deployment/go-mad
```

## Scaling

The application is designed to be stateless (except for the database connection pool). Multiple replicas can be run behind a load balancer.

## Upgrading

```bash
# Pull new image
docker pull go-mad:latest

# Or rebuild
make docker-build
docker push go-mad:latest

# Deploy
helm upgrade go-mad oci://your-registry/go-mad/helm/go-mad
```
<!-- go-doc:generated:end -->