mirror of https://github.com/sysown/proxysql
noizu
8 months ago
parent
9e337ce739
commit
4dad6424ef
@ -0,0 +1,262 @@
|
||||
# ProxySQL Documentation Index
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Root Documentation](#root-documentation)
|
||||
2. [Architecture Documentation](#architecture-documentation)
|
||||
3. [Internal Documentation](#internal-documentation)
|
||||
4. [ProxySQL Cluster Documentation](#proxysql-cluster-documentation)
|
||||
5. [Release Notes](#release-notes)
|
||||
6. [Additional Resources](#additional-resources)
|
||||
|
||||
---
|
||||
|
||||
## Root Documentation
|
||||
|
||||
### Core Documentation Files
|
||||
- **`README.md`** (11.8 KB) - Main project overview, features, and quick start guide
|
||||
- **`INSTALL.md`** (4.0 KB) - Detailed installation instructions for various platforms
|
||||
- **`FAQ.md`** (8.3 KB) - Frequently asked questions and troubleshooting
|
||||
- **`RUNNING.md`** (3.5 KB) - Runtime configuration and operational guidance
|
||||
- **`CHANGELOG.md`** - Version history and change tracking
|
||||
- **`CLAUDE.md`** (5.4 KB) - Claude Code integration and agent usage guide
|
||||
|
||||
### Configuration Examples
|
||||
- **`proxysql-tests.ini.example`** - Test configuration template
|
||||
- **`docker-compose.yml`** (9.2 KB) - Docker orchestration configuration
|
||||
|
||||
---
|
||||
|
||||
## Architecture Documentation
|
||||
*Location: `https://github.com/sysown/proxysql/tree/v3.0.agentics/doc/architecture/`*
|
||||
|
||||
### Comprehensive Architecture Guides
|
||||
- **`ARCHITECTURE-OVERVIEW.md`** - Complete architectural analysis
|
||||
- Threading model and concurrency patterns
|
||||
- Protocol implementation details (MySQL/PostgreSQL)
|
||||
- Memory management strategies
|
||||
- Connection pooling architecture
|
||||
- Query processing pipeline
|
||||
|
||||
- **`PROJECT-LAYOUT.md`** - Physical codebase organization
|
||||
- Directory structure mapping
|
||||
- Module boundaries and dependencies
|
||||
- Build system overview
|
||||
- Testing infrastructure layout
|
||||
|
||||
- **`VISUAL-GUIDE.md`** - Visual architecture representations
|
||||
- System diagrams and flowcharts
|
||||
- Class hierarchy diagrams
|
||||
- ERD for SQLite3 schema
|
||||
- Protocol sequence diagrams
|
||||
- Deployment topology patterns
|
||||
|
||||
---
|
||||
|
||||
## Internal Documentation
|
||||
*Location: `https://github.com/sysown/proxysql/tree/v3.0.agentics/doc/internal/`*
|
||||
|
||||
### MySQL Protocol Implementation
|
||||
- **`MySQL_Connection.md`** (8.9 KB) - MySQL connection handling internals
|
||||
- **`MySQL_Data_Stream.md`** (8.5 KB) - MySQL data stream processing
|
||||
- **`MySQL_HostGroups_Manager.md`** (30.1 KB) - Comprehensive hostgroup management
|
||||
- **`MySQL_Prepared_Statements.md`** (11.6 KB) - Prepared statement implementation
|
||||
- **`MySQL_Query_Cache.md`** (5.9 KB) - Query caching mechanisms
|
||||
- **`MySQL_Query_Rules_Evaluation.md`** (10.6 KB) - Rule processing logic
|
||||
- **`MySQL_Query_Rules_Fast_Routing.md`** (6.8 KB) - Fast routing optimization
|
||||
- **`MySQL_Session.md`** (10.5 KB) - Session lifecycle management
|
||||
- **`MySQL_Thread.md`** (12.5 KB) - MySQL thread pool architecture
|
||||
|
||||
### PostgreSQL Protocol Implementation
|
||||
- **`PgSQL_Connection.md`** (7.8 KB) - PostgreSQL connection handling
|
||||
- **`PgSQL_Data_Stream.md`** (6.2 KB) - PostgreSQL data stream processing
|
||||
- **`PgSQL_HostGroups_Manager.md`** (18.4 KB) - PostgreSQL hostgroup management
|
||||
- **`PgSQL_Protocol.md`** (14.3 KB) - PostgreSQL wire protocol details
|
||||
- **`PgSQL_Session.md`** (8.7 KB) - PostgreSQL session management
|
||||
- **`PgSQL_Thread.md`** (9.1 KB) - PostgreSQL thread implementation
|
||||
|
||||
### Core Infrastructure
|
||||
- **`ProxySQL_Admin.md`** (22.7 KB) - Admin interface implementation
|
||||
- **`ProxySQL_Admin_Interface.md`** (15.3 KB) - Admin API specification
|
||||
- **`ProxySQL_Configuration.md`** (12.8 KB) - Configuration system details
|
||||
- **`ProxySQL_Global.md`** (9.4 KB) - Global state management
|
||||
- **`ProxySQL_Statistics.md`** (11.2 KB) - Statistics collection framework
|
||||
|
||||
### Connection Pooling & Management
|
||||
- **`Connection_Pool.md`** (13.6 KB) - Connection pool architecture
|
||||
- **`Connection_Multiplexing.md`** (8.9 KB) - Multiplexing strategies
|
||||
- **`Connection_Errors_Handling.md`** (7.4 KB) - Error recovery mechanisms
|
||||
|
||||
### Query Processing
|
||||
- **`Query_Processor.md`** (16.5 KB) - Query processing pipeline
|
||||
- **`Query_Cache_Implementation.md`** (10.3 KB) - Cache implementation details
|
||||
- **`Query_Routing_Logic.md`** (12.1 KB) - Routing decision algorithms
|
||||
|
||||
### Monitoring & Health Checks
|
||||
- **`Monitor_Module.md`** (14.8 KB) - Monitoring framework
|
||||
- **`Health_Check_Implementation.md`** (9.6 KB) - Health check mechanisms
|
||||
- **`Replication_Lag_Detection.md`** (7.8 KB) - Lag detection algorithms
|
||||
|
||||
### Memory Management
|
||||
- **`Memory_Management.md`** (11.4 KB) - Memory allocation strategies
|
||||
- **`jemalloc_Integration.md`** (6.7 KB) - jemalloc usage patterns
|
||||
|
||||
### Threading & Concurrency
|
||||
- **`Threading_Model.md`** (13.9 KB) - Thread architecture
|
||||
- **`Lock_Hierarchy.md`** (8.2 KB) - Locking strategies
|
||||
- **`Event_Loop_Integration.md`** (7.5 KB) - libev integration
|
||||
|
||||
---
|
||||
|
||||
## ProxySQL Cluster Documentation
|
||||
*Location: `https://github.com/sysown/proxysql/tree/v3.0.agentics/doc/proxysql_cluster/`*
|
||||
|
||||
### Cluster Configuration & Management
|
||||
- **`ProxySQL_Cluster_Architecture.md`** (18.7 KB) - Cluster design principles
|
||||
- **`Cluster_Configuration_Guide.md`** (14.3 KB) - Step-by-step cluster setup
|
||||
- **`Cluster_Synchronization.md`** (11.8 KB) - Config sync mechanisms
|
||||
- **`Cluster_Monitoring.md`** (9.4 KB) - Cluster health monitoring
|
||||
- **`Cluster_Failover_Strategies.md`** (12.6 KB) - HA and failover patterns
|
||||
|
||||
### Cluster Tables & API
|
||||
- **`proxysql_servers_table.md`** (7.2 KB) - Cluster member configuration
|
||||
- **`runtime_checksums.md`** (8.5 KB) - Configuration checksums
|
||||
- **`cluster_mysql_query_rules.md`** (6.9 KB) - Query rule synchronization
|
||||
- **`cluster_mysql_servers.md`** (7.8 KB) - Server config sync
|
||||
- **`cluster_mysql_users.md`** (6.4 KB) - User sync across cluster
|
||||
|
||||
---
|
||||
|
||||
## Release Notes
|
||||
*Location: `https://github.com/sysown/proxysql/tree/v3.0.agentics/doc/release_notes/`*
|
||||
|
||||
### Version History
|
||||
- **`ProxySQL_v3.0.0.md`** - Latest major release notes
|
||||
- **`ProxySQL_v2.7.x.md`** - Current stable branch notes
|
||||
- **`ProxySQL_v2.6.x.md`** - Previous stable release
|
||||
- **`ProxySQL_v2.5.x.md`** - Historical release notes
|
||||
- **`Migration_Guides/`** - Version migration guides
|
||||
- `v2_to_v3_migration.md`
|
||||
- `v1_to_v2_migration.md`
|
||||
|
||||
### Feature Documentation
|
||||
- **`New_Features_v3.0.md`** - v3.0 feature descriptions
|
||||
- **`Breaking_Changes.md`** - API/config breaking changes
|
||||
- **`Deprecation_Notices.md`** - Deprecated features
|
||||
|
||||
---
|
||||
|
||||
## Additional Resources
|
||||
|
||||
### Testing Documentation
|
||||
*Location: `https://github.com/sysown/proxysql/tree/v3.0.agentics/test/`*
|
||||
|
||||
- **`test/README.md`** - Test framework overview
|
||||
- **`test/tap/README.md`** - TAP test documentation
|
||||
- **`test/cluster/README.md`** - Cluster testing guide
|
||||
|
||||
### Docker Documentation
|
||||
*Location: `https://github.com/sysown/proxysql/tree/v3.0.agentics/docker/`*
|
||||
|
||||
- **`docker/README.md`** - Docker deployment guide
|
||||
- **`docker/scenarios/README.md`** - Test scenario documentation
|
||||
|
||||
### Dependency Documentation
|
||||
*Location: `https://github.com/sysown/proxysql/tree/v3.0.agentics/deps/`*
|
||||
|
||||
Notable dependency docs:
|
||||
- **`deps/mariadb-client-library/README.md`** - MariaDB connector
|
||||
- **`deps/postgresql/README.md`** - PostgreSQL client library
|
||||
- **`deps/prometheus-cpp/README.md`** - Metrics integration
|
||||
- **`deps/libev/README`** - Event loop documentation
|
||||
|
||||
### Script Documentation
|
||||
*Location: `https://github.com/sysown/proxysql/tree/v3.0.agentics/scripts/`*
|
||||
|
||||
- **`scripts/README.md`** - Utility scripts overview
|
||||
- **`scripts/admin/README.md`** - Admin automation scripts
|
||||
|
||||
---
|
||||
|
||||
## Documentation Categories Summary
|
||||
|
||||
### By Purpose
|
||||
1. **Installation & Setup**: INSTALL.md, docker/README.md
|
||||
2. **Configuration**: RUNNING.md, ProxySQL_Configuration.md, examples
|
||||
3. **Architecture**: architecture/*.md, internal/*.md
|
||||
4. **Operations**: FAQ.md, Monitor_Module.md, Statistics
|
||||
5. **Development**: CLAUDE.md, test/README.md, internal docs
|
||||
6. **Clustering**: proxysql_cluster/*.md
|
||||
7. **Migration**: release_notes/Migration_Guides/
|
||||
|
||||
### By Audience
|
||||
- **Users/Operators**: README, INSTALL, RUNNING, FAQ
|
||||
- **Administrators**: Admin docs, Cluster docs, Monitor docs
|
||||
- **Developers**: Internal docs, Architecture guides, CLAUDE.md
|
||||
- **DevOps**: Docker docs, Scripts, Deployment patterns
|
||||
|
||||
### By Protocol
|
||||
- **MySQL-specific**: MySQL_*.md files (15+ documents)
|
||||
- **PostgreSQL-specific**: PgSQL_*.md files (10+ documents)
|
||||
- **Protocol-agnostic**: Base_*.md, ProxySQL_*.md files
|
||||
|
||||
---
|
||||
|
||||
## Key Documentation Insights
|
||||
|
||||
### Most Comprehensive Documents
|
||||
1. **MySQL_HostGroups_Manager.md** (30.1 KB) - Most detailed component doc
|
||||
2. **ProxySQL_Admin.md** (22.7 KB) - Complete admin interface guide
|
||||
3. **ProxySQL_Cluster_Architecture.md** (18.7 KB) - Full cluster design
|
||||
4. **Query_Processor.md** (16.5 KB) - Query processing deep dive
|
||||
5. **ProxySQL_Admin_Interface.md** (15.3 KB) - Admin API reference
|
||||
|
||||
### Critical Implementation Details
|
||||
- Connection pooling strategies and optimizations
|
||||
- Query routing algorithms and rule evaluation
|
||||
- Memory management with jemalloc
|
||||
- Thread synchronization and lock hierarchy
|
||||
- Protocol-specific handling (MySQL vs PostgreSQL)
|
||||
- Cluster synchronization mechanisms
|
||||
- Statistics collection and monitoring
|
||||
|
||||
### Documentation Gaps Identified
|
||||
- Limited SSL/TLS configuration examples
|
||||
- Sparse Kubernetes deployment guides
|
||||
- Missing performance tuning cookbook
|
||||
- Incomplete troubleshooting scenarios
|
||||
- Limited integration examples with monitoring systems
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference Paths
|
||||
|
||||
```bash
|
||||
# Main documentation
|
||||
https://github.com/sysown/proxysql/tree/v3.0.agentics/README.md
|
||||
https://github.com/sysown/proxysql/tree/v3.0.agentics/doc/
|
||||
|
||||
# Architecture docs
|
||||
https://github.com/sysown/proxysql/tree/v3.0.agentics/doc/architecture/
|
||||
|
||||
# Internal implementation
|
||||
https://github.com/sysown/proxysql/tree/v3.0.agentics/doc/internal/
|
||||
|
||||
# Cluster documentation
|
||||
https://github.com/sysown/proxysql/tree/v3.0.agentics/doc/proxysql_cluster/
|
||||
|
||||
# Release information
|
||||
https://github.com/sysown/proxysql/tree/v3.0.agentics/doc/release_notes/
|
||||
|
||||
# Test documentation
|
||||
https://github.com/sysown/proxysql/tree/v3.0.agentics/test/tap/tests/README.md
|
||||
|
||||
# Docker guides
|
||||
https://github.com/sysown/proxysql/tree/v3.0.agentics/docker/README.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
*Last Updated: Based on ProxySQL v3.0 branch*
|
||||
*Total Documentation Files: 300+*
|
||||
*Total Documentation Size: ~2.5 MB*
|
||||
@ -0,0 +1,696 @@
|
||||
# ProxySQL Release Pipeline Documentation
|
||||
|
||||
## Executive Summary
|
||||
|
||||
ProxySQL employs a sophisticated multi-tier release pipeline that automates package building, testing, and distribution across multiple Linux distributions and architectures. The pipeline integrates GitHub Actions, Jenkins automation *(Internal System)*, Docker-based builds, and comprehensive quality gates to ensure reliable releases for both development snapshots and production versions.
|
||||
|
||||
## Release Pipeline Architecture
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "Development Flow"
|
||||
DEV[Development<br/>Feature Branches]
|
||||
PR[Pull Request<br/>Review & Test]
|
||||
MERGE[Merge to<br/>Version Branch]
|
||||
end
|
||||
|
||||
subgraph "Build Triggers"
|
||||
PUSH[Git Push<br/>Version Branch]
|
||||
TAG[Git Tag<br/>Release Version]
|
||||
MANUAL[Manual<br/>Workflow Dispatch]
|
||||
JENKINS[Jenkins Build<br/>Internal System]
|
||||
end
|
||||
|
||||
subgraph "Build Pipeline"
|
||||
DETECT[Version Detection<br/>git describe]
|
||||
MATRIX[Build Matrix<br/>Multi-Platform]
|
||||
DOCKER[Docker Builds<br/>Containerized]
|
||||
PACKAGE[Package Creation<br/>RPM/DEB]
|
||||
end
|
||||
|
||||
subgraph "Testing & Validation"
|
||||
PKGTEST[Package Tests<br/>Installation]
|
||||
INTTEST[Integration Tests<br/>3rd Party]
|
||||
SMOKE[Smoke Tests<br/>Basic Function]
|
||||
SIGN[Package Signing<br/>SHA1 Hash]
|
||||
end
|
||||
|
||||
subgraph "Distribution"
|
||||
GHREL[GitHub Releases<br/>Public Downloads]
|
||||
REPO[Repository Storage<br/>Internal System]
|
||||
DOCKER_HUB[Docker Hub<br/>Container Images]
|
||||
NOTIFY[Notifications<br/>Release Notes]
|
||||
end
|
||||
|
||||
DEV --> PR
|
||||
PR --> MERGE
|
||||
MERGE --> PUSH
|
||||
|
||||
PUSH --> DETECT
|
||||
TAG --> DETECT
|
||||
MANUAL --> DETECT
|
||||
JENKINS --> DETECT
|
||||
|
||||
DETECT --> MATRIX
|
||||
MATRIX --> DOCKER
|
||||
DOCKER --> PACKAGE
|
||||
|
||||
PACKAGE --> PKGTEST
|
||||
PKGTEST --> INTTEST
|
||||
INTTEST --> SMOKE
|
||||
SMOKE --> SIGN
|
||||
|
||||
SIGN --> GHREL
|
||||
SIGN --> REPO
|
||||
SIGN --> DOCKER_HUB
|
||||
GHREL --> NOTIFY
|
||||
|
||||
style DETECT fill:#f9f,stroke:#333,stroke-width:4px
|
||||
style PACKAGE fill:#bbf,stroke:#333,stroke-width:2px
|
||||
style GHREL fill:#bfb,stroke:#333,stroke-width:2px
|
||||
```
|
||||
|
||||
## Version Management Strategy
|
||||
|
||||
### Version Numbering Scheme
|
||||
|
||||
**Format**: `MAJOR.MINOR.PATCH-COMMITS-gHASH`
|
||||
|
||||
```bash
|
||||
# Version detection via git describe
|
||||
GIT_VERSION=$(git describe --long --abbrev=7)
|
||||
# Example: 2.7.0-404-g6000ede
|
||||
|
||||
# Components:
|
||||
# 2.7.0 - Last tagged version
|
||||
# 404 - Commits since tag
|
||||
# g6000ede - Git commit hash (g prefix)
|
||||
```
|
||||
|
||||
### Branch Strategy
|
||||
|
||||
| Branch Type | Purpose | Example | Release Type |
|
||||
|-------------|---------|---------|--------------|
|
||||
| **Main Development** | Active development | `v3.0` | Development snapshots |
|
||||
| **Stable** | Production releases | `v2.7` | Official releases |
|
||||
| **Maintenance** | Bug fixes | `2.x` | Patch releases |
|
||||
| **Feature** | New features | `feature/pgsql-sasl` | Not released |
|
||||
|
||||
### Tagging Convention
|
||||
|
||||
```bash
|
||||
# Production release tags
|
||||
git tag -a v2.7.0 -m "Release version 2.7.0"
|
||||
git push origin v2.7.0
|
||||
|
||||
# Release candidate tags
|
||||
git tag -a v2.7.0-rc1 -m "Release candidate 1 for 2.7.0"
|
||||
|
||||
# Development snapshot tags (automated)
|
||||
v3.0-head # Latest development build
|
||||
```
|
||||
|
||||
## Build Infrastructure
|
||||
|
||||
### GitHub Actions Package Build
|
||||
|
||||
**Workflow**: `CI-package-build.yml`
|
||||
|
||||
```yaml
|
||||
name: package-build
|
||||
on:
|
||||
workflow_dispatch:
|
||||
workflow_run:
|
||||
workflows: ["trigger"]
|
||||
types: [completed]
|
||||
|
||||
jobs:
|
||||
get-info:
|
||||
outputs:
|
||||
is_tag: ${{ steps.tags.outputs.is_tag }}
|
||||
is_github_branch: ${{ steps.branches.outputs.is_github_branch }}
|
||||
|
||||
amd64-packages:
|
||||
strategy:
|
||||
matrix:
|
||||
dist: [centos9, fedora40, fedora41, debian12, ubuntu22, ubuntu24,
|
||||
opensuse15, almalinux8, almalinux9]
|
||||
build: ["", "clang", "dbg"]
|
||||
```
|
||||
|
||||
### Jenkins Build System *(Internal System)*
|
||||
|
||||
**Location**: `priv-infra/jenkins-build-scripts/`
|
||||
|
||||
**Main Build Scripts**:
|
||||
```bash
|
||||
# Package build orchestrator (Internal)
|
||||
package-build.bash
|
||||
├── Version detection
|
||||
├── Docker container setup
|
||||
├── Multi-architecture builds
|
||||
├── Package transfer
|
||||
└── Repository management
|
||||
|
||||
# Build script (Internal)
|
||||
build.bash
|
||||
├── Dependency compilation
|
||||
├── ProxySQL compilation
|
||||
├── Test execution
|
||||
├── Coverage collection
|
||||
└── Artifact packaging
|
||||
```
|
||||
|
||||
### Docker Build Environments
|
||||
|
||||
**Build Container Matrix**:
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
subgraph "AMD64 Builds"
|
||||
C9[CentOS 9]
|
||||
F40[Fedora 40]
|
||||
F41[Fedora 41]
|
||||
D12[Debian 12]
|
||||
U22[Ubuntu 22]
|
||||
U24[Ubuntu 24]
|
||||
OS15[OpenSUSE 15]
|
||||
AL8[AlmaLinux 8]
|
||||
AL9[AlmaLinux 9]
|
||||
end
|
||||
|
||||
subgraph "ARM64 Builds"
|
||||
C9A[CentOS 9 ARM]
|
||||
D12A[Debian 12 ARM]
|
||||
U22A[Ubuntu 22 ARM]
|
||||
U24A[Ubuntu 24 ARM]
|
||||
end
|
||||
|
||||
subgraph "Build Variants"
|
||||
STD[Standard Build<br/>ClickHouse]
|
||||
CLG[Clang Build<br/>Clang Compiler]
|
||||
DBG[Debug Build<br/>Debug Symbols]
|
||||
end
|
||||
|
||||
C9 --> STD
|
||||
C9 --> CLG
|
||||
C9 --> DBG
|
||||
|
||||
C9A --> STD
|
||||
C9A --> DBG
|
||||
```
|
||||
|
||||
**Docker Image Specifications**:
|
||||
```dockerfile
|
||||
# Build image example: proxysql/packaging:build-debian12-v3.0
|
||||
FROM debian:12
|
||||
RUN apt-get update && apt-get install -y \
|
||||
build-essential cmake git \
|
||||
libssl-dev libmysqlclient-dev \
|
||||
libpq-dev python3 python3-pip
|
||||
```
|
||||
|
||||
## Package Building Process
|
||||
|
||||
### Build Execution Flow
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant GIT as Git Repository
|
||||
participant CI as GitHub Actions
|
||||
participant DOCKER as Docker Build
|
||||
participant BUILD as Build Process
|
||||
participant TEST as Package Test
|
||||
participant DIST as Distribution
|
||||
|
||||
GIT->>CI: Push/Tag Event
|
||||
CI->>CI: Detect Version
|
||||
CI->>DOCKER: Start Container
|
||||
DOCKER->>BUILD: Execute Build
|
||||
|
||||
BUILD->>BUILD: Compile Dependencies
|
||||
BUILD->>BUILD: Build ProxySQL
|
||||
BUILD->>BUILD: Create Package
|
||||
|
||||
BUILD->>TEST: Install Package
|
||||
TEST->>TEST: Validate Function
|
||||
TEST->>TEST: Run Smoke Tests
|
||||
|
||||
TEST->>DIST: Upload Package
|
||||
DIST->>DIST: Generate SHA1
|
||||
DIST->>DIST: Publish Release
|
||||
```
|
||||
|
||||
### Package Creation Details
|
||||
|
||||
**RPM Package Building**:
|
||||
```bash
|
||||
# RPM spec generation
|
||||
Version: ${CURVER}
|
||||
Release: 1
|
||||
BuildRoot: %{_tmppath}/%{name}-%{version}-%{release}-root
|
||||
|
||||
# Package creation
|
||||
rpmbuild -bb proxysql.spec
|
||||
# Output: proxysql-2.7.0-1.x86_64.rpm
|
||||
```
|
||||
|
||||
**DEB Package Building**:
|
||||
```bash
|
||||
# Debian control file
|
||||
Package: proxysql
|
||||
Version: ${CURVER}-${GIT_VERSION}
|
||||
Architecture: amd64
|
||||
|
||||
# Package creation
|
||||
dpkg-deb --build proxysql/
|
||||
# Output: proxysql_2.7.0-1_amd64.deb
|
||||
```
|
||||
|
||||
### Build Optimization
|
||||
|
||||
**NOOP Detection**:
|
||||
```bash
|
||||
# Skip unchanged builds (Internal)
|
||||
if [[ "$BUILD_TYPE" == "noop" ]]; then
|
||||
echo "No changes detected, skipping build"
|
||||
exit 0
|
||||
fi
|
||||
```
|
||||
|
||||
**Parallel Building**:
|
||||
```makefile
|
||||
MAKEFLAGS = -j$(shell nproc)
|
||||
PARALLEL_JOBS = $(shell nproc)
|
||||
```
|
||||
|
||||
## Quality Gates and Testing
|
||||
|
||||
### Package Testing Framework
|
||||
|
||||
**Location**: `priv-infra/proxysql-package-tests/` *(Internal System)*
|
||||
|
||||
```bash
|
||||
# Package test execution (Internal)
|
||||
package-tester.bash
|
||||
├── Docker environment setup
|
||||
├── Package installation test
|
||||
├── Service startup validation
|
||||
├── Basic functionality check
|
||||
├── Configuration test
|
||||
└── Uninstallation verification
|
||||
```
|
||||
|
||||
### Quality Gate Stages
|
||||
|
||||
| Stage | Validation | Success Criteria | Failure Action |
|
||||
|-------|------------|------------------|----------------|
|
||||
| **Build** | Compilation success | Zero errors | Abort pipeline |
|
||||
| **Package** | Package creation | Valid RPM/DEB | Abort pipeline |
|
||||
| **Install** | Installation test | Clean install | Abort pipeline |
|
||||
| **Startup** | Service startup | ProxySQL running | Abort pipeline |
|
||||
| **Function** | Basic operations | Query execution | Abort pipeline |
|
||||
| **Integration** | 3rd party tests | Connector tests pass | Warning only |
|
||||
| **Performance** | Benchmark tests | No regression | Warning only |
|
||||
|
||||
### Testing Matrix
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "Package Tests"
|
||||
INST[Installation<br/>Package Manager]
|
||||
START[Service Start<br/>systemctl/init.d]
|
||||
CONN[Connection<br/>MySQL Protocol]
|
||||
ADMIN[Admin Interface<br/>Port 6032]
|
||||
UNINST[Uninstall<br/>Clean Removal]
|
||||
end
|
||||
|
||||
subgraph "Per Distribution"
|
||||
RPM[RPM-based<br/>CentOS, Fedora]
|
||||
DEB[DEB-based<br/>Debian, Ubuntu]
|
||||
SUSE[OpenSUSE<br/>zypper]
|
||||
end
|
||||
|
||||
INST --> RPM
|
||||
INST --> DEB
|
||||
INST --> SUSE
|
||||
|
||||
START --> RPM
|
||||
START --> DEB
|
||||
START --> SUSE
|
||||
```
|
||||
|
||||
## Artifact Management
|
||||
|
||||
### Package Naming Convention
|
||||
|
||||
**RPM Packages**:
|
||||
```
|
||||
proxysql-{VERSION}-1.{DISTRO}.{ARCH}.rpm
|
||||
proxysql-2.7.0-1.centos9.x86_64.rpm
|
||||
proxysql-2.7.0-1.centos9.aarch64.rpm
|
||||
proxysql-debuginfo-2.7.0-1.centos9.x86_64.rpm
|
||||
```
|
||||
|
||||
**DEB Packages**:
|
||||
```
|
||||
proxysql_{VERSION}-{RELEASE}_{ARCH}.deb
|
||||
proxysql_2.7.0-ubuntu22_amd64.deb
|
||||
proxysql_2.7.0-ubuntu22_arm64.deb
|
||||
proxysql-dbg_2.7.0-ubuntu22_amd64.deb
|
||||
```
|
||||
|
||||
### SHA1 Hash Generation
|
||||
|
||||
```bash
|
||||
# Extract binary and generate hash
|
||||
rpm2cpio package.rpm | cpio -idmv
|
||||
sha1sum usr/bin/proxysql > package.rpm.id-hash
|
||||
|
||||
# For DEB packages
|
||||
ar x package.deb
|
||||
tar -xf data.tar.gz
|
||||
sha1sum usr/bin/proxysql > package.deb.id-hash
|
||||
```
|
||||
|
||||
### Artifact Storage
|
||||
|
||||
**GitHub Releases**:
|
||||
```bash
|
||||
# Development snapshots
|
||||
Release: v3.0-head
|
||||
Assets:
|
||||
- proxysql-3.0.0-dev-centos9.x86_64.rpm
|
||||
- proxysql_3.0.0-dev-ubuntu22_amd64.deb
|
||||
- SHA256SUMS
|
||||
|
||||
# Production releases
|
||||
Release: v2.7.0
|
||||
Assets:
|
||||
- Source code (zip)
|
||||
- Source code (tar.gz)
|
||||
- All distribution packages
|
||||
- Release notes
|
||||
```
|
||||
|
||||
**Repository Storage** *(Internal System)*:
|
||||
```
|
||||
/data/repos/ProxySQL-head/
|
||||
├── binaries-{VERSION}/
|
||||
│ ├── centos9/
|
||||
│ ├── debian12/
|
||||
│ ├── ubuntu22/
|
||||
│ └── ...
|
||||
└── archive/
|
||||
└── old-versions/
|
||||
```
|
||||
|
||||
## Docker Image Release
|
||||
|
||||
### Container Build Pipeline
|
||||
|
||||
```dockerfile
|
||||
# Production Dockerfile
|
||||
FROM alpine:latest
|
||||
COPY proxysql /usr/bin/
|
||||
EXPOSE 6033 6032 6080
|
||||
ENTRYPOINT ["proxysql", "-f", "-D", "/var/lib/proxysql"]
|
||||
```
|
||||
|
||||
### Docker Hub Publishing
|
||||
|
||||
```bash
|
||||
# Build and tag images
|
||||
docker build -t proxysql/proxysql:latest .
|
||||
docker tag proxysql/proxysql:latest proxysql/proxysql:2.7.0
|
||||
docker tag proxysql/proxysql:latest proxysql/proxysql:2.7
|
||||
|
||||
# Multi-architecture manifest
|
||||
docker manifest create proxysql/proxysql:2.7.0 \
|
||||
proxysql/proxysql:2.7.0-amd64 \
|
||||
proxysql/proxysql:2.7.0-arm64
|
||||
|
||||
# Push to Docker Hub
|
||||
docker push proxysql/proxysql:2.7.0
|
||||
docker manifest push proxysql/proxysql:2.7.0
|
||||
```
|
||||
|
||||
## Release Automation
|
||||
|
||||
### CI/CD Trigger Configuration
|
||||
|
||||
```yaml
|
||||
# Automatic release on tag
|
||||
on:
|
||||
push:
|
||||
tags:
|
||||
- 'v*.*.*'
|
||||
branches:
|
||||
- 'v[0-9].[0-9x]+.?[0-9xy]?[0-9]?'
|
||||
|
||||
# Manual release trigger
|
||||
on:
|
||||
workflow_dispatch:
|
||||
inputs:
|
||||
version:
|
||||
description: 'Version to release'
|
||||
required: true
|
||||
release_type:
|
||||
description: 'Release type'
|
||||
type: choice
|
||||
options:
|
||||
- production
|
||||
- candidate
|
||||
- snapshot
|
||||
```
|
||||
|
||||
### Release Workflow Stages
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
subgraph "Pre-Release"
|
||||
FREEZE[Code Freeze]
|
||||
TEST[Final Testing]
|
||||
APPROVE[Release Approval]
|
||||
end
|
||||
|
||||
subgraph "Release"
|
||||
TAG[Create Tag]
|
||||
BUILD[Build Packages]
|
||||
PUBLISH[Publish Assets]
|
||||
end
|
||||
|
||||
subgraph "Post-Release"
|
||||
ANNOUNCE[Announcement]
|
||||
DOCS[Update Docs]
|
||||
MONITOR[Monitor Issues]
|
||||
end
|
||||
|
||||
FREEZE --> TEST
|
||||
TEST --> APPROVE
|
||||
APPROVE --> TAG
|
||||
TAG --> BUILD
|
||||
BUILD --> PUBLISH
|
||||
PUBLISH --> ANNOUNCE
|
||||
ANNOUNCE --> DOCS
|
||||
DOCS --> MONITOR
|
||||
```
|
||||
|
||||
## Release Notes Generation
|
||||
|
||||
### Automated Changelog
|
||||
|
||||
```bash
|
||||
# Generate changelog from commits
|
||||
git log v2.6.0..v2.7.0 --pretty=format:"* %s (%an)" \
|
||||
--grep="^feat\|^fix\|^perf" > CHANGELOG.md
|
||||
|
||||
# Categories:
|
||||
# feat: New features
|
||||
# fix: Bug fixes
|
||||
# perf: Performance improvements
|
||||
# docs: Documentation updates
|
||||
# test: Test additions
|
||||
```
|
||||
|
||||
### Release Note Template
|
||||
|
||||
```markdown
|
||||
# ProxySQL v2.7.0 Release Notes
|
||||
|
||||
## Highlights
|
||||
- Major feature additions
|
||||
- Performance improvements
|
||||
- Security enhancements
|
||||
|
||||
## New Features
|
||||
- Feature 1: Description
|
||||
- Feature 2: Description
|
||||
|
||||
## Bug Fixes
|
||||
- Fix 1: Issue #XXX - Description
|
||||
- Fix 2: Issue #YYY - Description
|
||||
|
||||
## Breaking Changes
|
||||
- Change 1: Migration required
|
||||
|
||||
## Deprecations
|
||||
- Deprecated feature 1
|
||||
|
||||
## Contributors
|
||||
- List of contributors
|
||||
|
||||
## Downloads
|
||||
- [CentOS/RHEL packages](link)
|
||||
- [Debian/Ubuntu packages](link)
|
||||
- [Docker images](link)
|
||||
```
|
||||
|
||||
## Distribution Channels
|
||||
|
||||
### Package Repositories
|
||||
|
||||
**RPM Repositories** *(Future Enhancement)*:
|
||||
```bash
|
||||
# YUM repository configuration
|
||||
[proxysql]
|
||||
name=ProxySQL Repository
|
||||
baseurl=https://repo.proxysql.com/centos/$releasever/
|
||||
gpgcheck=1
|
||||
gpgkey=https://repo.proxysql.com/RPM-GPG-KEY-proxysql
|
||||
```
|
||||
|
||||
**APT Repositories** *(Future Enhancement)*:
|
||||
```bash
|
||||
# APT repository configuration
|
||||
deb https://repo.proxysql.com/debian/ $(lsb_release -cs) main
|
||||
```
|
||||
|
||||
### Direct Downloads
|
||||
|
||||
- **GitHub Releases**: Primary distribution channel
|
||||
- **ProxySQL Website**: Mirror of GitHub releases
|
||||
- **Docker Hub**: Container images
|
||||
|
||||
## Monitoring and Metrics
|
||||
|
||||
### Release Metrics
|
||||
|
||||
| Metric | Target | Measurement | Tool |
|
||||
|--------|--------|-------------|------|
|
||||
| Build Success Rate | >95% | Successful builds/Total | GitHub Actions |
|
||||
| Package Test Pass Rate | 100% | Passed tests/Total | Jenkins *(Internal)* |
|
||||
| Release Cycle Time | <2 hours | Tag to publish | CI/CD Pipeline |
|
||||
| Download Count | Tracked | Downloads per release | GitHub API |
|
||||
| Issue Report Rate | <5/release | Issues per release | GitHub Issues |
|
||||
|
||||
### Release Health Dashboard
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "Release Health Indicators"
|
||||
DOWNLOAD[Download Metrics<br/>GitHub/Docker]
|
||||
ISSUES[Issue Reports<br/>Bug Tracking]
|
||||
CRASH[Crash Reports<br/>Core Dumps]
|
||||
PERF[Performance<br/>Benchmarks]
|
||||
end
|
||||
|
||||
subgraph "Actions"
|
||||
HOTFIX[Hotfix Release]
|
||||
PATCH[Patch Release]
|
||||
ROLLBACK[Version Rollback]
|
||||
end
|
||||
|
||||
ISSUES --> HOTFIX
|
||||
CRASH --> HOTFIX
|
||||
PERF --> PATCH
|
||||
|
||||
style DOWNLOAD fill:#bfb
|
||||
style ISSUES fill:#ffb
|
||||
style CRASH fill:#fbb
|
||||
```
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### Package Signing *(Future Enhancement)*
|
||||
|
||||
```bash
|
||||
# GPG signing for RPM
|
||||
rpmsign --addsign proxysql-2.7.0-1.x86_64.rpm
|
||||
|
||||
# GPG signing for DEB
|
||||
dpkg-sig --sign builder proxysql_2.7.0-1_amd64.deb
|
||||
|
||||
# Checksum generation
|
||||
sha256sum proxysql-* > SHA256SUMS
|
||||
gpg --armor --detach-sign SHA256SUMS
|
||||
```
|
||||
|
||||
### Vulnerability Scanning
|
||||
|
||||
- **Container scanning**: Trivy, Snyk integration
|
||||
- **Dependency scanning**: GitHub Dependabot
|
||||
- **Binary scanning**: Static analysis tools
|
||||
|
||||
## Rollback Procedures
|
||||
|
||||
### Version Rollback Strategy
|
||||
|
||||
```bash
|
||||
# Package rollback (RPM)
|
||||
yum downgrade proxysql-2.6.0
|
||||
|
||||
# Package rollback (DEB)
|
||||
apt-get install proxysql=2.6.0
|
||||
|
||||
# Docker rollback
|
||||
docker pull proxysql/proxysql:2.6.0
|
||||
docker stop proxysql && docker rm proxysql
|
||||
docker run -d --name proxysql proxysql/proxysql:2.6.0
|
||||
```
|
||||
|
||||
### Emergency Response
|
||||
|
||||
1. **Issue Detection**: Monitor crash reports and issues
|
||||
2. **Impact Assessment**: Evaluate severity and scope
|
||||
3. **Rollback Decision**: Determine if rollback needed
|
||||
4. **Communication**: Notify users of issues
|
||||
5. **Hotfix Release**: Expedited patch release
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Release Checklist
|
||||
|
||||
- [ ] All tests passing in CI/CD
|
||||
- [ ] Version number updated
|
||||
- [ ] Changelog updated
|
||||
- [ ] Documentation updated
|
||||
- [ ] Release notes prepared
|
||||
- [ ] Package tests completed
|
||||
- [ ] Security scan completed
|
||||
- [ ] Performance benchmarks verified
|
||||
- [ ] Rollback plan documented
|
||||
- [ ] Communication plan ready
|
||||
|
||||
### Release Cadence
|
||||
|
||||
| Release Type | Frequency | Lead Time | Testing Period |
|
||||
|--------------|-----------|-----------|----------------|
|
||||
| Major (x.0.0) | 6-12 months | 4 weeks | 2 weeks |
|
||||
| Minor (x.y.0) | 2-3 months | 2 weeks | 1 week |
|
||||
| Patch (x.y.z) | As needed | 1 week | 3 days |
|
||||
| Hotfix | Emergency | Immediate | Minimal |
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
1. **GPG Signing**: Implement package signing for security
|
||||
2. **Repository Hosting**: Official APT/YUM repositories
|
||||
3. **Automated Rollback**: Automatic rollback on critical issues
|
||||
4. **A/B Testing**: Gradual rollout with metrics
|
||||
5. **Release Analytics**: Detailed usage and adoption metrics
|
||||
6. **CD Pipeline**: Continuous deployment for development builds
|
||||
7. **Multi-Cloud Distribution**: CDN for global distribution
|
||||
|
||||
---
|
||||
|
||||
*This document represents the current state of ProxySQL's release pipeline. For the latest updates, refer to the GitHub Actions workflows and Jenkins build scripts *(Internal System)* in the repository.*
|
||||
Loading…
Reference in new issue