Cloud SQL 语言连接器概览
本页面总结了 Cloud SQL 语言连接器以及如何将其用于您的实例。
Cloud SQL 语言连接器是在连接到 Cloud SQL 实例时提供加密和 IAM 授权的库。Cloud SQL 语言连接器代表用户的应用创建与代理端服务器的已获授权连接,并将该连接传递到应用的数据库驱动程序。Cloud SQL 语言连接器无法提供 Cloud SQL 实例的网络路径(如果尚不存在)。
Cloud SQL 语言连接器使用客户端组件连接到 Cloud SQL 实例上的代理服务器。该连接器会创建一个临时证书,以授权持有者连接到服务器端代理。服务器端代理要求提供有效的 TLS 证书才能连接,从而限制对 Cloud SQL 数据库的访问。
Cloud SQL 支持以下 Cloud SQL 语言连接器:
Cloud SQL 建议使用 Cloud SQL 语言连接器连接到 Cloud SQL 实例。您还可以使用数据库客户端或 Cloud SQL Auth 代理连接到 Cloud SQL 实例。如需详细了解如何连接到 Cloud SQL 实例,请参阅连接选项简介。
要求
如果 Cloud SQL 实例使用共享证书授权机构 (CA) 作为其 serverCaMode
,在客户端,请确保您使用的 Cloud SQL 语言连接器满足以下版本要求:
如果 Cloud SQL 实例使用客户管理的 CA 作为其 serverCaMode
,在客户端,请确保您使用的 Cloud SQL 语言连接器满足以下版本要求:
当实例使用客户管理的 CA 作为其服务器 CA 模式时,您可以为实例配置自定义 DNS 名称。您可以在服务器证书的自定义主题备用名称 (SAN) 字段中提供自定义 DNS 名称。
为实例设置自定义 DNS 名称后,您可以使用该 DNS 名称从 Cloud SQL 语言连接器连接到实例。
Cloud SQL 语言连接器的优势
Cloud SQL 语言连接器具有以下连接到 Cloud SQL 实例的优势:
- IAM 授权:使用身份和访问权限管理 (IAM) 权限来控制谁或什么可以连接到 Cloud SQL 实例。
- 便利:无需管理 SSL 证书、配置防火墙规则或启用已获授权的网络。
限制
如果您在使用情境感知访问权限和 IAM 数据库身份验证,则无法使用 Cloud SQL 语言连接器。当您尝试登录实例时,IAM 身份验证会失败。
强制使用 Cloud SQL 语言连接器
通过强制使用连接器,您可以强制仅使用 Cloud SQL Auth 代理或 Cloud SQL 语言连接器连接到 Cloud SQL 实例。强制使用连接器后,Cloud SQL 会拒绝与数据库的直接连接。
如果您使用的是启用了 Private Service Connect 的实例,则存在限制。如果该实例已要求强制使用连接器,则您无法为该实例创建读取副本。同样,如果该实例具有读取副本,则您无法对该实例要求强制使用连接器。
如需详细了解如何强制要求仅使用 Cloud SQL Auth 代理或 Cloud SQL 语言连接器连接到实例,请参阅使用 Cloud SQL 语言连接器连接。
后续步骤
如未另行说明,那么本页面中的内容已根据知识共享署名 4.0 许可获得了许可,并且代码示例已根据 Apache 2.0 许可获得了许可。有关详情,请参阅 Google 开发者网站政策。Java 是 Oracle 和/或其关联公司的注册商标。
最后更新时间 (UTC):2025-08-08。
[[["易于理解","easyToUnderstand","thumb-up"],["解决了我的问题","solvedMyProblem","thumb-up"],["其他","otherUp","thumb-up"]],[["没有我需要的信息","missingTheInformationINeed","thumb-down"],["太复杂/步骤太多","tooComplicatedTooManySteps","thumb-down"],["内容需要更新","outOfDate","thumb-down"],["翻译问题","translationIssue","thumb-down"],["示例/代码问题","samplesCodeIssue","thumb-down"],["其他","otherDown","thumb-down"]],["最后更新时间 (UTC):2025-08-08。"],[],[],null,["# Cloud SQL Language Connectors overview\n\n\u003cbr /\u003e\n\nMySQL \\| [PostgreSQL](/sql/docs/postgres/language-connectors \"View this page for the PostgreSQL database engine\") \\| [SQL Server](/sql/docs/sqlserver/language-connectors \"View this page for the SQL Server database engine\")\n\n\u003cbr /\u003e\n\nThis page summarizes the Cloud SQL Language Connectors and how to use them\nwith your instances.\n\nCloud SQL Language Connectors are libraries that provide encryption and\n[IAM](/iam) authorization when connecting to a Cloud SQL instance.\nCloud SQL Language Connectors create authorized connections to the\nproxy-side server on behalf of a user's application and pass that connection to\nthe application's database driver. They don't provide a network path to a\nCloud SQL instance if one is not already present.\n\nCloud SQL Language Connectors use a client-side component to connect to a proxy server\non the Cloud SQL instance. The connector creates a temporary certificate\nthat authorizes the holder to connect to the server-side proxy. The server-side\nproxy limits access to the Cloud SQL database by requiring a valid TLS\ncertificate in order to connect.\n\nCloud SQL supports the following Cloud SQL Language Connectors:\n\n- [Cloud SQL Java connector](/sql/docs/mysql/connect-connectors#java)\n- [Cloud SQL Python connector](/sql/docs/mysql/connect-connectors#python)\n- [Cloud SQL Go connector](/sql/docs/mysql/connect-connectors#go)\n- [Cloud SQL Node.js connector](/static/sql/docs/mysql/connect-connectors#node.js)\n\nCloud SQL recommends using Cloud SQL Language Connectors to connect to your\nCloud SQL instance. You can also connect to a Cloud SQL\ninstance [using a database client](/sql/docs/mysql/connect-admin-ip) or the\n[Cloud SQL Auth Proxy](/sql/docs/mysql/sql-proxy). For more information about\nconnecting to a Cloud SQL instance, see [About connection options](/sql/docs/mysql/connect-overview).\n\nRequirements\n------------\n\nIf your Cloud SQL instance uses\n[shared certificate authority (CA)](/sql/docs/mysql/authorize-ssl#shared-regional-ca)\nas its `serverCaMode`, then on the client side,\nmake sure that the Cloud SQL Language Connectors you're using meet\nthe following version requirements:\n\n- [Cloud SQL Java connector](/sql/docs/mysql/connect-connectors#java): [v1.21.0](https://github.com/GoogleCloudPlatform/cloud-sql-jdbc-socket-factory/releases/tag/v1.21.0) or later\n- [Cloud SQL Go connector](/sql/docs/mysql/connect-connectors#go): [v1.12.0](https://github.com/GoogleCloudPlatform/cloud-sql-go-connector/releases/tag/v1.12.0) or later\n- [Cloud SQL Node.js connector](/static/sql/docs/mysql/connect-connectors#node.js): [v1.4.0](https://github.com/GoogleCloudPlatform/cloud-sql-nodejs-connector/releases/tag/v1.4.0) or later\n\n| **Note:** [Cloud SQL Python connector](/sql/docs/mysql/connect-connectors#python) supports instances that use the shared CA configuration, but the connector doesn't verify server identity.\n\nIf your Cloud SQL instance uses\n[customer-managed CA](/sql/docs/mysql/authorize-ssl#customer-managed-ca)\nas its `serverCaMode`, then on the client side,\nmake sure that the Cloud SQL Language Connectors you're using meet\nthe following version requirements:\n\n- [Cloud SQL Java connector](/sql/docs/mysql/connect-connectors#java): [v1.22.0](https://github.com/GoogleCloudPlatform/cloud-sql-jdbc-socket-factory/releases/tag/v1.22.0) or later\n- [Cloud SQL Go connector](/sql/docs/mysql/connect-connectors#go): [v1.14.0](https://github.com/GoogleCloudPlatform/cloud-sql-go-connector/releases/tag/v1.14.0) or later\n- [Cloud SQL Node.js connector](/static/sql/docs/mysql/connect-connectors#node.js): [v1.6.0](https://github.com/GoogleCloudPlatform/cloud-sql-nodejs-connector/releases/tag/v1.6.0) or later\n\nWhen an instance uses customer-managed CA as its server CA mode, you can configure\nthe instance with a [custom DNS name](/sql/docs/mysql/configure-ssl-instance#custom-dns-name).\nYou provide the custom DNS name in the\ncustom subject alternative name (SAN) field of the server certificate.\n\nAfter you set up a custom DNS name for the instance, you can connect to the\ninstance from Cloud SQL Language Connectors using the DNS name.\n\nBenefits of Cloud SQL Language Connectors\n-----------------------------------------\n\nCloud SQL Language Connectors provide the following\nbenefits with connecting to a Cloud SQL instance:\n\n- **IAM authorization**: Uses identity and access management (IAM) permissions to control who or what can connect to your Cloud SQL instances.\n- **Convenience**: Removes the requirement to manage SSL certificates, configure firewall rules, or enable authorized networks.\n\n\u003cbr /\u003e\n\nLimitations\n-----------\n\nYou can't use the Cloud SQL Language Connectors if you're using\n[context-aware access](/iap/docs/cloud-iap-context-aware-access-howto) and\nIAM database authentication. When you try to login to the instance,\nIAM authentication fails.\n\nEnforce the use of Cloud SQL Language Connectors\n------------------------------------------------\n\nBy using [connector enforcement](/sql/docs/mysql/admin-api/rest/v1/instances#ConnectorEnforcement), you can enforce using only the Cloud SQL Auth Proxy or Cloud SQL Language Connectors to connect to Cloud SQL instances. With connector enforcement, Cloud SQL rejects direct connections to the database.\n\nIf you're using a [Private Service Connect-enabled instance](/sql/docs/mysql/about-private-service-connect), then there's a limitation. If the instance has connector enforcement enabled, then you can't create read replicas for the instance. Similarly, if the instance has read replicas, then you can't enable connector enforcement for the instance.\n\nFor more information about how to enforce using only the Cloud SQL Auth Proxy or Cloud SQL Language Connectors to connect to an instance, see [Connect using Cloud SQL Language Connectors](/sql/docs/mysql/connect-connectors#enforce).\n\nWhat's next\n-----------\n\n\u003cbr /\u003e\n\n- [Connect using the Cloud SQL Java Connector](/sql/docs/mysql/connect-connectors#java).\n- [Connect using the Cloud SQL Python Connector](/sql/docs/mysql/connect-connectors#python).\n- [Connect using the Cloud SQL Go Connector](/sql/docs/mysql/connect-connectors#go).\n- [Connect using the Cloud SQL Node.js Connector](/static/sql/docs/mysql/connect-connectors#node.js).\n- Learn more about the [Cloud SQL Auth Proxy](/sql/docs/mysql/sql-proxy).\n\n\u003cbr /\u003e"]]