initial commit

docs/operations.md

@@ -0,0 +1,110 @@
+# 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
+```