From 563f57595a2415ca8bb73442aeb0ced50f11ef8f Mon Sep 17 00:00:00 2001
From: djshow832 <zhangming@pingcap.com>
Date: Tue, 25 Oct 2022 15:50:17 +0800
Subject: [PATCH] *: update README (#122)

---
 README-CN.md | 22 --------------
 README.md    | 84 +++++++++++++++++++++++++++++++++++++++-------------
 2 files changed, 64 insertions(+), 42 deletions(-)
 delete mode 100644 README-CN.md

diff --git a/README-CN.md b/README-CN.md
deleted file mode 100644
index 814c2ba8..00000000
--- a/README-CN.md
+++ /dev/null
@@ -1,22 +0,0 @@
-# Weir
-
-Weir是伴鱼公司研发的开源数据库代理平台, 主要为TiDB分布式数据库提供数据库治理功能.
-
-## 功能特性
-
-> 1. Weir 为 MySQL 协议提供应用层代理，兼容 TiDB 4.0。[L7层负载](docs/cn/proxy.md)
-> 2. Weir 使用连接池进行后端连接管理，并支持负载均衡。[链接管理](docs/cn/connection-management.md)
-> 3. Weir 支持多租户管理，所有命名空间都可以在运行时动态重新加载。[多租户软隔离](docs/cn/multi-tenant.md)
-> 4. Weir 支持 qps 限流和熔断机制来保护客户端和 TiDB 服务器。[熔断限流机制](docs/cn/fault-tolerant.md)
-
-## 使用手册
-
-- [快速上手](docs/cn/quickstart.md)
-- [Proxy配置详解](docs/cn/proxy-config.md)
-- [Namespace配置详解](docs/cn/namespace-config.md)
-- [集群部署](docs/cn/cluster_deployment.md)
-- [配置热加载](docs/cn/config-dynamic-reload.md)
-- [监控与告警](docs/cn/monitoring.md)
-- [RESTful-Api](docs/cn/RESTful_api.md)
-
-## FAQ
diff --git a/README.md b/README.md
index 998e79e7..5399cde9 100644
--- a/README.md
+++ b/README.md
@@ -1,40 +1,84 @@
-# Weir
+## What is TiProxy?
 
-Weir is a database proxy middleware platform, mainly providing traffic management for TiDB.
+TiProxy is a database proxy that is based on TiDB. It keeps client connections alive while the TiDB server upgrades, restarts, scales in, and scales out.
 
-Weir is maintained by [伴鱼](https://www.ipalfish.com/) and [PingCAP](https://pingcap.com/).
-
-[中文文档](README-CN.md)
+TiProxy is forked from [Weir](https://github.com/tidb-incubator/weir).
 
 ## Features
 
-- __L7 Proxy__
+### Connection Management
 
-Weir provides application layer proxy for MySQL Protocol, and it is compatible with TiDB 4.0.
+When a TiDB instance restarts or shuts down, TiProxy migrates backend connections on this instance to other instances. In this way, the clients won't be disconnected.
 
-- __Connection Management__
+### Load Balance
 
-Weir uses connection pool for backend connection management, and supports load balancing.
+TiProxy routes new connections to backends based on their scores to keep load balanced. The score is basically calculated from the connections on each backend.
 
-- __Multi-tenant Management__
+Besides, when the clients create or close connections, TiProxy also migrates backend connections to keep the backends balanced.
 
-Weir supports multi-tenant management. All the namespaces can be dynamic reloaded in runtime.
+### Service Discovery
 
-- __Fault Tolerance__
+When a new TiDB instance starts, the TiProxy detects the new TiDB instance and migrates backend connections to the instance.
 
-Weir supports rate limiting and circuit breaking to protect both clients and TiDB servers.
+The TiProxy also checks health on TiDB instances to ensure they are alive, and migrates the backend connections to other TiDB instances if any instance is down.
 
 ## Architecture
 
-There are three core components in Weir platform: proxy, controller and UI dashboard.
+For more details, see [Design Doc](https://github.com/pingcap/tidb/blob/master/docs/design/2022-07-20-session-manager.md).
+
+## Build
+
+Build the binary in local:
+
+```shell
+$ make
+```
+
+Build a docker image:
+
+```shell
+$ make docker
+```
+
+## Usage
+
+1. Generate a self-signed certificate, which is used for the token-based authentication between TiDB and TiProxy.
+
+Put the certs and keys to all the TiDB servers. Make sure all the TiDB instances use the same certificate.
+
+2. Update the `config.toml` of TiDB instances:
+
+```toml
+security.auto-tls=true
+security.session-token-signing-cert={path/to/cert.pem}
+security.session-token-signing-key={path/to/key.pem}
+graceful-wait-before-shutdown=10
+```
+
+Where the `session-token-signing-cert` and `session-token-signing-key` are the paths to the certs generated in the 1st step.
+
+And then start the TiDB cluster with the config.toml.
+
+3. Update the `proxy.yaml` of TiProxy:
+
+```yaml
+proxy:
+    pd-addrs: "127.0.0.1:2379"
+```
+
+Where the `pd-addrs` contains the addresses of all PD instances.
+
+And then start TiProxy:
 
-<img src="docs/en/assets/weir-architecture.png" style="zoom:80%;" />
+```shell
+$ bin/tiproxy --config=conf/proxy.yaml
+```
 
-## Roadmap
+4. Connect to TiProxy with your client. The default port is 6000:
 
-- Web Application Firewall (WAF) for SQL
-- Database Mesh for TiDB
-- SQL audit
+```shell
+$ mysql -h127.0.0.1 -uroot -P6000
+```
 
 ## Code of Conduct
 
@@ -42,4 +86,4 @@ This project is for everyone. We ask that our users and contributors take a few
 
 ## License
 
-Weir is under the Apache 2.0 license. See the [LICENSE](./LICENSE) file for details.
+TiProxy is under the Apache 2.0 license. See the [LICENSE](./LICENSE) file for details.