[MySQL] Documentation Updates

[mfittko]

Summary

Update all relevant documentation to include MySQL as a supported database backend, including configuration guides, deployment instructions, and architectural documentation.

Parent Epic

Part of #240 - Add MySQL as Optional Database Backend

---

🆕 Additional Items from PR Review

Single-Replica StatefulSet HA Guidance

During the review of PR #255 (Helm Chart MySQL Support), an important documentation item was identified:

The in-cluster MySQL StatefulSet is hardcoded to replicas: 1. The documentation must include clear guidance that:

⚠️ For production high-availability (HA) deployments, use an external managed MySQL service:

• Amazon Aurora MySQL / Amazon RDS for MySQL
• Google Cloud SQL for MySQL
• Azure Database for MySQL
• Self-managed MySQL Group Replication or InnoDB Cluster

Files requiring this note:

• deploy/helm/llm-proxy/README.md - MySQL section
• docs/database/database-selection.md - MySQL comparison
• docs/deployment/kubernetes.md - MySQL deployment section

The in-cluster MySQL option should be clearly positioned as development/testing only.

---

Documentation Structure

flowchart TB
    subgraph CoreDocs["Core Documentation"]
        README["README.md"]
        DOCSIDX["docs/README.md"]
    end
    
    subgraph GettingStarted["Getting Started"]
        CONFIG["configuration.md"]
        QUICK["quickstart.md"]
    end
    
    subgraph DatabaseDocs["Database Documentation"]
        DBSEL["database-selection.md"]
        DCMYSQL["docker-compose-mysql.md (NEW)"]
        DBREADME["internal/database/README.md"]
    end
    
    subgraph DeployDocs["Deployment Documentation"]
        DOCKER["deployment/docker.md"]
        K8S["deployment/kubernetes.md"]
        HELMRM["helm/README.md"]
    end
    
    subgraph ArchDocs["Architecture Documentation"]
        ARCHIDX["architecture/index.md"]
        ARCHDB["architecture/database.md"]
    end
    
    subgraph ConfigDocs["Configuration"]
        ENVEX[".env.example"]
        ENVDOC["environment-variables.md"]
    end
    
    CoreDocs --> GettingStarted
    GettingStarted --> DatabaseDocs
    DatabaseDocs --> DeployDocs
    DeployDocs --> ArchDocs
    ConfigDocs --> DatabaseDocs

Loading

---

Detailed Task Breakdown

Phase 1: Core Documentation

Task	Description	Files
1.1	Add MySQL to supported databases list	README.md
1.2	Update feature matrix	README.md
1.3	Update quick start examples	README.md
1.4	Update documentation index	docs/README.md

Phase 2: Getting Started Guides

Task	Description	Files
2.1	Add MySQL configuration section	docs/getting-started/configuration.md
2.2	Add MySQL quick start option	docs/getting-started/quickstart.md
2.3	Document build tag requirements	docs/getting-started/configuration.md

Phase 3: Database Documentation

Task	Description	Files
3.1	Add MySQL to comparison table	docs/database/database-selection.md
3.2	Document MySQL pros/cons	docs/database/database-selection.md
3.3	Create MySQL Docker guide	docs/database/docker-compose-mysql.md
3.4	Update internal database README	internal/database/README.md
3.5	Document connection string format	Multiple files
3.6	Add HA guidance for production	Multiple files (see above)

Phase 4: Deployment Documentation

Task	Description	Files
4.1	Add MySQL Docker Compose section	docs/deployment/docker.md
4.2	Add MySQL Helm configuration	docs/deployment/kubernetes.md
4.3	Update Helm chart README	deploy/helm/llm-proxy/README.md
4.4	Document build arguments	docs/deployment/docker.md
4.5	Add in-cluster MySQL limitations note	deploy/helm/llm-proxy/README.md

Phase 5: Architecture Documentation

Task	Description	Files
5.1	Add MySQL to database layer	docs/architecture/index.md
5.2	Document MySQL integration	docs/architecture/database.md
5.3	Update architecture diagrams	Multiple files

Phase 6: Configuration Documentation

Task	Description	Files
6.1	Add MySQL environment variables	.env.example
6.2	Document MySQL variables	docs/configuration/environment-variables.md
6.3	Add example configurations	Multiple files

Phase 7: Changelog and Release Notes

Task	Description	Files
7.1	Add MySQL feature entry	CHANGELOG.md
7.2	Document breaking changes (none)	CHANGELOG.md

---

Database Comparison Table

Update docs/database/database-selection.md with:

Feature	SQLite	PostgreSQL	MySQL
Setup Complexity	Zero config	Medium	Medium
Horizontal Scaling	✗ Single instance	✓ Multiple instances	✓ Multiple instances
Concurrent Writes	Limited	Excellent	Excellent
Best For	Dev, small deployments	Production, analytics	Production, web apps
Build Tag Required	No	Yes (-tags postgres)	Yes (-tags mysql)
Maintenance	None	Requires DBA	Requires DBA
Cloud Managed Options	N/A	RDS, Aurora, Cloud SQL	RDS, Aurora, Cloud SQL
In-Cluster Helm	N/A	Dev/Test only	Dev/Test only

---

Environment Variables Reference

Add to documentation:

Variable	Type	Required	Default	Description
DB_DRIVER	string	No	sqlite	Database driver: sqlite, postgres, or mysql
DATABASE_URL	string	If MySQL	-	MySQL connection string
DATABASE_PATH	string	If SQLite	./data/proxy.db	SQLite file path

---

Build Instructions to Document

Binary Build

Build Type	Command	Notes
SQLite only	go build ./...	Default, smallest binary
With MySQL	go build -tags mysql ./...	Includes MySQL driver
With PostgreSQL	go build -tags postgres ./...	Includes PostgreSQL driver
All databases	go build -tags "mysql,postgres" ./...	Full support

Docker Build

Build Type	Command	Notes
With MySQL	docker build --build-arg BUILD_TAGS=mysql ...	MySQL support
All databases	docker build --build-arg BUILD_TAGS="mysql,postgres" ...	Full support

---

Documentation Quality Checklist

Content Requirements

• All configuration examples tested and verified
• All commands verified to work
• All links working and accurate
• Consistent terminology throughout
• Version compatibility noted (MySQL 8.0+, MariaDB 10.5+)
• HA guidance included for production deployments

Style Requirements

• Follows existing documentation style
• Uses consistent formatting
• Includes appropriate diagrams
• Has clear section headings
• Uses tables for structured information

Technical Accuracy

• Connection string formats verified
• Environment variables accurate
• Build commands tested
• Docker commands tested
• Helm commands tested

---

Acceptance Criteria

• All documentation files updated and reviewed
• Database comparison table includes MySQL
• Build and deployment instructions verified
• Troubleshooting guide covers MySQL-specific issues
• Links between documentation pages work correctly
• Documentation follows existing style and format
• CHANGELOG.md updated with appropriate version/date
• .env.example includes MySQL variables
• Helm chart README updated
• Internal database README updated
• HA guidance for production MySQL deployments included

---

Files to Create/Modify

File	Action	Priority
README.md	Modify	High
docs/README.md	Modify	High
docs/database/database-selection.md	Modify	High
docs/database/docker-compose-mysql.md	Create	Medium
docs/getting-started/configuration.md	Modify	High
docs/getting-started/quickstart.md	Modify	Medium
docs/deployment/docker.md	Modify	High
docs/deployment/kubernetes.md	Modify	High
docs/architecture/index.md	Modify	Medium
internal/database/README.md	Modify	High
deploy/helm/llm-proxy/README.md	Modify	High
.env.example	Modify	High
CHANGELOG.md	Modify	High

---

Dependencies

This should be one of the last sub-issues completed, after:

• [MySQL] Driver Integration and Connection Handling #241 MySQL Driver Integration ✅
• [MySQL] Schema Migrations #242 MySQL Migrations ✅
• [MySQL] Docker Compose Profile #243 Docker Compose Profile ✅
• [MySQL] Helm Chart Support #244 Helm Chart Support ✅ (PR Add MySQL support to Helm chart #255 approved)
• [MySQL] Integration Tests and CI #245 Integration Tests ✅ (PR Add MySQL integration tests and CI pipeline #256 approved)

This ensures all documented features are actually implemented and tested.