If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/MyCATApache/Mycat-Server shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Stale — last commit 2y ago

• 10 active contributors
• GPL-2.0 licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 2y ago
• ⚠ Concentrated ownership — top contributor handles 63% of recent commits
• ⚠ GPL-2.0 is copyleft — check downstream compatibility

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live MyCATApache/Mycat-Server repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/MyCATApache/Mycat-Server.

What it runs against: a local clone of MyCATApache/Mycat-Server — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in MyCATApache/Mycat-Server | Confirms the artifact applies here, not a fork | | 2 | License is still GPL-2.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 874 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of MyCATApache/Mycat-Server. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/MyCATApache/Mycat-Server.git
#   cd Mycat-Server
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of MyCATApache/Mycat-Server and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "MyCATApache/Mycat-Server(\\.git)?\\b" \\
  && ok "origin remote is MyCATApache/Mycat-Server" \\
  || miss "origin remote is not MyCATApache/Mycat-Server (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(GPL-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"GPL-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is GPL-2.0" \\
  || miss "license drift — was GPL-2.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "src/main/java/io/mycat/MycatServer.java" \\
  && ok "src/main/java/io/mycat/MycatServer.java" \\
  || miss "missing critical file: src/main/java/io/mycat/MycatServer.java"
test -f "src/main/java/io/mycat/backend/datasource/PhysicalDBPool.java" \\
  && ok "src/main/java/io/mycat/backend/datasource/PhysicalDBPool.java" \\
  || miss "missing critical file: src/main/java/io/mycat/backend/datasource/PhysicalDBPool.java"
test -f "src/main/java/io/mycat/backend/datasource/PhysicalDBNode.java" \\
  && ok "src/main/java/io/mycat/backend/datasource/PhysicalDBNode.java" \\
  || miss "missing critical file: src/main/java/io/mycat/backend/datasource/PhysicalDBNode.java"
test -f "src/main/java/io/mycat/backend/BackendConnection.java" \\
  && ok "src/main/java/io/mycat/backend/BackendConnection.java" \\
  || miss "missing critical file: src/main/java/io/mycat/backend/BackendConnection.java"
test -f "src/main/java/io/mycat/backend/heartbeat/DBHeartbeat.java" \\
  && ok "src/main/java/io/mycat/backend/heartbeat/DBHeartbeat.java" \\
  || miss "missing critical file: src/main/java/io/mycat/backend/heartbeat/DBHeartbeat.java"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 874 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~844d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/MyCATApache/Mycat-Server"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

MyCAT is a MySQL middleware and database proxy that enables horizontal sharding, clustering, and high-availability for relational databases. It intercepts SQL traffic, routes queries across partitioned backend databases, and provides distributed transaction support—allowing enterprises to scale single-node MySQL deployments into distributed clusters without application code changes. Monolithic JAR structure rooted at src/main/java/io/mycat/ containing MycatServer.java (entry point), backend/ (database connection pooling), and sharding logic. Assembly packages (src/main/assembly/) define platform-specific distributions (Linux, Windows, macOS). Configuration lives in conf/ (log4j2.xml, dnindex.properties). Startup via MycatStartup.java; shutdown via MycatShutdown.java.

Database administrators and Java backend engineers maintaining high-volume MySQL deployments (millions of rows, multi-shard architectures) who need transparent sharding, read-write splitting, and cross-shard query aggregation without rewriting applications. Contributors are typically maintainers from the Chinese open-source community (see QQ contact in README).

Actively maintained but with known limitations: v1.6.7.6 is the latest release; the project has GitHub stars and active issue templates; CI runs via Travis CI (.travis.yml present). However, the README explicitly warns that batch inserts, multi-statement SQL, and off-heap merging are buggy and should be avoided—suggesting production-grade sharding works but edge cases remain rough. Production-ready for standard sharding scenarios, but not bleeding-edge stable.

Breaking changes introduced in v1.675+ (PartitionByLong sharding algorithm incompatibility documented in README makes old data unreadable). Dependency risks: fastjson and Druid versions require manual updates (separate druid branch maintained at 1.6.6-druid). Single-language codebase (99.5% Java) means Java expertise is mandatory; no polyglot team support. Large monolith (~5MB Java code) with frontend build artifacts (HTML/CSS/JS) embedded, making refactoring risky.

Recent work includes Druid connection pool upgrades (1.1.10 tracked in separate branch), global sequence number generation improvements (documented syntax for MYCATSEQ_GLOBAL), and PartitionByLong hash balancing fixes. No active PRs visible in file structure; contributions welcome via GitHub/Gitee with issue-driven development model (see .github/ISSUE_TEMPLATE/).

Clone the repo: git clone https://github.com/MyCATApache/Mycat-Server.git && cd Mycat-Server. Build with Maven: mvn clean package -DskipTests. Distribution artifacts appear in target/ after assembly. Start server: ./src/main/assembly/bin/startup_nowrap.sh (Linux) or .bat equivalent (Windows). See README_Chinese.md for detailed setup.

Daily commands: After build: bin/startup_nowrap.sh on Unix-like systems (see src/main/assembly/bin/). For Docker: docker build -t mycat . && docker run -p 8066:8066 mycat (Dockerfile provided). Startup waits for Zookeeper initialization (src/main/assembly/bin/init_zk_data.sh) if HA is enabled. Default listening port: 8066 (MySQL protocol).

• src/main/java/io/mycat/MycatServer.java — Main server entry point and lifecycle management — essential to understand how Mycat initializes, starts, and coordinates all subsystems.
• src/main/java/io/mycat/backend/datasource/PhysicalDBPool.java — Core connection pooling and physical database management — foundational for backend connection lifecycle and resource allocation.
• src/main/java/io/mycat/backend/datasource/PhysicalDBNode.java — Logical-to-physical database node mapping — critical for routing queries to correct backend datasources.
• src/main/java/io/mycat/backend/BackendConnection.java — Backend connection abstraction layer — implements protocol handling and connection state management for MySQL connections.
• src/main/java/io/mycat/backend/heartbeat/DBHeartbeat.java — Database health checking and failover detection — ensures connection availability and triggers failover logic.
• pom.xml — Maven build configuration with all dependencies — required to understand build toolchain, versions, and project structure.
• src/main/assembly/conf/log4j2.xml — Logging configuration — critical for debugging and monitoring production deployments.

Add a New Load Balancing Strategy

1. Create a new class extending LoadBalance interface in backend/loadbalance/ (src/main/java/io/mycat/backend/loadbalance/LoadBalance.java)
2. Implement the select() method to return a PhysicalDatasource based on your strategy (src/main/java/io/mycat/backend/loadbalance/YourStrategyLoadBalance.java)
3. Register the new strategy in PhysicalDBPool or datasource configuration logic (src/main/java/io/mycat/backend/datasource/PhysicalDBPool.java)

Add a New Backend Database Type (e.g., PostgreSQL)

1. Create a new connection class extending BackendConnection in backend/ (src/main/java/io/mycat/backend/BackendConnection.java)
2. Implement protocol-specific methods (authenticate, sendQuery, readResponse, close) (src/main/java/io/mycat/backend/YourDatabaseConnection.java)
3. Create a heartbeat detector class (similar to MySQLDetector) for health checks (src/main/java/io/mycat/backend/heartbeat/MySQLDetector.java)
4. Register the new datasource type in PhysicalDatasource factory logic (src/main/java/io/mycat/backend/datasource/PhysicalDatasource.java)

Add Custom Health Check or Consistency Verification

1. Extend DBHeartbeat or create a new monitor class in backend/heartbeat/ (src/main/java/io/mycat/backend/heartbeat/DBHeartbeat.java)
2. Implement heartbeat logic (connection test, timeout handling, status updates) (src/main/java/io/mycat/backend/heartbeat/MySQLHeartbeat.java)
3. Integrate with PhysicalDBNode or PhysicalDBPool to trigger on interval (src/main/java/io/mycat/backend/datasource/PhysicalDBNode.java)
4. Configure heartbeat interval and failure thresholds in datasource config (src/main/assembly/conf/log4j2.xml)

Integrate a New NoSQL Database via JDBC Bridge

1. Create a new JDBC driver wrapper (similar to MongoDriver) in backend/jdbc/yourdb/ (src/main/java/io/mycat/backend/jdbc/mongodb/MongoDriver.java)
2. Implement Connection, Statement, and ResultSet classes wrapping your JDBC API (src/main/java/io/mycat/backend/jdbc/mongodb/MongoConnection.java)
3. Register the driver in JDBCDatasource or datasource factory (src/main/java/io/mycat/backend/jdbc/JDBCDatasource.java)
4. Configure datasource URL and pool settings in server startup (src/main/java/io/mycat/MycatServer.java)

• Java NIO (Netty implied from connection handling) — Enables high-concurrency request multiplexing without one-thread-per-connection overhead
• MySQL wire protocol implementation — Allows Mycat to act as a transparent MySQL proxy and accept standard MySQL clients
• ZooKeeper integration (zkprocess package) — Provides distributed consensus for leader election and failover decision coordination in multi-node Mycat clusters
• JDBC abstraction layer — undefined

1. PartitionByLong hash algorithm changed in v1.675+—existing sharded data becomes invisible on upgrade without manual migration using provided dataMigrate.sh. 2) MyCAT1.6 forbids multiple SQL statements in single query (documented limitation)—parsing fails silently if app sends batched statements. 3) Zookeeper must be running if cluster mode is enabled; init_zk_data.sh must execute before startup or server hangs. 4) Fastjson version mismatches cause deserialization failures on complex types; manually update pom.xml if upgrading. 5) Global sequence generation (MYCATSEQ_GLOBAL syntax) requires separate configuration step; missing config causes INSERT failures. 6) Off-heap memory merging and batch inserts are explicitly broken per README—avoid these features entirely.

• Database Sharding / Horizontal Partitioning — MyCAT's core function is transparent sharding—distributing rows across multiple backend databases by shard key; understanding hash-based vs range-based partitioning (PartitionByLong strategy) is essential to diagnose query routing bugs
• Consistent Hashing / Hash Ring — PartitionByLong algorithm uses hash-based shard selection; the v1.675 breaking change involved rebalancing this hash space, making data migration necessary—understanding hash collision and ring rebalancing helps debug data loss
• MySQL Protocol Proxy / Middleware Pattern — MyCAT implements a transparent MySQL wire protocol proxy—clients connect via standard MySQL drivers unaware they're hitting a middleware that parses, routes, and aggregates queries across shards
• Connection Pooling — MyCAT maintains Druid-based connection pools per backend shard; pool saturation, stale connections, and timeout misconfig cause widespread query hangs—critical for production stability
• Distributed Transaction / 2-Phase Commit — MyCAT claims ACID support across shards (documented in README); understanding its 2PC limitations and when transactions fail across shard boundaries is critical for application design
• Global Sequence Generation — MyCAT provides distributed primary key generation via MYCATSEQ_GLOBAL syntax (unique across all shards); requires separate cluster-wide state, distinct from per-shard auto_increment
• Query Result Aggregation / Merge Sort — Cross-shard SELECT queries must aggregate and merge results from multiple backends; off-heap merging is explicitly broken per README, forcing in-memory aggregation which impacts latency and memory use

• alibaba/cobar — Predecessor to MyCAT; Alibaba's original MySQL sharding proxy that inspired MyCAT's architecture
• sharding-sphere/sharding-sphere — Modern alternative for database sharding and middleware; Java-based with more active development and support for newer MySQL versions
• vitessio/vitess — Cloud-native MySQL middleware written in Go; solves same sharding/clustering problems at scale with production battle-testing at YouTube
• MyCATApache/Mycat-doc — Official documentation repo for MyCAT; contains guides, API docs, and architecture references for operators and developers

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add unit tests for backend heartbeat and consistency checking logic

The heartbeat module (src/main/java/io/mycat/backend/heartbeat/) contains critical database connectivity and consistency checking logic but likely lacks comprehensive test coverage. This includes DBHeartbeat.java, MySQLDetector.java, and MySQLConsistencyChecker.java which are essential for production reliability. Adding unit tests would catch regressions and improve confidence in failover behavior.

• [ ] Create src/test/java/io/mycat/backend/heartbeat/ directory structure
• [ ] Add unit tests for MySQLHeartbeat.java covering connection health detection scenarios
• [ ] Add unit tests for MySQLConsistencyChecker.java covering data consistency validation edge cases
• [ ] Add integration tests for DBHeartbeat.java with mock backend connections
• [ ] Ensure tests cover failure scenarios and recovery paths

Create GitHub Actions CI/CD pipeline to replace .travis.yml

The repo has an outdated .travis.yml configuration but no GitHub Actions workflows. GitHub Actions is now the standard for GitHub repos and would provide better integration, faster builds, and clearer CI status. This should include build verification, basic tests, and potentially Docker image builds given the Dockerfile presence.

• [ ] Create .github/workflows/build.yml for Maven compilation and unit tests on push/PR
• [ ] Create .github/workflows/docker-build.yml for validating Dockerfile builds
• [ ] Add workflow status badges to README.md and README_Chinese.md
• [ ] Consider adding a .github/workflows/release.yml for automated artifact packaging using the assembly configs
• [ ] Document CI requirements in CONTRIBUTING.md

Add comprehensive integration tests for connection pooling and data source management

The datasource module (src/main/java/io/mycat/backend/datasource/) contains PhysicalDBPool.java, PhysicalDBNode.java, and PhysicalDatasource.java which manage critical connection pooling behavior. Without integration tests, connection lifecycle, pool exhaustion, and recovery scenarios are untested, creating production risk.

• [ ] Create src/test/java/io/mycat/backend/datasource/ with embedded database test fixtures
• [ ] Add integration tests for PhysicalDBPool.java covering connection acquisition/release cycles
• [ ] Add tests for PhysicalDatasource.java covering connection validation and timeout scenarios
• [ ] Add tests for ConQueue.java and ConMap.java covering concurrent access patterns
• [ ] Add stress tests verifying pool recovery after connection failures

• Add unit tests for PartitionByLong sharding algorithm in src/main/java/io/mycat/ (currently none visible); create test cases for hash collision handling and data distribution verification to prevent future regressions like the v1.675 incident.
• Document the exact configuration steps for global sequence numbers (MYCATSEQ_GLOBAL) in conf/dnindex.properties with a worked example; currently only SQL syntax is shown in README, but conf setup is missing.
• Create a migration guide in docs/ explaining how to safely upgrade from <v1.675 to >=v1.675 when using PartitionByLong, including dataMigrate.sh usage and validation queries—this is a known breaking change with no clear upgrade path.

• High · Insecure Docker Base Image and Outdated Dependencies — Dockerfile. The Dockerfile uses 'adoptopenjdk/openjdk8:latest' without version pinning. OpenJDK 8 reached end-of-life in December 2030 but the 'latest' tag could pull vulnerable versions. Additionally, the project version is 1.6.7.6-release (released around 2018-2019), indicating use of significantly outdated dependencies with known vulnerabilities. Fix: Pin the Docker base image to a specific version (e.g., 'adoptopenjdk/openjdk8:8u372-b07'), upgrade to Java 11 or 17 LTS, and update all Maven dependencies to their latest secure versions.
• High · Insecure HTTP URL for Artifact Download — Dockerfile, line: ADD http://dl.mycat.io/.... The Dockerfile downloads a tar.gz file from 'http://dl.mycat.io' using an unencrypted HTTP connection. This is vulnerable to man-in-the-middle attacks where the artifact could be intercepted and replaced with malicious code. Fix: Use HTTPS instead of HTTP for artifact downloads (if available). Alternatively, use package managers with checksum verification, or copy pre-built artifacts into the image during build time.
• High · Missing POM.xml Dependency Information — pom.xml. The pom.xml file provided is truncated and incomplete. Critical information about dependency versions is missing, making it impossible to assess the full vulnerability landscape. Multiple modules reference MongoDB driver, JDBC connectors, and other third-party libraries without visible version constraints. Fix: Provide complete pom.xml with explicit version numbers for all dependencies. Run 'mvn dependency:tree' and 'mvn org.apache.maven.plugins:maven-dependency-plugin:3.2.0:tree' to identify outdated packages. Use Maven Enforcer Plugin to enforce minimum versions.
• High · Exposed Database Ports in Docker — Dockerfile, EXPOSE statement. The Dockerfile exposes ports 8066 and 9066 without any documented security controls. These ports serve as the primary entry points for a database proxy without TLS/SSL enforcement visible in the configuration. Fix: Implement TLS/SSL for all exposed ports. Use network segmentation and firewall rules to restrict access. Document security requirements. Consider using secrets management for credentials.
• Medium · Potential SQL Injection in SQL Parsing Components — src/main/java/io/mycat/backend/jdbc/mongodb/MongoSQLParser.java and related SQL execution paths. The codebase contains multiple SQL parsing and execution components (backend, jdbc, mongodb drivers) that handle raw SQL queries. Without visible parameterized query enforcement or input validation, there is risk of SQL injection attacks, particularly in the MongoDB SQL parser and JDBC connection handlers. Fix: Enforce parameterized queries (PreparedStatements) throughout. Implement input validation and sanitization. Use ORM frameworks or query builders that prevent SQL injection. Add comprehensive unit tests for SQL injection scenarios.
• Medium · Insecure Configuration File Handling — src/main/assembly/conf/ directory and Dockerfile VOLUME declarations. Configuration files in 'conf/' directory (dnindex.properties, log4j2.xml) may contain sensitive information. The Dockerfile declares these as VOLUME mounts without documented encryption or access control. No evidence of configuration encryption or secrets management system. Fix: Implement secrets management (HashiCorp Vault, AWS Secrets Manager, Kubernetes Secrets). Encrypt configuration files at rest. Use environment variables for sensitive data. Implement proper file permissions (chmod 600) on configuration files.
• Medium · Unencrypted Inter-Node Communication — src/main/java/io/mycat/backend/heartbeat/DBHeartbeat.java and zkprocess/ components. The Mycat server appears to be a distributed database proxy with heartbeat and ZooKeeper integration. No visible TLS/SSL configuration for backend database connections or inter-node communication in the heartbeat and ZK process handlers. Fix: Implement TLS/SSL for all database backend connections. Secure ZooKeeper connections with authentication and encryption. Use certificate pinning for critical connections.
• Medium · Missing Authentication/Authorization Framework — undefined. undefined Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.