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/flike/kingshard 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 — Missing license — unclear to depend on

• Last commit 5w ago
• 27+ active contributors
• Distributed ownership (top contributor 45% of recent commits)
• CI configured
• ⚠ No license — legally unclear to depend on
• ⚠ No test directory detected

_{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 flike/kingshard repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/flike/kingshard.

What it runs against: a local clone of flike/kingshard — 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 flike/kingshard | Confirms the artifact applies here, not a fork | | 2 | Default branch master exists | Catches branch renames | | 3 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 4 | Last commit ≤ 67 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of flike/kingshard. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/flike/kingshard.git
#   cd kingshard
#
# 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 flike/kingshard and re-run."
  exit 2
fi

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

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

# 4. Critical files exist
test -f "cmd/kingshard/main.go" \\
  && ok "cmd/kingshard/main.go" \\
  || miss "missing critical file: cmd/kingshard/main.go"
test -f "proxy/server/conn.go" \\
  && ok "proxy/server/conn.go" \\
  || miss "missing critical file: proxy/server/conn.go"
test -f "proxy/router/router.go" \\
  && ok "proxy/router/router.go" \\
  || miss "missing critical file: proxy/router/router.go"
test -f "backend/node.go" \\
  && ok "backend/node.go" \\
  || miss "missing critical file: backend/node.go"
test -f "config/config.go" \\
  && ok "config/config.go" \\
  || miss "missing critical file: config/config.go"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 67 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~37d)"
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/flike/kingshard"
  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).

kingshard is a high-performance MySQL proxy written in Go that intercepts client connections and routes SQL queries to sharded backend MySQL instances. It provides read/write splitting, hash/range/date-based sharding across multiple nodes, and connection pooling — achieving ~80% throughput of direct MySQL connections while enabling transparent horizontal scaling. Monolithic structure with layered architecture: cmd/kingshard/main.go is the entry point; config/ handles YAML parsing (etc/ks.yaml); backend/ contains connection pooling (backend_conn.go), node management (node.go), and statement handling (stmt.go); core/ provides error handling and logging; Yacc-based SQL parser sits alongside the main flow. No separation into packages beyond directory grouping.

DevOps engineers and backend architects deploying large-scale MySQL systems who need to shard data across multiple database nodes without rewriting application code; teams managing multi-tenant or time-series databases that require horizontal scaling at the proxy layer.

Actively maintained but niche: the project has comprehensive documentation (doc/KingDoc/), test coverage for core modules (backend/*_test.go, config/config_test.go), and Travis CI integration (.travis.yml), but the last visible activity and commit patterns suggest slower development velocity than major forks like vitess. Suitable for production if your sharding strategy matches its model (hash/range/date), but not as battle-tested as MySQL Router or ProxySQL.

Minimal dependencies (only gopkg.in/yaml.v2, labstack/echo, prometheus/client_golang) reduces supply-chain risk. Single-maintainer concern (flike organization) means no visible secondary maintainers. Yacc grammar parser (21KB) for SQL parsing is a custom implementation — potential for edge-case SQL parsing bugs. No visible issue tracker or PR activity in provided data limits transparency on active problems.

Based on file structure alone, no active PR or issue data visible. The mature state of documentation and test files suggests the project is in maintenance mode rather than active feature development. Last confirmed build via .travis.yml integration.

git clone https://github.com/flike/kingshard.git $GOPATH/src/github.com/flike/kingshard
cd $GOPATH/src/github.com/flike/kingshard
source ./dev.sh
make
./bin/kingshard -config=etc/ks.yaml

Daily commands:

make                           # Compiles to ./bin/kingshard
./bin/kingshard -config=etc/ks.yaml  # Starts proxy listening for client connections

• cmd/kingshard/main.go — Entry point that initializes the proxy server, loads configuration, and starts accepting client connections
• proxy/server/conn.go — Core connection handler managing client-proxy protocol negotiation and query routing to backend MySQL nodes
• proxy/router/router.go — SQL routing engine that determines which backend node(s) receive each query based on sharding rules
• backend/node.go — Backend MySQL node abstraction managing connection pools and failover logic
• config/config.go — Configuration loader parsing YAML files defining sharding schemes, node addresses, and proxy rules
• mysql/packetio.go — Low-level MySQL protocol packet serialization/deserialization critical for client-server communication

• Client Connection Handler (conn.go) (Go net/conn, MySQL protocol parser) — Authenticates clients, parses MySQL protocol, routes queries, formats responses
  • Failure mode: Client connection drops; queries in-flight are lost; client must reconnect
• Router (router.go) (SQL parser, hash/range sharding logic) — Analyzes SQL, extracts sharding keys, selects target backend nodes, builds execution plans
  • Failure mode: Query routes to wrong shard → incorrect results or errors; application must validate
• Backend Node Manager (node.go) (Go goroutines, connection pooling) — Maintains connection pool, detects node failures, marks nodes online/offline
  • Failure mode: Pool exhaustion → new queries queue/timeout; node failure → queries fail (no auto-failover by default)
• Result Set Aggregator (resultset.go) (In-memory sorting, MySQL packet marshaling) — Merges result sets from multiple shards, sorts if needed, formats MySQL protocol packets
  • Failure mode: Large result sets exhaust memory; slow sort blocks other queries
• Configuration Loader (config.go) (YAML parser, schema validation) — Parses YAML config, validates sharding rules, initializes backend nodes
  • Failure mode: Invalid config → proxy fails to start; no graceful degradation

• MySQL Client → Proxy Server — TCP packets containing MySQL protocol messages (login, queries, prepared statements)
• Proxy Server → Router — Parsed SQL queries with metadata extracted from protocol
• Router → Backend Node Selection — Sharding key and target node list determined by routing rules
• Backend Node Manager → MySQL Server — SQL queries forwarded to backend connections with read/write split applied
• MySQL Server → Result Set Aggregator — Result rows and metadata from one or more backend nodes
• Result Set Aggregator → Proxy Server — Merged and sorted result set ready for client serialization

Add a new sharding rule

1. Define sharding schema in YAML config (etc/ks.yaml), specifying table name, sharding key, and node mapping (etc/ks.yaml)
2. Update config parser to load new shard configuration (config/config.go)
3. Implement shard selection logic in router matching the sharding key extraction pattern (proxy/router/shard.go)
4. Write tests to verify sharding distribution (proxy/router/router_test.go)

Add a new admin command

1. Define command parsing in the admin connection handler (proxy/server/conn_admin.go)
2. Implement command execution logic (node online/offline, config reload, etc.) (proxy/server/conn_admin.go)
3. Format response as MySQL result set (mysql/resultset.go)

Add backend node failover detection

1. Modify backend connection health check logic (backend/backend_conn.go)
2. Update node status management with failure thresholds and recovery (backend/node.go)
3. Update router to skip unhealthy nodes during shard selection (proxy/router/router.go)
4. Add metrics for node health in Prometheus exporter (monitor/prometheus.go)

• Go — High concurrency with goroutines, static compilation for single binary deployment, good MySQL driver ecosystem
• YAML configuration — Human-readable sharding scheme definition without code recompilation
• MySQL protocol (binary safe) — Full compatibility with MySQL clients and connection pooling support
• Prometheus metrics — Standard observability integration for production monitoring and alerting

• In-process routing vs external coordinator

  • Why: Simpler deployment and lower latency for routing decisions
  • Consequence: No distributed coordination; each proxy instance routes independently (suitable for hash-based sharding)

• Synchronous query execution to backends

  • Why: Maintains ACID guarantees per-node and simplifies result aggregation
  • Consequence: Latency scales with slowest backend response; requires separate async queue for bulk operations

• Single proxy instance per connection

  • Why: Simplified connection state management and transaction handling
  • Consequence: Horizontal scaling requires multiple proxy instances with external load balancing (no built-in clustering)

• Distributed transactions across shards (no 2-phase commit)
• Query cache or result caching layer
• Automatic shard rebalancing
• Cross-shard JOINs
• Automatic schema migration
• Built-in HA/clustering (requires external LVS/keepalived)

Configuration file (etc/ks.yaml) must define all backend nodes, sharding rules, and user credentials upfront — no runtime node discovery; if a backend node is added to MySQL, kingshard requires config reload or restart. Prepared statements are stored per-connection, not globally, so statement IDs from one client are invalid on another — clients must re-prepare after reconnection. The custom Yacc SQL parser may not handle all MySQL syntax edge cases (window functions, CTEs, JSON operators) — test your specific SQL patterns. Backend connection pools have configurable max size but no dynamic resizing — undersizing causes queue buildup, oversizing wastes memory.

• MySQL Wire Protocol — kingshard intercepts and re-implements the MySQL client-server protocol; understanding frame types (COM_QUERY, COM_STMT_PREPARE), result set encoding, and error handling is essential for proxy logic and debugging
• Consistent Hashing — Hash-based sharding in kingshard likely uses consistent hashing to distribute keys across nodes and minimize redistribution when nodes are added/removed; understanding rehashing impact is critical for operational planning
• Connection Pooling — backend_conn.go implements a connection pool to amortize TCP handshake cost; misunderstanding pool saturation and idle timeout leads to connection exhaustion or cascading failures
• Read/Write Splitting — kingshard routes SELECT queries to slave replicas and write queries (INSERT, UPDATE, DELETE) to the master; understanding replication lag and consistency guarantees is critical for data correctness
• Yacc (Yet Another Compiler Compiler) — kingshard uses Yacc grammar to parse SQL statements; understanding how grammar rules map to AST nodes and potential parse conflicts helps debug routing failures and extend SQL support
• Sharding Key Selection — kingshard requires explicit sharding key definition in config (hash/range/date on specific columns); poor sharding key choice causes data skew and hot nodes — a domain knowledge problem, not just technical
• Two-Phase Commit (XA Transactions) — kingshard states it supports 'transaction in single node' but cross-shard transactions are not mentioned; understanding XA limitations and when strong consistency fails is crucial for application design

• vitessio/vitess — Industry-standard MySQL sharding and clustering proxy; more mature and feature-rich alternative used at scale by YouTube
• percona/proxysql — General-purpose MySQL proxy with advanced routing, caching, and query rewriting; handles non-sharded use cases better than kingshard
• mysql/mysql-router — Official MySQL proxy for InnoDB Cluster HA; good comparison for reliability and feature parity, though focused on clustering not sharding
• go-sql-driver/mysql — Pure Go MySQL driver that kingshard clients use; understanding the wire protocol it implements is necessary to debug kingshard proxy issues
• pingcap/tidb — Distributed SQL database with integrated proxy and sharding; alternative architecture if moving beyond MySQL sharding to NewSQL

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 integration tests for backend connection pooling and failover scenarios in backend/

The backend/ package contains critical connection management code (backend_conn.go, node.go, balancer.go, db.go) but lacks comprehensive integration tests. Currently only unit tests exist (*_test.go files). Given kingshard is a production MySQL proxy handling connection pools and load balancing across multiple backend nodes, integration tests validating failover behavior, connection exhaustion handling, and rebalancing under failure conditions are essential but missing.

• [ ] Create backend/integration_test.go with test fixtures for multi-node MySQL setups
• [ ] Add test cases for: node failure detection, connection pool exhaustion recovery, balancer rebalancing after node restoration
• [ ] Update Makefile to distinguish between unit tests (make test) and integration tests (make test-integration)
• [ ] Document integration test setup requirements in doc/KingDoc/contribution_guide.md

Implement GitHub Actions CI workflow to replace Travis CI and add Go 1.16+ support validation

The repo uses outdated Travis CI (.travis.yml) and declares Go 1.13 in go.mod. Modern Go versions (1.16+) include significant security and performance improvements. The project lacks validation that it builds and tests against supported Go versions. GitHub Actions would provide faster feedback and better integration with GitHub's native workflows.

• [ ] Create .github/workflows/go-test.yml with matrix testing for Go 1.16, 1.17, 1.18, 1.19, 1.20
• [ ] Include steps: setup-go, go mod download, go test -v ./..., go build ./cmd/kingshard
• [ ] Add go vet and staticcheck linting steps to catch common issues
• [ ] Update README.md to reflect new CI badge from GitHub Actions instead of Travis

Add comprehensive sharding strategy unit tests for core SQL routing logic in sharding/

The doc/KingDoc/ directory contains multiple files describing sharding features (kingshard_sharding_introduce.md, kingshard_date_sharding.md) and the file structure references sharding capabilities, but there is no visible sharding/ package with corresponding tests in the file list. The routing and sharding decision logic is critical to correctness but appears untested. This gap risks silent failures in production sharding decisions.

• [ ] Locate or create the sharding logic package (likely in router/ or sharding/ directory not shown in partial structure)
• [ ] Create comprehensive unit tests for: hash-based routing, date-based routing, range-based routing, and routing fallback logic
• [ ] Add tests validating correct shard selection for edge cases (NULL values, date boundaries, hash collisions)
• [ ] Document sharding routing logic and test coverage in doc/KingDoc/sharding_architecture.md

• Add integration tests for backend/db_test.go and backend/db.go covering database selection, schema changes, and multi-database transactions — the db.go file has no corresponding test file despite _test.go pattern being used elsewhere
• Document sharding strategy selection in doc/KingDoc/ — the readme mentions 'hash, range and date sharding' but doesn't explain when to use each or show config examples for each type; good learning task for a new contributor
• Add Prometheus metrics export for connection pool saturation (active/idle ratio per node) to backend/balancer.go — prometheus/client_golang is already a dependency and metrics are mentioned in docs but not detailed in code

• High · Outdated Go Version in Docker Build — Dockerfile (line 1). The Dockerfile uses golang:1.13.8 which is significantly outdated (released in 2020). This version has known security vulnerabilities and lacks modern security features. Go 1.13 is no longer supported. Fix: Update to a current stable Go version (1.21 or later). Example: 'FROM golang:1.21-alpine as builder'
• High · Outdated Alpine Base Image — Dockerfile (line 7). The Dockerfile uses alpine:3.11.3 (released in 2020) which is outdated and may contain unpatched security vulnerabilities. Current Alpine versions are 3.18+. Fix: Update to a current Alpine version: 'FROM alpine:3.18' or later, ensuring security patches are current
• High · Insecure Dependency: jwt-go (deprecated) — go.mod (github.com/dgrijalva/jwt-go v3.2.0+incompatible). The project depends on github.com/dgrijalva/jwt-go v3.2.0, which is deprecated and no longer maintained. This library has known security vulnerabilities and the maintainer has explicitly marked it as deprecated in favor of github.com/golang-jwt/jwt. Fix: Migrate to github.com/golang-jwt/jwt/v5 which is actively maintained and receives security updates
• High · Insecure Dependency: labstack/echo v3 — go.mod (github.com/labstack/echo v3.3.10+incompatible). The project uses labstack/echo v3.3.10 which is an old major version. Echo v4 introduced significant security improvements and bug fixes. Version 3 is no longer actively maintained. Fix: Upgrade to labstack/echo v4.x (current major version) for security patches and improvements
• Medium · Outdated YAML Parser — go.mod (gopkg.in/yaml.v2 v2.2.5). The gopkg.in/yaml.v2 package is outdated. Version v3 is available with security improvements and better performance. v2 is in maintenance-only mode. Fix: Consider upgrading to gopkg.in/yaml.v3 for improved security and performance, after testing for compatibility
• Medium · Potential SQL Injection Risk in Sharding Logic — backend/backend_conn.go, backend/stmt.go. The codebase implements SQL sharding functionality. Without visible input validation and parameterized query patterns in the file structure, there is risk of SQL injection attacks during query routing and transformation. Fix: Ensure all SQL queries use prepared statements and parameterized queries. Implement strict input validation for sharding keys. Add comprehensive unit tests for SQL injection vectors.
• Medium · Missing Security Headers Configuration — cmd/kingshard/main.go, config/config.go. No visible configuration for security headers (HSTS, CSP, X-Frame-Options, etc.) in the echo server setup. The admin API documentation references kingshard_admin_api.md but security headers are not evident. Fix: Configure security headers in the Echo middleware. Add CORS restrictions, disable X-Frame-Options, implement rate limiting, and add request validation middleware.
• Medium · Hardcoded Configuration File Path — Dockerfile (line 17) and etc/ks.yaml. The Dockerfile hardcodes the configuration path to /etc/kingshard/ks.yaml. If the config file contains credentials or sensitive data, it should be injected via secure environment variables or secrets management. Fix: Use environment variables or container orchestration secrets (Docker Secrets, Kubernetes Secrets) for sensitive configuration. Never hardcode paths or credentials in Dockerfiles.
• Medium · No Apparent Input Validation for ACL Control — core/ (implementation not fully visible). The README mentions 'Client's ip ACL control' but the implementation details are not visible. Weak ACL implementation could allow unauthorized access to the proxy. Fix: Implement strict IP

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.