## Module 2: TiProxy Connection Migration During TiDB Server Scaling in

TiProxy can migrate connections from one TiDB server to another without breaking the client connection.

When a TiDB server is about to be offline or the ratio of connections on one TiDB server to connections on another TiDB server exceeds the threshold, the connection migration is triggered. The client is unaware of the connection migration, when using TiProxy.

In the following figure, the TiDB server with the red-dotted line is the one to be scaled in.

![demo018_splash_image_aa_003_20250926.png 85%](https://lab-static.pingcap.com/images/2025/9/26/359c3af54e50e857a606f12425b9849e2fcff4ba.png)

### Step 1. Verify the TiProxy settings

+ [graceful-wait-before-shutdown](https://docs.pingcap.com/tidb/stable/tidb-configuration-file/#graceful-wait-before-shutdown-new-in-v50) specifies the number of seconds that TiDB waits when you shut down the server (closing the TCP port), which allows the clients to disconnect.
+ In [Terminal 2](ssh://monitor1-ssh#2), run the following commands:

  ```bash
  ./connect-tiproxy.sh
  ```

  ```output
  tidb:tiproxy>
  ```

  ```sql
  show config where name='graceful-wait-before-shutdown';
  exit;
  ```

  ```output
  tidb:tiproxy> show config where name='graceful-wait-before-shutdown';
  +------+------------------+-------------------------------+-------+
  | Type | Instance         | Name                          | Value |
  +------+------------------+-------------------------------+-------+
  | tidb | ${LAB:HOST_DB1_PRIVATE_IP}:4000 | graceful-wait-before-shutdown | 15    |
  | tidb | ${LAB:HOST_DB2_PRIVATE_IP}:4000 | graceful-wait-before-shutdown | 15    |
  +------+------------------+-------------------------------+-------+
  2 rows in set (0.01 sec)
  ```

> [!TIP]
> [graceful-wait-before-shutdown](https://docs.pingcap.com/tidb/stable/tidb-configuration-file/#graceful-wait-before-shutdown-new-in-v50) must be at least 10 seconds greater than the duration of the longest transaction of your application to avoid client connection interruption when the TiDB server goes offline.
> Moreover, we recommend you avoid running long transactions, such as batch processing, when scaling in TiDB server.

### Step 2. Check the workload in terminal 1

+ In [Terminal 1](ssh://monitor1-ssh#1), check that the Python workload is still running, and the threads connect to both TiDB servers.
+ Note that in this Python code, there is no extra logic handling TiDB server scaling in. Without TiProxy, you should be able to see errors such as connection lost.

  ```output
  ...
  Thread 4: Connected to TiDB server ${LAB:HOST_DB2_PRIVATE_IP}:4000. User 1 balance updated to: 6
  Thread 3: Connected to TiDB server ${LAB:HOST_DB1_PRIVATE_IP}:4000. User 9 balance updated to: 8
  Thread 1: Connected to TiDB server ${LAB:HOST_DB1_PRIVATE_IP}:4000. User 10 balance updated to: 5
  Thread 2: Connected to TiDB server ${LAB:HOST_DB2_PRIVATE_IP}:4000. User 1 balance updated to: 3
  ...
  ```

### Step 3. Scale in a TiDB Server

+ Open [Terminal 2](ssh://monitor1-ssh#2), run the following command

  ```bash
  ~/.tiup/bin/tiup cluster scale-in tidb-demo --node ${HOST_DB2_PRIVATE_IP}:4000 -y
  ```

  ```output
  ...
  Scaled cluster `tidb-demo` in successfully
  ```

### Step 4. Observe [Terminal 1](ssh://monitor1-ssh#1)

+ In [Terminal 1](ssh://monitor1-ssh#1), you should be able to see that now all threads connect to the same TiDB server.
+ There are no error messages printed out. The connection migration is completely transparent to the application.

  ```output
  ...
  Thread 2: Connected to TiDB server ${LAB:HOST_DB1_PRIVATE_IP}:4000. User 9 balance updated to: 2
  Thread 1: Connected to TiDB server ${LAB:HOST_DB1_PRIVATE_IP}:4000. User 3 balance updated to: 9
  Thread 4: Connected to TiDB server ${LAB:HOST_DB1_PRIVATE_IP}:4000. User 1 balance updated to: 6
  Thread 2: Connected to TiDB server ${LAB:HOST_DB1_PRIVATE_IP}:4000. User 6 balance updated to: 6
  ...
  ```

+ Stop the workload by using `ctrl` + `c`.

  ```output
  ^C
  Received interrupt signal. Stopping all threads...
  ```

### Conclusion

+ In this lab, we show you that, when scaling in TiDB server, TiProxy can migrate the connection to other TiDB servers, so that the scaling in is transparent to the application.