# He3Proxy

**Repository Path**: he3db/he3proxy

## Basic Information

- **Project Name**: He3Proxy
- **Description**: He3Proxy是中移（苏州）软件技术有限公司基于PG协议专为He3DB打造的高性能数据库代理项目。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: https://gitee.com/he3db/he3proxy
- **GVP Project**: No

## Statistics

- **Stars**: 70
- **Forks**: 16
- **Created**: 2022-08-29
- **Last Updated**: 2024-07-25

## Categories & Tags

**Categories**: database-service

**Tags**: 数据库中间件

## README

[comment]: <> "[![Build Status]&#40;https://travis-ci.org/flike/kingshard.svg?branch=master&#41;]&#40;https://travis-ci.org/flike/kingshard&#41;"
[![LICENSE](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://gitee.com/he3db/he3proxy/blob/master/doc/License)

[comment]: <> "[![Build Status]&#40;https://travis-ci.org/XiaoMi/Gaea.svg?branch=master&#41;]&#40;https://travis-ci.org/XiaoMi/Gaea&#41;"
[![Go Report Card](https://goreportcard.com/badge/gitee.com/he3db/he3proxy)](https://goreportcard.com/report/gitee.com/he3db/he3proxy)

# He3Proxy

## 简介

He3Proxy是中移（苏州）软件技术有限公司基于[PG协议](https://www.postgresql.org/docs/current/protocol.html)
专为[He3DB](https://gitee.com/he3db) 打造的高性能数据库代理项目，采用Go语言开发， He3Proxy为[He3DB](https://gitee.com/he3db) 提供读写分离、负载均衡、连接池管理、
读一致性等基础能力，让用户像使用单机一样使用[He3DB](https://gitee.com/he3db) 集群，并提升集群整体吞吐量、提高节点资源利用率， 同时兼具[He3DB](https://gitee.com/he3db)
集群管理功能，如集群监控、灰度升级、数据分层存储、动态扩缩容等，助力[He3DB](https://gitee.com/he3db) 实现serverless。

同时He3Proxy也兼容其他基于[PG协议](https://www.postgresql.org/docs/current/protocol.html) 的主从架构数据库，可作为其数据库中间件使用。

## 架构图

![架构图](./doc/pic/architecture.png)

## 集群部署图

![集群部署图](./doc/pic/deployment.png)

## 功能介绍

- 支持PG协议连接。
- 支持SQL读写分离。
- 支持连接池管理，可复用已有后端数据库链接，减少建立链接时的性能损耗。
- 支持多个slave，slave之间通过权值进行负载均衡。
- 支持多个slave，slave之间通过节点负载情况进行负载均衡。
- 支持显式事务内先读操作的负载均衡。
- 支持强制读主库。
- 支持所有请求均主库执行。
- 支持配置proxy到后端数据库的最大连接数限制。
- 支持SQL黑名单机制。
- 支持通过配置hba文件，实现数据库安全访问权限控制。
- 支持热加载配置文件，动态修改He3Proxy配置项。
- 支持session读一致性，并根据节点负载情况进行负载均衡。
- 支持客户端链接维度的tracing数据采集（jaeger）。

### 功能演示

![功能演示](./doc/pic/functional_demonstration.gif)

## 安装部署

```
	1. 安装Go语言环境（请使用最新版）
	2. git clone https://gitee.com/he3db/he3proxy.git $GOPATH/src/gitee.com/he3db/he3proxy
	3. cd $GOPATH/src/gitee.com/he3db/he3proxy
	4. source ./dev.sh
	5. make
	6. 设置配置文件
	7. 运行he3proxy
	   ./bin/he3proxy -config=./etc/he3proxy.yaml -hba=./etc/hba.conf -log-level=info
```

**Goland打包Linux二进制文件配置可参考下图**

![Goland打包配置](./doc/pic/goland_pkg.png)

### 配置文件说明

[配置文件说明](./doc/He3Proxy/configure_description.md)

### 启动参数说明

```
postgres@he3db:~/he3proxy$ ./bin/he3proxy -h
    __  __    _____       ____
   / / / /__ |__  /      / __ \_________  _  ____  __
  / /_/ / _ \ /_ <______/ /_/ / ___/ __ \| |/_/ / / /
 / __  /  __/__/ /_____/ ____/ /  / /_/ />  </ /_/ /
/_/ /_/\___/____/     /_/   /_/   \____/_/|_|\__, /
                                            /____/
Usage of ./he3proxy:
  -cancel-request [启用后支持ctrl+c终止异常链接，默认false]
        the flag of save connection id and secret for cancel request
  -config string [He3Proxy配置文件路径]
        He3Proxy config file (default "./etc/he3proxy.yaml")
  -conn-pool [是否使用连接池，默认 true]
        the switch of connection pool, if true means use backend connection pool (default true)
  -cpu-profile [是否使用连接池，默认 true]
        analysis cpu profile
  -db-mode string [后端数据库类型，保留kingshard的MySQL数据库链接功能，默认 postgresql]
        switch proxy work mode [mysql|postgresql], default postgresql (default "postgresql")
  -hba string [He3Proxy hba 配置文件路径]
        He3Proxy hba config file (default "./etc/hba.conf")
  -he3proxy [He3Proxy中间件标识，若使用读一致性功能，需要开启此配置，默认 false]
        the flag of he3proxy, if true means tell backend current connection is by he3proxy
  -keep-conn [始终使用当前链接处理，适用于高性能读需求，读写混和场景不适用，默认 false]
        keep use current conn, and not release util conn release
  -log-level string [日志级别设置]
        log level [debug|info|warn|error], default set by configuration
  -max-cpu int [程序最大使用cpu数]
        the GO MAX PROCS, default sys logical cpu nums
  -metrics [是否开启prometheus采集指标，默认 false]
        the flag of collection metrics, if true means work with prometheus
  -opentracing [是否开启opentracing指标采集，默认 false]
        switch of opentracing
  -pprof [debug使用，用于开启pprof，默认 false]
        the switch of pprof
  -pyroscope [debug使用，是否开启pyroscope监控，默认false]
        the switch of pyroscope
  -readonly [高性能读场景使用，读写场景不适用，默认 false]
        improve read performance by not release conn
  -server-version string [设置后端数据库版本]
        set backend server version for pg, default 14.2 (default "14.2")
  -simple-parse [解析器使用选择，true使用CRDB的语法书解析（读一致性功能必须设置为true），false使用简单分词，默认true]
        the flag of use simple parse (lex), if false means will use crdb parse (AST) (default true)
  -single-session [单链接模式，不使用负载均衡，默认 false]
        the switch of single session, if true means proxy work without loadbalance
  -tracer-provider-url string [设置jaeger指标采集地址，opentracing为true时此参数有效]
        jaeger collector url (default "http://localhost:14268/api/traces")
  -v    the version of He3Proxy [输出He3Proxy版本信息]
```

## 鸣谢

* 感谢[kingshard](https://github.com/flike/kingshard) 作者Fei Chen，He3Proxy以kingshard作为基础框架，在其之上进行定制化改造开发。
* 感谢[CockroachDB](https://github.com/cockroachdb/cockroach) 团队及[postgresql-parser](github.com/auxten/postgresql-parser)
  的作者auxten， He3Proxy在SQL解析层参考使用了项目postgresql-parser，在hba登录鉴权管理等方面参考了CockroachDB的实现。
* 感谢[TiDB for PostgreSQL](https://github.com/DigitalChinaOpenSource/TiDB-for-PostgreSQL)
  作者神州数码团队，He3Proxy在前后端握手、协议处理方面参考了TiDB for PostgreSQL的实现。
* 感谢PG Go语言驱动[pgx](https://github.com/jackc/pgx)
  团队，He3Proxy在前后端链接管理、协议等方面使用了pgx团队提供的[pgconn](https://github.com/jackc/pgconn) 、[pgproto3](github.com/jackc/pgproto3)
  等工具。
* 感谢其他第三方依赖包对He3Proxy提供的帮助，有你们使开发更高效。
* 感谢以下[开源爱好者](https://gitee.com/he3db/he3proxy/contributors?ref=master) 为He3Proxy做出的贡献。

## 贡献说明

欢迎参与并贡献He3Proxy， 请查看[Contribute](./doc/He3Proxy/contributing.md) 了解详细信息。[CLA](./doc/He3Proxy/CLA.md)提供更多贡献信息。

## RoadMap

[comment]: <实例> "- [x] example"

- [ ] 支持根据冷热数据分布情况进行读节点选择
- [ ] 整体性能调优，目标性能损耗15%以内
- [ ] 支持注册中心（优先etcd）
- [ ] 支持性能监控，如SQL执行时长、节点负载等
- [ ] 支持对He3DB的管理功能，如节点扩缩容、故障切换等
- [ ] 支持He3DB集群灰度升级
- [ ] 支持流量管控，愿景DB订购参数不再是CPU、Mem、Disk而是所需的TPS、QPS
- [ ] 支持Web页面管理中间件功能

## He3Proxy用户列表

**注意： 当前为非release版本，不建议生产使用！**

## 社区

[项目地址](https://gitee.com/he3db/he3proxy) ：https://gitee.com/he3db/he3proxy

欢迎加入[slack](https://dbspecialzone.slack.com/archives/C0403CV7TDY) 进行沟通交流~

更多技术细节欢迎查阅[技术文章专栏](https://www.zhihu.com/column/c_1551505442693394432)

## License

He3Proxy采用Apache 2.0协议，相关协议请参看[目录](./doc/License)