# He3Proxy

**Repository Path**: chenjian835/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**: 0
- **Forks**: 16
- **Created**: 2023-05-08
- **Last Updated**: 2023-05-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## 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读一致性，并根据节点负载情况进行负载均衡。(开发测试中)

### 功能演示

![功能演示](./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=debug
```

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

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

### 配置文件说明

[he3proxy.yaml](./etc/he3proxy.yaml)

### 环境变量说明

|  变量名   | 含义  | 可选值  | 默认值  | 示例  |
|  ----  | ----  | ----  | ----  | ----  |
|  SERVER_VERSION | 为兼容不同版本的客户端设计了此参数，表示后端数据库的版本，仅在使用PG数据库时有效 | x.x.x | 9.0.0 | export SERVER_VERSION=14.2 |
|  SINGLE_SESSION | 只使用主节点进行读写操作 | [on,off] | 关闭 | export SINGLE_SESSION=on |
|  CONNS_POOL_SWITCH | 是否使用连接池 | [true,false] | 开启 | export CONNS_POOL_SWITCH=false |
|  HE3PROXY_FLAG | 对后端数据库表明是He3Proxy建立的链接，一些定制化功能所需如读一致性，仅限数据库为He3DB时使用 | [true,false] | 开启 | export HE3PROXY_FLAG=false |

[comment]: <> "|  DB_TYPE | 表示后端数据库的类型，项目基于kingshard开发，保留了原有kingshard的功能，仍可作为mysql的中间件 | [mysql,postgresql] | postgresql | export DB_TYPE=postgresql |"

## 鸣谢

* 感谢[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"

- [ ] 支持读一致性，节点LSN信息维护到DB粒度
- [ ] 支持根据冷热数据分布情况进行读节点选择
- [ ] 整体性能调优，目标性能损耗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://join.slack.com/t/dbspecialzone/shared_invite/zt-1fe4g7uf4-iC_rdhnWpQkP0oQl_GUSKQ) 进行沟通交流~

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

## License

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