TiDB Cloud Lake FAQ¶

Account and Lake DSN¶

What if I don't have a TiDB Cloud account?¶

Go to Register TiDB Cloud. After completing registration and initial authentication, the system will enter TiDB Cloud Lake and open Connect. Copy the LakeSQL DSN, then return to Guance to continue configuration.

Cannot find Connect or Lake DSN¶

1. Make sure you are currently in TiDB Cloud Lake;
2. Open Connect on the Lake page;
3. Select LakeSQL in the connection examples; do not copy Python, Golang, or other examples;
4. Verify that the DSN contains both the Database and the warehouse parameter.

See Register TiDB Cloud and Obtain Lake DSN for the complete steps.

Lake DSN format error or unable to parse Database / Warehouse¶

Re-copy the full DSN from the Connect page; do not manually delete or modify its content. The format should be similar to:

lake://user:password@host:443/database?warehouse=warehouse_name

If the password contains special characters, prefer using the DSN generated by the TiDB Cloud Lake page to avoid encoding errors caused by manual concatenation.

Connection and Authentication¶

Authentication failed error¶

Possible causes include incorrect SQL user name or password, an updated password, or a disabled user. Confirm the account status in TiDB Cloud Lake, re-obtain the DSN, and then update the configuration in Guance.

Unable to connect to TiDB Cloud Lake error¶

Check the following in order:

1. Whether the Endpoint and Port in the DSN are complete;
2. Whether the target Warehouse is available;
3. Whether the TiDB Cloud Lake service is running normally;
4. Whether the network policy allows Guance service to access the Lake;
5. Re-run the test connection later to rule out transient network or Warehouse unavailability.

What should I do after changing the password?¶

Re-copy the Lake DSN and update it in all external data sources and data forwarding rules that use the old password. The two features store configurations independently and do not synchronize automatically.

External Data Sources and Queries¶

Connection succeeded, but queries return no permission error¶

A successful connection only means the DSN and basic connection are valid. Verify that the SQL user has read-only query permissions on the target Database, Schema, and Table, and that the current Guance member has the usage permission on that external data source.

Cannot see the Lake data source in the query data source list¶

Verify:

• The data source is saved and has not been deleted;
• The current member has the usage permission on that data source;
• The current page supports external data source queries;
• No filter or search condition is hiding the data source.

Why can’t write-type SQL be executed?¶

To protect Lake data, external data source queries only support single read-only SELECT, WITH ... SELECT, or EXPLAIN statements. Write, delete, DDL, transactions, and multi-statement queries are rejected by the server. To write observability data, use Data Forwarding to TiDB Cloud Lake.

Query timeout or result exceeds the limit¶

A single query defaults to a 60-second timeout and returns at most 10,000 rows. Narrow the time range, add WHERE conditions, reduce the scan scope, or add a LIMIT.

Data Forwarding¶

The test connection succeeded, but the target table was not created¶

The test connection verifies the Lake DSN, Database, Warehouse, whether the target table exists, and the corresponding write or table creation permissions, and provides the check result. It does not create the table. If the target table does not exist, the system will create it according to the managed schema of the forwarded data type when the rule is completed.

No write or table creation permission when testing connection or completing the rule¶

• If the target table exists: the SQL user needs write permission on it;
• If the target table does not exist: the SQL user also needs permission to create tables in the target Database.

After adjusting the permissions, re-test the connection and then complete the rule creation.

If the write permission or table structure check on the target table fails, or if the system fails to create the target table, the rule will still be enabled and show a [！] warning in the rule list. Fix the permissions, table structure, or table creation issue according to the warning to ensure subsequent batches can be written to the target table.

Target table structure is incompatible¶

An existing target table must be compatible with the system-managed schema of the forwarded data type. It is recommended to use a new table name so that the system automatically creates it when the rule is completed. If you must use an existing table, adjust its structure according to the error message first.

The rule is enabled, but no data can be found yet¶

Data forwarding packs Parquet batches according to the selected data waiting time and loads them into the Lake, so it is not a row-by-row real-time write. Check:

1. Whether any data matches the data type and filter conditions of the rule;
2. Whether the selected waiting time of 15 minutes, 30 minutes, or 1 hour has been exceeded;
3. Whether the rule or the loading batch shows a failure;
4. Whether the Database and Target Table used in the query match the rule.

Why is it not necessary to fill in Bucket, storage path, or IAM credentials?¶

TiDB Cloud Lake forwarding uses the intermediate storage and object path managed by Guance. You only need to provide the Lake DSN and Target Table; the Bucket, object path, and intermediate access credentials are maintained by the system.

Security Troubleshooting¶

What information can I provide when submitting an issue?¶

You can provide:

• The data source name or forwarding rule name;
• The redacted Endpoint, Database, Warehouse, and Target Table;
• The failure time, error code, and error message on the page;
• The SQL fingerprint or the query structure after removing sensitive conditions.

Do not provide the full Lake DSN, SQL user password, internal Bucket, temporary credentials, or complete query results containing sensitive data.