diff --git a/docs/pages/database-access/reference/configuration.mdx b/docs/pages/database-access/reference/configuration.mdx index 63d85a66abeed..1dfdafe6baa87 100644 --- a/docs/pages/database-access/reference/configuration.mdx +++ b/docs/pages/database-access/reference/configuration.mdx @@ -36,6 +36,10 @@ proxy_service: # MySQL proxy is listening on a separate port and needs to be enabled # on the proxy server. mysql_listen_addr: "0.0.0.0:3036" + # MySQL Server version allows you to overwrite the default Teleport Proxy Service MySQL version (8.0.0-Teleport) + # Note that if the MySQL client connection is using TLS Routing the dynamic MySQL Server Version takes + # precedence over the mysql_server_version proxy settings. + # mysql_server_version: "8.0.4" # Postgres proxy listening address. If provided, proxy will use a separate listener # instead of multiplexing Postgres protocol on web_listener_addr. # postgres_listen_addr: "0.0.0.0:5432" diff --git a/docs/pages/database-access/troubleshooting.mdx b/docs/pages/database-access/troubleshooting.mdx index 33a1a45c8b00d..7e80c8ada2d90 100644 --- a/docs/pages/database-access/troubleshooting.mdx +++ b/docs/pages/database-access/troubleshooting.mdx @@ -137,3 +137,17 @@ Now Alice can connect to any database in the Teleport cluster using any database This example is intentionally simple; we could have configured Alice's permissions using more fine-grained control. For more detailed information about database access controls and how to restrict access see the [RBAC](../database-access/rbac.mdx) documentation. + +## Connection to MySQL database results in "Unknown system variable 'query_cache_size'" error + +When TLS Routing is disable by default, the Teleport Proxy Service returns `8.0.0-Teleport` as the MySQL server version. In some cases, like connecting with a GUI Client, this can result in obtaining an `Unknown system variable 'query_cache_size'` error that indicates that MySQL capabilities were not properly negotiated between the MySQL client and server. + +One way to solve this issue is to [use the TLS Routing feature](https://goteleport.com/docs/manageAment/operations/tls-routing/), where the Teleport Proxy Service propagates the correct MySQL server version via TLS Routing extensions. + +If migration to TLS Routing is not possible, another way to bypass this error is to use the [Teleport local proxy command](https://goteleport.com/docs/connect-your-client/gui-clients/#get-connection-information), which allows you to establish a TLS Routing connection to the Teleport Proxy Service even if TLS Routing was not enabled on the Teleport cluster. + +Another possibility is to overwrite the default MySQL server version (8.0.0-Teleport) returned by the Teleport Proxy Service. To do this, assign the `mysql_server_version` field in the `proxy_service` configuration block on your Teleport Proxy Service instances: +```yaml +proxy_service: + mysql_server_version: "8.0.4" +``` \ No newline at end of file