SQL Proxy Account

A SQL proxy account is a SQL user account that is automatically created by TiDB Cloud to access the database via SQL Editor or Data Service on behalf of a TiDB Cloud user. For example, testuser@pingcap.com is a TiDB Cloud user account, while 3jhEcSimm7keKP8.testuser._41mqK6H4 is its corresponding SQL proxy account.

SQL proxy accounts provide a secure, token-based authentication mechanism for accessing the database in TiDB Cloud. By eliminating the need for traditional username and password credentials, SQL proxy accounts enhance security and simplify access management.

The key benefits of SQL proxy accounts are as follows:

Enhanced security: mitigates risks associated with static credentials by using JWT tokens.
Streamlined access: restricts access specifically to the SQL Editor and Data Service, ensuring precise control.
Ease of management: simplifies authentication for developers and administrators working with TiDB Cloud.

Identify the SQL proxy account

If you want to identify whether a specific SQL account is a SQL proxy account, take the following steps:

Examine the mysql.user table:

USE mysql;
SELECT user FROM user WHERE plugin = 'tidb_auth_token';

Check grants for the SQL account. If roles like role_admin, role_readonly, or role_readwrite are listed, then it is a SQL proxy account.
```
SHOW GRANTS for 'username';
```

How the SQL proxy account is created

The SQL proxy account is automatically created during TiDB Cloud cluster initialization for the TiDB Cloud user who is granted a role with permissions in the cluster.

How the SQL proxy account is deleted

When a user is removed from an organization or a project, or their role changes to one that does not have access to the cluster, the SQL proxy account is automatically deleted.

Note that if a SQL proxy account is manually deleted, it will be automatically recreated when the user log in to the TiDB Cloud console next time.

SQL proxy account username

In some cases, the SQL proxy account username is exactly the same as the TiDB Cloud username, but in other cases it is not exactly the same. The SQL proxy account username is determined by the length of the TiDB Cloud user's email address. The rules are as follows:

Environment	Email length	Username format
TiDB Cloud Dedicated	<= 32 characters	Full email address
TiDB Cloud Dedicated	> 32 characters	`prefix($email, 23)_prefix(base58(sha1($email)), 8)`
TiDB Cloud Serverless	<= 15 characters	`serverless_unique_prefix + "." + email`
TiDB Cloud Serverless	> 15 characters	`serverless_unique_prefix + "." + prefix($email, 6)_prefix(base58(sha1($email)), 8)`

Examples:

Environment	Email address	SQL proxy account username
TiDB Cloud Dedicated	`user@pingcap.com`	`user@pingcap.com`
TiDB Cloud Dedicated	`longemailaddressexample@pingcap.com`	`longemailaddressexample_48k1jwL9`
TiDB Cloud Serverless	`u1@pingcap.com`	`{user_name_prefix}.u1@pingcap.com`
TiDB Cloud Serverless	`longemailaddressexample@pingcap.com`	`{user_name_prefix}.longem_48k1jwL9`

Note

In the preceding table, {user_name_prefix} is a unique prefix generated by TiDB Cloud to distinguish TiDB Cloud Serverless clusters. For details, see the user name prefix of TiDB Cloud Serverless clusters.

SQL proxy account password

Since SQL proxy accounts are JWT token-based, it is not necessary to manage passwords for these accounts. The security token is automatically managed by the system.

SQL proxy account roles

The SQL proxy account's role depends on the TiDB Cloud user's IAM role:

Organization level:
- Organization Owner: role_admin
- Organization Billing Admin: No proxy account
- Organization Member: No proxy account
- Organization Console Audit admin: No proxy account
Project level:
- Project Owner: role_admin
- Project Data Access Read-Write: role_readwrite
- Project Data Access Read-Only: role_readonly

SQL proxy account access control

SQL proxy accounts are JWT token-based and only accessible to the Data Service and SQL Editor. It is impossible to access the TiDB Cloud cluster using a SQL proxy account with a username and password.