Acerca de las opciones de conexión

En esta página, se proporciona una descripción general de las formas en que puedes conectarte a tu instancia de Cloud SQL y se describen las opciones de autenticación y autorización disponibles.

Descripción general

Cuando consideres cómo conectarte a tu instancia de Cloud SQL, debes tener en cuenta muchas opciones, incluidas las siguientes:

  • ¿Quieres que se pueda acceder a tu instancia de Cloud SQL desde Internet, mantenerla privada en una red de nube privada virtual (VPC) o hacer que se pueda acceder a ella de forma pública y privada?
  • ¿Planeas escribir tu propio código de conexión o conectarte mediante herramientas disponibles públicamente, como el proxy de autenticación de Cloud SQL o un cliente psql?
  • ¿Quieres solicitar encriptación mediante SSL/TLS o permitir el tráfico sin encriptar?

En las siguientes secciones, analizaremos las opciones que Cloud SQL proporciona para conectar, autorizar y autenticar en tu base de datos.

  • Cómo conectarse: Se refiere a qué ruta de red usas para llegar a la instancia:
    • Una dirección IP interna, solo de VPC (privada).
    • Una dirección IP externa, accesible a través de Internet (Pública).
  • Cómo autenticar: Se refiere a qué conexiones están autorizadas y pueden conectarse a la instancia de Cloud SQL.
    • El proxy de autenticación de Cloud SQL y las bibliotecas de conectores de Cloud SQL para Java y Python proporcionan acceso basado en IAM.
    • Certificados SSL/TLS autoadministrados: Estos solo permiten conexiones basadas en claves públicas específicas.
    • Redes autorizadas: Una lista de direcciones IP permitidas para conectarse.
  • Cómo realizar la autenticación: El método para acceder a tu base de datos.
    • Autenticación de base de datos integrada: Accede con un nombre de usuario o una contraseña configurados en el motor de base de datos.

Usa la siguiente información para decidir qué opciones de conexión, autorización y autenticación te resultan más útiles.

Antes de comenzar

Si se otorga acceso a una aplicación, esto no significa que se habilite de forma automática una cuenta de usuario de base de datos para conectarse a la instancia. Antes de que puedas conectarte a una instancia, debes tener una cuenta de usuario de base de datos con la que te puedas conectar. Para instancias nuevas, debes tener configurada la cuenta de usuario predeterminada. Más información

Opciones de conexión

Las conexiones de bases de datos consumen recursos en el servidor y en la aplicación de conexión. Usa siempre prácticas adecuadas de administración de conexión para minimizar el espacio de tu aplicación y reducir la posibilidad de superar los límites de conexión de Cloud SQL. Para obtener más información, consulta la página sobre cómo administrar conexiones de bases de datos.

IP pública y privada

En Cloud SQL, la IP pública significa que se puede acceder a la instancia a través de la Internet pública. Por el contrario, las instancias que usan solo IP privadas no son accesibles a través de la Internet pública, pero se puede acceder a ellas a través de una nube privada virtual (VPC). Las instancias de Cloud SQL pueden tener una dirección IP pública y una privada.

IP privada

Una IP privada es una dirección IPv4 o IPv6 a la que se puede acceder en una nube privada virtual (VPC).

Puedes usar esta dirección para conectarte desde otros recursos con acceso a la VPC. Las conexiones mediante IP privadas suelen proporcionar una latencia más baja y vectores de ataque limitados porque no requieren atravesar Internet. De forma opcional, puedes solicitar que todas las conexiones usen el proxy de Cloud SQL o los certificados SSL autoadministrados.

Es preferible configurar tu instancia con una IP privada cuando te conectas desde un cliente en un recurso con acceso a una VPC. Para obtener más información sobre qué recursos pueden usar una IP privada, consulta Requisitos de IP privada.

En el caso de las rutas de IP privadas, los siguientes servicios y aplicaciones se conectan directamente a tu instancia a través del Acceso a VPC sin servidores:

  • Entorno estándar de App Engine
  • Entorno flexible de App Engine
  • Cloud Functions
  • Cloud Run

Obtén más información sobre el uso de IP privada con Cloud SQL.

Si deseas obtener instrucciones para agregar una IP privada a la instancia, consulta Configura la conectividad de IP privada.

IP pública

Una IP pública es una dirección IPv4 o IPv6 que está disponible de forma externa en la Internet pública. Esta dirección puede recibir conexiones de dispositivos dentro y fuera de la red de Google, incluso desde ubicaciones como una oficina o tu casa.

Para contribuir a la seguridad de tu instancia, cualquier conexión a una instancia de Cloud SQL mediante una IP pública debe autorizarse mediante el uso del proxy de Cloud SQL o las redes autorizadas.

La configuración de tu instancia con una IP pública es mejor cuando te conectas desde un cliente que no cumple con los requisitos de una VPC.

Si deseas obtener instrucciones para agregar una IP pública a una instancia, consulta Configura la conectividad de IP pública.

Para obtener más información sobre cómo conectar un cliente sqlcmd a una instancia de Cloud SQL mediante una IP pública, consulta Conéctate mediante un cliente de base de datos.

Opciones de autorización

Proxy de Cloud SQL Auth

El proxy de autenticación de Cloud SQL te permite autorizar y proteger tus conexiones mediante los permisos de Identity and Access Management (IAM). El proxy de autenticación de Cloud SQL valida las conexiones mediante credenciales para un usuario o una cuenta de servicio y une la conexión en una capa SSL/TLS autorizada para una instancia de Cloud SQL. Para obtener más información sobre cómo funciona el proxy de autenticación de Cloud SQL, consulta Acerca del proxy de autenticación de Cloud SQL.

El uso del proxy de autenticación de Cloud SQL es el método recomendado para autenticar conexiones a una instancia de Cloud SQL porque es el más seguro.

El proxy de autenticación de Cloud SQL es una biblioteca de código abierto que se distribuye como un objeto binario ejecutable. El proxy de autenticación de Cloud SQL actúa como un servidor intermediario que escucha las conexiones entrantes, las une en SSL/TLS y, luego, las pasa a una instancia de Cloud SQL.

Algunos entornos proporcionan un mecanismo que se conecta mediante el proxy de autenticación de Cloud SQL. A fin de obtener instrucciones para conectarte mediante estos entornos, consulta una de las siguientes páginas:

Bibliotecas de conectores de Cloud SQL para Java y Python

Cloud SQL ofrece bibliotecas cliente que proporcionan encriptación y autorización basada en IAM cuando se conectan a una instancia de Cloud SQL con conectores de Java y Python.

Puedes usar estas bibliotecas directamente desde el entorno de lenguaje. Proporcionan la misma autenticación que el proxy de autenticación de Cloud SQL sin la necesidad de un proceso externo. Para comenzar, consulta Conéctate mediante los conectores de Cloud SQL.

Certificados SSL/TLS autoadministrados

En lugar de usar el proxy de Cloud SQL Auth para encriptar las conexiones, es posible configurar certificados SSL/TLS de cliente o servidor que sean específicos de una instancia de Cloud SQL. Estos certificados se usan para validar el cliente y el servidor entre sí, y encriptar las conexiones entre ellos.

Se recomienda usar certificados SSL/TLS autoadministrados para proporcionar encriptación cuando no se usa el proxy de Cloud SQL Auth. Si no lo haces, tus datos se transmiten de forma insegura, y un tercero podría interceptarlos o inspeccionarlos.

Para comenzar a usar los certificados SSL/TLS autoadministrados, consulta Autoriza con certificados SSL/TLS.

Redes autorizadas

A menos que uses el proxy de autenticación de Cloud SQL, las conexiones a la dirección IP pública de una instancia solo se permiten si la conexión proviene de una red autorizada. Las redes autorizadas son direcciones IP o rangos a los que el usuario especificó que tiene permiso para conectarse.

Para comenzar a usar las redes autorizadas, consulta Autoriza con redes autorizadas.

Opciones de autenticación

La autenticación proporciona control de acceso mediante la verificación de la identidad de un usuario. Para los usuarios finales, la autenticación se logra cuando el usuario ingresa credenciales (nombre de usuario y contraseña). Para las aplicaciones, la autenticación se logra cuando se asignan las credenciales de un usuario a una cuenta de servicio.

Cloud SQL usa la autenticación integrada de la base de datos que se autentica con un nombre de usuario y una contraseña. Para obtener más información, consulta Crea y administra usuarios de SQL Server.

Herramientas para la conexión

En la siguiente tabla, se muestran algunas opciones para conectarse a Cloud SQL:

Opción de conexión Más información
Proxy de Cloud SQL Auth
gcloud
Conectores de lenguaje de Cloud SQL
Cloud Shell
Conéctate con herramientas de administración de bases de datos de terceros
SQL Server Management Studio
Explorador de objetos de SMSS
Visual Studio

Muestras de código

Puedes conectarte al proxy de autenticación de Cloud SQL desde cualquier lenguaje que permita conectarte a un socket de TCP. A continuación, se incluyen algunos fragmentos de código de ejemplos completos en GitHub para ayudarte a comprender cómo funcionan juntos en tu aplicación.

Conéctate con TCP

Instrucción de invocación del proxy de autenticación de Cloud SQL:

./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAME=tcp:1433 &

Python

Para ver este fragmento en el contexto de una aplicación web, consulta el archivo README en GitHub.

# Remember - storing secrets in plaintext is potentially unsafe. Consider using
# something like https://cloud.google.com/secret-manager/docs/overview to help keep
# secrets secret.
db_user = os.environ["DB_USER"]
db_pass = os.environ["DB_PASS"]
db_name = os.environ["DB_NAME"]
db_host = os.environ["DB_HOST"]

# Extract host and port from environment variable DB_HOST
host_args = db_host.split(":")
db_hostname, db_port = host_args[0], int(host_args[1])

# SQL Server drivers don't account for this
if db_hostname == "localhost":
    db_hostname = "127.0.0.1"

# The SQLAlchemy engine will help manage interactions, including automatically
# managing a pool of connections to your database
pool = sqlalchemy.create_engine(
    # Equivalent URL:
    # mssql+pytds://<db_user>:<db_pass>@/<host>:<port>/<db_name>?driver=ODBC+Driver+17+for+SQL+Server
    sqlalchemy.engine.url.URL.create(
        "mssql+pytds",
        username=db_user,
        password=db_pass,
        database=db_name,
        host=db_hostname,
        port=db_port,
    ),
    **db_config
)

Java

Para ver este fragmento en el contexto de una aplicación web, consulta el archivo README en GitHub.

Nota:

  • CLOUD_SQL_CONNECTION_NAME debe representarse como <MY-PROJECT>:<INSTANCE-REGION>:<INSTANCE-NAME>
  • Con el argumento ipTypes=PRIVATE, se forzará a SocketFactory a la conexión con la IP privada asociada de una instancia
  • Consulta los requisitos de la versión de fábrica de los sockets de JDBC para el archivo pom.xml aquí.

// Note: For Java users, the Cloud SQL JDBC Socket Factory can provide authenticated connections
// which is preferred to using the Cloud SQL Proxy with Unix sockets.
// See https://github.com/GoogleCloudPlatform/cloud-sql-jdbc-socket-factory for details.

// The configuration object specifies behaviors for the connection pool.
HikariConfig config = new HikariConfig();

// The following is equivalent to setting the config options below:
// jdbc:sqlserver://;user=<DB_USER>;password=<DB_PASS>;databaseName=<DB_NAME>;
// socketFactoryClass=com.google.cloud.sql.sqlserver.SocketFactory;
// socketFactoryConstructorArg=<INSTANCE_CONNECTION_NAME>

// See the link below for more info on building a JDBC URL for the Cloud SQL JDBC Socket Factory
// https://github.com/GoogleCloudPlatform/cloud-sql-jdbc-socket-factory#creating-the-jdbc-url

// Configure which instance and what database user to connect with.
config
    .setDataSourceClassName("com.microsoft.sqlserver.jdbc.SQLServerDataSource");
config.setUsername(DB_USER); // e.g. "root", "sqlserver"
config.setPassword(DB_PASS); // e.g. "my-password"
config.addDataSourceProperty("databaseName", DB_NAME);

config.addDataSourceProperty("socketFactoryClass",
    "com.google.cloud.sql.sqlserver.SocketFactory");
config.addDataSourceProperty("socketFactoryConstructorArg", INSTANCE_CONNECTION_NAME);

// ... Specify additional connection properties here.

// ...

// Initialize the connection pool using the configuration object.
DataSource pool = new HikariDataSource(config);

Node.js

Para ver este fragmento en el contexto de una aplicación web, consulta el archivo README en GitHub.

const createPool = async () => {
  const config = {pool: {}, options: {}};

  // Check if a Secret Manager secret version is defined
  // If a version is defined, retrieve the secret from Secret Manager and set as the DB_PASS
  const {CLOUD_SQL_CREDENTIALS_SECRET} = process.env;
  if (CLOUD_SQL_CREDENTIALS_SECRET) {
    const secrets = await accessSecretVersion(CLOUD_SQL_CREDENTIALS_SECRET);
    try {
      process.env.DB_PASS = secrets.toString();
    } catch (err) {
      err.message = `Unable to parse secret from Secret Manager. Make sure that the secret is JSON formatted: \n ${err.message} `;
      throw err;
    }
  }

  config.user = process.env.DB_USER; // e.g. 'my-db-user'
  config.password = process.env.DB_PASS; // e.g. 'my-db-password'
  config.database = process.env.DB_NAME; // e.g. 'my-database'
  // set the server to '172.17.0.1' when connecting from App Engine Flex
  config.server = process.env.DEPLOYED ? '172.17.0.1' : '127.0.0.1';
  config.port = 1433;

  // ...
  config.options.trustServerCertificate = true;
  return await mssql.connect(config);
};

Comienza a usarlo

Para ver este fragmento en el contexto de una aplicación web, consulta el archivo README en GitHub.

var (
	dbUser    = mustGetenv("DB_USER") // e.g. 'my-db-user'
	dbPwd     = mustGetenv("DB_PASS") // e.g. 'my-db-password'
	dbTCPHost = mustGetenv("DB_HOST") // e.g. '127.0.0.1' ('172.17.0.1' if deployed to GAE Flex)
	dbPort    = mustGetenv("DB_PORT") // e.g. '1433'
	dbName    = mustGetenv("DB_NAME") // e.g. 'my-database'
)

dbURI := fmt.Sprintf("server=%s;user id=%s;password=%s;port=%s;database=%s;", dbTCPHost, dbUser, dbPwd, dbPort, dbName)

// dbPool is the pool of database connections.
dbPool, err := sql.Open("mssql", dbURI)
if err != nil {
	return nil, fmt.Errorf("sql.Open: %v", err)
}

// ...

return dbPool, nil

C#

Para ver este fragmento en el contexto de una aplicación web, consulta el archivo README en GitHub.

            // Equivalent connection string:
            // "User Id=<DB_USER>;Password=<DB_PASS>;Server=<DB_HOST>;Database=<DB_NAME>;"
            var connectionString = new SqlConnectionStringBuilder()
            {
                // Remember - storing secrets in plain text is potentially unsafe. Consider using
                // something like https://cloud.google.com/secret-manager/docs/overview to help keep
                // secrets secret.
                DataSource = Environment.GetEnvironmentVariable("DB_HOST"),     // e.g. '127.0.0.1'
                // Set Host to 'cloudsql' when deploying to App Engine Flexible environment
                UserID = Environment.GetEnvironmentVariable("DB_USER"),         // e.g. 'my-db-user'
                Password = Environment.GetEnvironmentVariable("DB_PASS"),       // e.g. 'my-db-password'
                InitialCatalog = Environment.GetEnvironmentVariable("DB_NAME"), // e.g. 'my-database'

                // The Cloud SQL proxy provides encryption between the proxy and instance
                Encrypt = false,
            };
            connectionString.Pooling = true;
            // ...
            return connectionString;

Ruby

Para ver este fragmento en el contexto de una aplicación web, consulta el archivo README en GitHub.

development:
  adapter: sqlserver
  # Configure additional properties here.
  username: <%= ENV["DB_USER"] %>  # e.g. "my-database-user"
  password: <%= ENV["DB_PASS"] %> # e.g. "my-database-password"
  database: <%= ENV.fetch("DB_NAME") { "vote_development" } %>
  host: <%= ENV.fetch("DB_HOST") { "127.0.0.1" }%> # '172.17.0.1' if deployed to GAE Flex
  port: <%= ENV.fetch("DB_PORT") { 1433 }%> 

PHP

Para ver este fragmento en el contexto de una aplicación web, consulta el archivo README en GitHub.

// $username = 'your_db_user';
// $password = 'yoursupersecretpassword';
// $dbName = 'your_db_name';
// $dbHost = "127.0.0.1";

// Connect using TCP
$dsn = sprintf('sqlsrv:server=%s;Database=%s', $dbHost, $dbName);

// Connect to the database
$conn = new PDO($dsn, $username, $password, $connConfig);

Solucionar problemas

Si tienes problemas de conexión, revisa las siguientes páginas para obtener ayuda con la depuración o la solución de problemas conocidos:

¿Qué sigue?