TiProxyの概要

TiProxyはPingCAPの公式プロキシコンポーネントです。クライアントとTiDBサーバーの間に配置され、TiDBの負荷分散、接続の維持、サービス検出などの機能を提供します。

TiProxyはオプションのコンポーネントです。サードパーティ製のプロキシコンポーネントを使用したり、プロキシを使用せずにTiDBサーバーに直接接続することも可能です。

次の図は、TiProxyのアーキテクチャを示しています。

主な特徴

TiProxyは、接続移行、フェイルオーバー、サービス検出、および迅速な導入機能を提供します。

接続移行

TiProxyは、クライアント接続を切断することなく、あるTiDBサーバーから別のTiDBサーバーへ接続を移行できます。

次の図に示すように、クライアントは当初、TiProxy を介して TiDB 1 に接続します。接続移行後、クライアントは実際に TiDB 2 に接続します。TiDB 1 がオフラインになりそうになった場合、または TiDB 1 への接続数と TiDB 2 への接続数の比率が設定されたしきい値を超えた場合に、接続移行がトリガーされます。クライアントは接続移行を認識しません。

接続移行は通常、次のようなシナリオで発生します。

TiDBサーバーがスケールイン、ローリングアップグレード、またはローリング再起動を実行する場合、TiProxyはオフラインになりそうなTiDBサーバーから他のTiDBサーバーに接続を移行して、クライアント接続を維持することができます。
TiDBサーバーがスケールアウトを実行する際、TiProxyは既存の接続を新しいTiDBサーバーに移行することで、クライアント接続プールをリセットすることなくリアルタイムの負荷分散を実現できます。

フェイルオーバー

TiDBサーバーがメモリ不足（OOM）になる危険性がある場合、またはPDやTiKVへの接続に失敗した場合、TiProxyは問題を自動的に検出し、接続を別のTiDBサーバーに移行することで、クライアントの接続を継続的に確保します。

サービスディスカバリ

TiDBサーバーがスケールインまたはスケールアウトを実行する際、一般的なロードバランサーを使用している場合は、TiDBサーバーリストを手動で更新する必要があります。しかし、TiProxyは手動操作なしでTiDBサーバーリストを自動的に検出できます。

迅速な導入

TiProxyはTiUPに統合グラファナれており、組み込みの仮想IP管理をサポートしているTiDB Operator 、導入、運用、管理コストTiDBダッシュボード削減できます。

ユーザーシナリオ

TiProxyは、以下のシナリオに適しています。

接続の維持：TiDBサーバーがスケールイン、ローリングアップグレード、またはローリング再起動を実行すると、クライアント接続が切断され、エラーが発生します。クライアントに冪等なエラー再試行メカニズムがない場合、エラーを手動で確認して修正する必要があり、作業コストが大幅に増加します。TiProxyはクライアント接続を維持できるため、クライアントはエラーを報告しません。
頻繁なスケールインとスケールアウト：アプリケーションのワークロードは定期的に変化する可能性があります。コストを削減するために、TiDBをクラウドにデプロイし、ワークロードに応じてTiDBサーバーを自動的にスケールインおよびスケールアウトすることができます。ただし、スケールインによってクライアントが切断される可能性があり、スケールアウトによって負荷が不均衡になる可能性があります。TiProxyはクライアント接続を維持し、負荷分散を実現できます。
CPU負荷の不均衡: バックグラウンドタスクが大量のCPUリソースを消費したり、接続間でワークロードが大きく変動してCPU負荷が不均衡になったりすると、TiProxyはCPU使用率に基づいて接続を移行して負荷分散を実現できます。詳細については、 CPUベースの負荷分散参照してください。
TiDBサーバーのOOM: 暴走クエリによってTiDBサーバーのメモリが不足した場合、TiProxyはOOMリスクを事前に検出し、他の正常な接続を別のTiDBサーバーに移行することで、クライアントの接続を継続的に確保します。詳細については、メモリベースの負荷分散参照してください。

TiProxyは、以下のシナリオには適していません。

パフォーマンスに敏感: TiProxy のパフォーマンスは HAProxy や他のロードバランサーよりも低いため、TiProxy を使用する場合は、同様のパフォーマンスレベルを維持するためにより多くの CPU リソースを確保する必要があります。詳細については、 TiProxyのパフォーマンステストレポートを参照してください。
コストに敏感な場合：TiDBクラスタがハードウェアロードバランサー、仮想IP、またはKubernetesが提供するロードバランサーを使用している場合、TiProxyを追加するとコストが増加します。さらに、クラウド上のアベイラビリティゾーンにまたがってTiDBクラスタをデプロイする場合、TiProxyを追加するとアベイラビリティゾーン間のトラフィックコストも増加します。
予期せぬTiDBサーバーのダウンタイムに対するフェイルオーバー：TiProxyは、TiDBサーバーがオフラインになった場合、または計画通りに再起動された場合にのみ、クライアント接続を維持できます。TiDBサーバーが予期せずオフラインになった場合、接続は切断されます。

TiProxyが適しているシナリオではTiProxyを使用し、アプリケーションのパフォーマンスが重要な場合はHAProxyなどの他のプロキシを使用することをお勧めします。

インストールと使用方法

このセクションでは、 TiUPを使用して TiProxy をデプロイおよび変更する方法について説明します。TiProxy をスケールアウトすることで、 TiProxyを使用して新しいクラスターを作成しますまたは既存のクラスターで TiProxy を有効にするいずれかを選択できます。

注記：
TiUPのバージョンが1.16.1以降であることを確認してください。

その他の導入方法については、以下のドキュメントを参照してください。

TiDB Operatorを使用して TiProxy をデプロイするには、 TiDB Operatorドキュメントを参照してください。
TiUPを使用して TiProxy をローカルにすばやくデプロイするには、 TiProxyをデプロイ参照してください。

TiProxyでクラスターを作成する

以下の手順では、新しいクラスタを作成する際に TiProxy をデプロイする方法について説明します。

TiDBインスタンスを設定します。
TiProxyを使用する場合は、TiDB用にgraceful-wait-before-shutdown設定する必要があります。この値は、アプリケーションの最長トランザクションの継続時間より少なくとも10秒長く設定する必要があります。これにより、TiDBサーバーがオフラインになったときにクライアント接続が中断されるのを防ぎます。トランザクションの継続時間はTiDB監視ダッシュボードのトランザクションメトリクスで確認できます。詳細については、制限事項参照してください。
設定例は以下のとおりです。
```
server_configs:
  tidb:
    graceful-wait-before-shutdown: 30
```
TiProxyインスタンスを設定します。
TiProxyの高い可用性を確保するためには、少なくとも2つのTiProxyインスタンスをデプロイし、 ha.virtual-ipとha.interfaceを設定して仮想IPを構成し、トラフィックを利用可能なTiProxyインスタンスにルーティングすることをお勧めします。
以下の点にご注意ください。
- ワークロードの種類と最大 QPS に基づいて、TiProxy インスタンスのモデルと数を選択します。詳細については、 TiProxyのパフォーマンステストレポート参照してください。
- TiProxyインスタンスは通常TiDBサーバーインスタンスよりも少ないため、TiProxyのネットワーク帯域幅がボトルネックになりやすくなります。たとえば、AWSでは、同じシリーズのEC2インスタンスのベースラインネットワーク帯域幅はCPUコア数に比例しません。ネットワーク帯域幅がボトルネックになった場合は、TiProxyインスタンスをより多くの小さなインスタンスに分割してQPSを向上させることができます。詳細については、ネットワーク仕様参照してください。
- トポロジ構成ファイルでTiProxyのバージョンを指定することをお勧めします。これにより、TiDBクラスタをアップグレードするためにコマンドtiup cluster upgradeを実行した際にTiProxyが自動的にアップグレードされるのを防ぎ、TiProxyのアップグレードによってクライアント接続が切断されるのを防止できます。
TiProxy のテンプレートの詳細については、 TiProxyトポロジーのシンプルなテンプレート参照してください。
TiDBクラスタトポロジファイル内の構成項目の詳細については、 TiUPを使用したTiDBデプロイメントのトポロジーコンフィグレーションファイル参照してください。
設定例は以下のとおりです。
```
component_versions:
  tiproxy: "v1.3.2"
server_configs:
  tiproxy:
    ha.virtual-ip: "10.0.1.10/24"
    ha.interface: "eth0"
tiproxy_servers:
  - host: 10.0.1.11
    port: 6000
    status_port: 3080
  - host: 10.0.1.12
    port: 6000
    status_port: 3080
```
クラスターを起動します。
TiUPを使用してクラスターを起動するには、 TiUPドキュメント参照してください。
TiProxyに接続します。
クラスタがデプロイされると、TiDBサーバーポートとTiProxyポートが同時に公開されます。クライアントはTiDBサーバーに直接接続するのではなく、TiProxyポートに接続する必要があります。

既存のクラスターでTiProxyを有効にする

TiProxyがデプロイされていないクラスターの場合、TiProxyインスタンスをスケールアウトすることでTiProxyを有効にできます。

TiProxyインスタンスを設定します。

TiProxyを別のトポロジーファイルで設定します。例: tiproxy.toml :

component_versions:
  tiproxy: "v1.3.2"
server_configs:
  tiproxy:
    ha.virtual-ip: "10.0.1.10/24"
    ha.interface: "eth0"
tiproxy_servers:
  - host: 10.0.1.11
    deploy_dir: "/tiproxy-deploy"
    port: 6000
    status_port: 3080
  - host: 10.0.1.12
    deploy_dir: "/tiproxy-deploy"
    port: 6000
    status_port: 3080

TiProxyをスケールアウトする。
TiProxyインスタンスをスケールアウトするには、 tiup cluster scale-outコマンドを使用します。例：
```
tiup cluster scale-out <cluster-name> tiproxy.toml
```
TiProxyをスケールアウトすると、 TiUPはTiDB用に自己署名証明書security.session-token-signing-certとsecurity.session-token-signing-key自動的に構成します。この証明書は接続の移行に使用されます。
TiDBの設定を変更してください。
TiProxyを使用する場合は、TiDB用にgraceful-wait-before-shutdown設定する必要があります。この値は、TiDBサーバーがオフラインになったときにクライアント接続が中断されないように、アプリケーションの最長トランザクションの継続時間より少なくとも10秒長くする必要があります。トランザクションの継続時間はTiDB監視ダッシュボードのトランザクションメトリクスで確認できます。詳細については、制限事項参照してください。
設定例は以下のとおりです。
```
server_configs:
  tidb:
    graceful-wait-before-shutdown: 30
```
TiDBの設定を再読み込みしてください。
TiDBは自己署名証明書とgraceful-wait-before-shutdownで構成されているため、それらを有効にするにはtiup cluster reloadコマンドを使用して構成を再読み込みする必要があります。構成を再読み込みすると、TiDBはローリング再起動を実行し、クライアント接続が切断されることに注意してください。
```
tiup cluster reload <cluster-name> -R tidb
```
TiProxyに接続します。
TiProxyを有効にすると、クライアントはTiDBサーバーポートではなく、TiProxyポートに接続するようになります。

TiProxyの設定を変更します

TiProxy がクライアント接続を維持するようにするため、必要がない限り TiProxy を再起動しないでください。そのため、TiProxy の設定項目のほとんどはオンラインで変更できます。オンラインでの変更をサポートする設定項目のリストについては、 TiProxyの設定参照してください。

TiUPを使用してTiProxyの設定を変更する場合、変更する設定項目がオンライン変更に対応している場合は、オプション--skip-restartを使用することでTiProxyの再起動を回避できます。

TiProxyをアップグレードする

TiProxyをデプロイする際には、TiDBクラスタをアップグレードした際にTiProxyもアップグレードされないように、TiProxyのバージョンを指定することをお勧めします。

TiProxyをアップグレードする必要がある場合は、アップグレードコマンドに--tiproxy-versionを追加してTiProxyのバージョンを指定してください。

tiup cluster upgrade <cluster-name> <version> --tiproxy-version <tiproxy-version>

注記：
このコマンドは、クラスターのバージョンが変更されない場合でも、TiDBクラスターをアップグレードして再起動します。

TiDBクラスターを再起動します

tiup cluster restartを使用して TiDB クラスターを再起動すると、TiDB サーバーがローリング再起動されないため、クライアント接続が切断されます。したがって、このコマンドの使用は避けてください。

その代わりに、 tiup cluster upgrade使用してクラスターをアップグレードしたり、 tiup cluster reloadを使用して構成を再読み込みしたりすると、TiDB サーバーがローリング再起動されるため、クライアント接続には影響しません。

他のコンポーネントとの互換性

TiProxyはTiDB v6.5.0以降のバージョンのみをサポートしています。
TiProxy の TLS 接続は TiDB と互換性のない機能を持っています。詳細はSecurity参照してください。
TiDB DashboardとGrafanaは、バージョン7.6.0以降でTiProxyをサポートしています。
TiUPはv1.14.1以降でTiProxyをサポートし、 TiDB Operatorはv1.5.1以降でTiProxyをサポートしています。
TiProxyのステータスポートが提供するインターフェースはTiDBサーバーのものとは異なるため、 TiDB Lightning使用してデータをインポートする場合、ターゲットデータベースはTiProxyのアドレスではなく、TiDBサーバーのアドレスである必要があります。

Security

TiProxyはTLS接続を提供します。クライアントとTiProxy間のTLS接続は、以下のルールに従って有効化されます。

TiProxy の設定security.server-tls TLS 接続を使用しないように設定されている場合、クライアントが TLS 接続を有効にしているかどうかに関わらず、クライアントと TiProxy 間の TLS 接続は有効になりません。
TiProxyの設定security.server-tls TLS接続を使用するように設定されている場合、クライアントとTiProxy間のTLS接続は、クライアントがTLS接続を有効にした場合にのみ有効になります。

TiProxyとTiDBサーバー間のTLS接続は、以下のルールに従って有効化されます。

TiProxyのsecurity.require-backend-tls trueに設定されている場合、クライアントがTLS接続を有効にしているかどうかに関わらず、TiProxyとTiDBサーバーは常にTLS接続を有効にします。TiProxyのsecurity.sql-tlsがTLSを使用しないように設定されている場合、またはTiDBサーバーがTLS証明書を構成していない場合、クライアントはエラーを報告します。
TiProxyのsecurity.require-backend-tls falseに設定され、TiProxyのsecurity.sql-tlsがTLSで構成され、TiDBサーバーがTLS証明書で構成されている場合、TiProxyとTiDBサーバーは、クライアントがTLS接続を有効にした場合にのみTLS接続を有効にします。
TiProxyのsecurity.require-backend-tls falseに設定されている場合、TiProxyのsecurity.sql-tlsがTLSを使用しないように設定されている場合、またはTiDBサーバーがTLS証明書を構成していない場合、TiProxyとTiDBサーバーはTLS接続を有効にしません。

TiProxyには、TiDBと互換性のない以下の動作があります。

STATUSとSHOW STATUSステートメントは異なるTLS情報を返す可能性があります。5 STATUSのステートメントはクライアントとTiProxy間のTLS情報を返し、 SHOW STATUSステートメントはTiProxyとTiDBサーバー間のTLS情報を返します。
TiProxy は証明書ベースの認証サポートしていません。そうでない場合、クライアントと TiProxy 間の TLS 証明書が TiProxy と TiDBサーバー間の TLS 証明書と異なるため、クライアントはログインに失敗する可能性があります。TiDBサーバーはTiProxy 上の TLS 証明書に基づいて TLS 証明書を検証します。

制限事項

TiProxyは、以下のシナリオではクライアント接続を維持できません。

TiDBが予期せずオフラインになりました。TiProxyは、TiDBサーバーがオフラインまたは計画通りに再起動された場合にのみクライアント接続を維持し、TiDBサーバーのフェイルオーバーはサポートしていません。
TiProxyは、スケールイン、アップグレード、または再起動を実行します。TiProxyがオフラインになると、クライアントとの接続は切断されます。
TiDBは接続を積極的に切断します。例えば、セッションがwait_timeout以上リクエストを送信しない場合、TiDBは接続を積極的に切断し、TiProxyもクライアント接続を切断します。

TiProxyは、以下のシナリオでは接続を移行できないため、クライアント接続が中断されたり、ロードバランシングが失敗したりする可能性があります。

長時間実行される単一のステートメントまたは単一のトランザクション：実行時間が、TiDBサーバーで設定されているgraceful-wait-before-shutdownから10秒を引いた値を超えます。
カーソルを使用し、時間内に完了しない場合：セッションはカーソルを使用してデータを読み取りますが、TiDBサーバーで設定された値graceful-wait-before-shutdownから10秒を引いた後、データの読み取りを完了するか、カーソルを閉じません。
セッションはローカル一時テーブルを作成します。
このセッションではユーザーレベルのロックが行われます。
このセッションではテーブルロックが行われます。
セッションでエラーコードプリペアドステートメントが作成され、プリペアドステートメントが無効になります。たとえば、プリペアドステートメントに関連付けられたテーブルが、プリペアドステートメントの作成後に削除された場合などです。
セッションはセッションレベル実行計画のバインディングを作成しますが、バインディングが無効です。たとえば、バインディングに関連付けられたテーブルは、バインディングが作成された後で削除されます。
セッションが作成された後、そのセッションで使用されているユーザーが削除されるか、ユーザー名が変更されます。

サポートされているコネクタ

TiProxyでは、クライアントが使用するコネクタが認証プラグインサポートしている必要があります。そうでない場合、接続が失敗する可能性があります。

以下の表は、サポートされているコネクタの一部を示しています。

言語	コネクタ	サポートされている最小バージョン
Java	MySQL Connector/J	2019年5月1日
C	libmysqlclient	5.5.7
行く	Go SQLDriver	1.4.0
JavaScript	MySQLコネクタ/Node.js	1.0.2
JavaScript	mysqljs/mysql	2.15.0
JavaScript	node-mysql2	1.0.0-rc-6
PHP	mysqlnd	5.4
Python	MySQLコネクタ/Python	1.0.7
Python	PyMySQL	0.7

一部のコネクタは共通ライブラリを呼び出してデータベースに接続しますが、これらのコネクタは表には記載されていません。必要なライブラリのバージョンについては、上記の表を参照してください。たとえば、MySQL/Rubyはlibmysqlclientを使用してデータベースに接続するため、MySQL/Rubyで使用されるlibmysqlclientのバージョンは5.5.7以降である必要があります。

TiProxyリソース

TiProxy リリースノート
TiProxyに関する問題 : TiProxyのGitHubイシュー一覧