Conéctate a Cloud SQL desde aplicaciones externas

En esta página se describe cómo establecer una conexión con Cloud SQL desde una aplicación que se ejecuta fuera de Google Cloud.

Para obtener información sobre las diversas opciones de conexión a Cloud SQL, consulta la página sobre opciones de conexión para aplicaciones externas. Para obtener información sobre la configuración de la IP pública, consulta Configura la conectividad de IP pública.

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.

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

Puedes conectarte a una instancia de Cloud SQL con los siguientes métodos:

Conéctate desde una aplicación externa con el proxy

Si configuras el proxy de Cloud SQL para un entorno de pruebas local (no de producción), puedes usar la guía de inicio rápido del proxy, en lugar de estas instrucciones.

Si usas los lenguajes de programación Java o Go, tienes algunas alternativas al proxy de Cloud SQL. Más información

1. Habilita la API

Habilita la API de Cloud SQL Admin.

Habilita la API

2. Instala el cliente del proxy en tu máquina local

Linux de 64 bits

  1. Descarga el proxy con el siguiente comando:
    wget https://dl.google.com/cloudsql/cloud_sql_proxy.linux.amd64 -O cloud_sql_proxy
    
  2. Haz que el proxy sea ejecutable con el siguiente comando:
    chmod +x cloud_sql_proxy
    

Linux de 32 bits

  1. Descarga el proxy con el siguiente comando:
    wget https://dl.google.com/cloudsql/cloud_sql_proxy.linux.386 -O cloud_sql_proxy
    
  2. Haz que el proxy sea ejecutable con el siguiente comando:
    chmod +x cloud_sql_proxy
    

macOS de 64 bits

  1. Descarga el proxy con el siguiente comando:
    curl -o cloud_sql_proxy https://dl.google.com/cloudsql/cloud_sql_proxy.darwin.amd64
    
  2. Haz que el proxy sea ejecutable con el siguiente comando:
    chmod +x cloud_sql_proxy
    

macOS de 32 bits

  1. Descarga el proxy con el siguiente comando:
    curl -o cloud_sql_proxy https://dl.google.com/cloudsql/cloud_sql_proxy.darwin.386
    
  2. Haz que el proxy sea ejecutable con el siguiente comando:
    chmod +x cloud_sql_proxy
    

Windows de 64 bits

Para descargar el proxy, haz clic con el botón derecho en https://dl.google.com/cloudsql/cloud_sql_proxy_x64.exe y selecciona Guardar vínculo como. Cambia el nombre del archivo por cloud_sql_proxy.exe.

Windows de 32 bits

Para descargar el proxy, haz clic derecho en https://dl.google.com/cloudsql/cloud_sql_proxy_x86.exe y selecciona Guardar vínculo como. Cambia el nombre del archivo por cloud_sql_proxy.exe.
Si no se incluye aquí tu sistema operativo, también puedes compilar el proxy desde la fuente.

3. Determina cómo autenticar el proxy

Obtén más información sobre las opciones de autenticación del proxy.

4. Si tu método de autenticación lo requiere, crea una cuenta de servicio

Cuando usas una cuenta de servicio a fin de proporcionar credenciales para el proxy, debes crearla con los permisos necesarios. Si usas las funciones más específicas de la administración de identidades y acceso (IAM) para administrar los permisos de Cloud SQL, debes asignar una función que incluya el permiso cloudsql.instances.connect a la cuenta de servicio. Las funciones predefinidas de Cloud SQL que incluyen este permiso son las siguientes:

  • Cliente de Cloud SQL
  • Editor de Cloud SQL
  • Administrador de Cloud SQL

Si usas las funciones de proyecto heredadas (visualizador, editor o propietario), la cuenta de servicio debe tener, al menos, la función de editor.

  1. Ve a la página Cuentas de servicio de Google Cloud Console.

    Ve a la página Cuentas de servicio

  2. Selecciona el proyecto que contiene la instancia de Cloud SQL.
  3. Haz clic en Crear cuenta de servicio.
  4. En el cuadro de diálogo Crear cuenta de servicio, ingresa un nombre descriptivo para la cuenta de servicio.
  5. En Función, selecciona una de las siguientes funciones:
    • Cloud SQL > Cliente de Cloud SQL
    • Cloud SQL > Editor de Cloud SQL
    • Cloud SQL > Administrador de Cloud SQL

    O bien, puedes seleccionar Proyecto > Editor a fin de usar la función básica de editor, pero esta incluye permisos para todo Google Cloud.

    Si no ves estas funciones, es posible que tu usuario de Google Cloud no tenga el permiso resourcemanager.projects.setIamPolicy. Para comprobar tus permisos, accede a la página de IAM en Google Cloud Console y busca tu ID de usuario.

  6. Cambia el ID de cuenta de servicio por un valor único y fácil de reconocer.
  7. Haz clic en Proporcionar una clave privada nueva y confirma que el tipo de clave sea JSON.
  8. Haz clic en Crear.

    El archivo de clave privada se descargará en tu equipo. Puedes moverlo a otra ubicación. Protege el archivo de clave.

5. Define cómo especificar tus instancias para el proxy

Obtén más información sobre las opciones de especificación de instancias del proxy.

6. Inicia el proxy

Las opciones que pasas al proxy dependen de las opciones de especificación de la instancia y la autenticación que elegiste con anterioridad.

Según tu lenguaje y entorno, puedes iniciar el proxy con sockets TCP o con sockets Unix.

Sockets TCP

  1. Copia el nombre de la conexión de la instancia desde la página Detalles de la instancia.

    Por ejemplo: myproject:myregion:myinstance.

  2. Si usas una cuenta de servicio para autenticar el proxy, toma nota de la ubicación en la máquina cliente del archivo de clave privada que se generó cuando creaste la cuenta de servicio.
  3. Inicia el proxy.

    Estas son algunas strings posibles para invocar al proxy:

    • Si usas la autenticación del SDK de Cloud:
      ./cloud_sql_proxy -instances=<INSTANCE_CONNECTION_NAME>=tcp:3306
      
      El puerto especificado no debe estar en uso, por ejemplo, por un servidor de base de datos local.
    • Si usas una cuenta de servicio y también incluyes de forma explícita el nombre de la conexión de la instancia (recomendado para entornos de producción):
      ./cloud_sql_proxy -instances=<INSTANCE_CONNECTION_NAME>=tcp:3306 \
                        -credential_file=<PATH_TO_KEY_FILE> &
      

    Si deseas obtener más información sobre las opciones del proxy, consulta las opciones para autenticar el proxy y las opciones de especificación de instancias.

Sockets Unix

  1. Si usas una especificación de instancia explícita, copia el nombre de la conexión de tu instancia que aparece en la página Detalles de la instancia.
  2. Crea el directorio donde se alojarán los sockets del proxy:
    sudo mkdir /cloudsql; sudo chmod 777 /cloudsql
  3. Si usas una cuenta de servicio para autenticar el proxy, toma nota de la ubicación del archivo de claves privadas que se generó en la máquina cliente cuando creaste la cuenta de servicio.
  4. Abre una ventana de terminal nueva y, luego, inicia el proxy.

    Estas son algunas strings posibles para invocar al proxy:

    • Si usas una cuenta de servicio y también incluyes de forma explícita el nombre de la conexión de la instancia (recomendado para entornos de producción):
      ./cloud_sql_proxy -dir=/cloudsql -instances=<INSTANCE_CONNECTION_NAME> \
                        -credential_file=<PATH_TO_KEY_FILE> &
    • Si usas la autenticación del SDK de Cloud y la detección automática de instancias:
      ./cloud_sql_proxy -dir=/cloudsql &

    Se recomienda iniciar el proxy en su propia terminal para que puedas supervisar los resultados sin que se mezclen con los de otros programas.

    Si deseas obtener más información sobre las opciones del proxy, consulta las opciones para autenticar el proxy y las opciones de especificación de instancias.

  5. Cuando uses un socket Unix para conectarte a Cloud SQL con el proxy de Cloud SQL, asegúrate de que la longitud del nombre del socket no supere el límite del sistema. Esto depende del sistema, pero suele tener entre 91 y 108 caracteres. En Linux, la longitud se suele definir como 108, y puedes usar el siguiente comando para verificar:
    cat /usr/include/linux/un.h | grep "define UNIX_PATH_MAX"

7. Actualiza tu aplicación para conectarte a Cloud SQL con el proxy

La instrucción del código exacto requerido para usar el proxy y conectarte a tu instancia de Cloud SQL depende del lenguaje y del marco de trabajo que uses.

Debes conectarte al proxy de la misma manera que lo harías a un socket TCP o Unix (según cómo invocaste el proxy):

Sockets TCP

Con sockets TCP, el proxy está disponible como un host local:

127.0.0.1:3306

Sockets Unix

Con los sockets Unix, el proxy está disponible con la siguiente ruta de acceso:

PROXY_PATH/INSTANCE_CONNECTION_NAME;
Donde PROXY_PATH es la ruta de acceso al directorio que estableciste con la opción -dir cuando iniciaste el proxy. En los ejemplos en esta documentación, se usa /cloudsql. Puedes encontrar el nombre de conexión de tu instancia en la página Detalles de la instancia en Google Cloud Console o usar PROJECT-ID:REGION:INSTANCE_NAME.

¿Necesitas ayuda? Para solucionar problemas del proxy, consulta Cómo solucionar problemas de conexión del proxy de Cloud SQL. También puedes consultar nuestra página de asistencia de Cloud SQL.

Información específica del lenguaje y ejemplos

Puedes conectarte al proxy desde cualquier lenguaje que permita conectarte a un socket Unix o TCP. A continuación, se muestran algunas instrucciones de invocación y conexión de muestra que te ayudarán a comprender cómo funcionan en conjunto en tu aplicación.

.NET

Después de iniciar el proxy, edita el archivo appsettings.json y define una string de conexión en CloudSql:ConnectionString. Por ejemplo:

{
  "CloudSQL" : {
     ConnectionString": "Host=127.0.0.1;Uid=DATABASE_USER;Pwd=PASSWORD;Database=DATABASE_NAME"
  }
}

Luego, en el archivo Startup.cs, crea una conexión de base de datos:

var connectionString = new MySqlConnectionStringBuilder(
    Configuration["CloudSql:ConnectionString"])
{
    // Connecting to a local proxy that does not support ssl.
    SslMode = MySqlSslMode.None,
};
DbConnection connection =
    new MySqlConnection(connectionString.ConnectionString);

Go

Puedes usar el proxy de Cloud SQL con el lenguaje de programación Go de dos maneras:

  1. Mediante la biblioteca del proxy de Go
  2. Mediante la ejecución del proxy como un proceso complementario

Biblioteca del proxy de Go

La biblioteca proporciona la forma más fácil de conectarse a Cloud SQL desde un programa de Go, ya que no necesitas iniciar de manera explícita el proxy como su propio proceso.

import (
    "github.com/GoogleCloudPlatform/cloudsql-proxy/proxy/dialers/mysql"
)
...
cfg := mysql.Cfg(INSTANCE_CONNECTION_NAME, DATABASE_USER, PASSWORD)
cfg.DBName = DATABASE_NAME
db, err := mysql.DialCfg(cfg)

Para obtener más información, consulta la página GitHub del proxy de Cloud SQL.

Proceso complementario

También puedes ejecutar el proxy como un proceso complementario y conectarlo desde tu aplicación.

En las instrucciones de invocación de proxy a continuación se usa la autenticación del SDK de Cloud local para abreviar. Tu instrucción de invocación puede variar según cómo autentiques y especifiques tus instancias. Para obtener más información, consulta esta sección sobre las opciones para autenticar el proxy de Cloud SQL.

Sockets TCP

Instrucción de invocación del proxy:

./cloud_sql_proxy -instances=[INSTANCE_CONNECTION_NAME]=tcp:3306 &

Instrucción de conexión:

import (
       "database/sql"
        _ "github.com/go-sql-driver/mysql"
)

dsn := fmt.Sprintf("%s:%s@tcp(%s)/%s",
       DATABASE_USER,
       PASSWORD,
       "127.0.0.1:3306",
       DATABASE_NAME)
db, err := sql.Open("mysql", dsn)

Sockets Unix

Instrucción de invocación del proxy:

./cloud_sql_proxy -instances=[INSTANCE_CONNECTION_NAME] -dir=/cloudsql &

Instrucción de conexión:

import (
       "database/sql"
        _ "github.com/go-sql-driver/mysql"
)

dsn := fmt.Sprintf("%s:%s@unix(/cloudsql/%s)/%s",
       DATABASE_USER,
       PASSWORD,
       INSTANCE_CONNECTION_NAME,
       DATABASE_NAME)
db, err := sql.Open("mysql", dsn)

Java

El lenguaje de programación Java no proporciona compatibilidad nativa con los sockets Unix. Puedes usar sockets TCP o una biblioteca que proporcione compatibilidad para sockets Unix con el proxy de Cloud SQL, pero la forma más fácil de conectarte a una instancia de segunda generación sin agregar direcciones de red autorizadas es usar la fábrica de sockets de JDBC.

La fábrica de sockets de JDBC proporciona una alternativa al software de proxy del lado del cliente y requiere que habilites la API de Administrador de Cloud SQL, al igual que el proxy de Cloud SQL. La fábrica de sockets proporciona el mismo nivel de encriptación que el proxy y se autentica con las credenciales del SDK de Cloud. Debes instalar y autenticar el SDK de Cloud antes de usar la fábrica de sockets.

Consulta los controladores JDBC para la fábrica de sockets de Cloud SQL a fin de obtener ejemplos de código. Revisa el README para obtener instrucciones.

PHP

PDO y TCP

Invoca el proxy:

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

En los siguientes ejemplos, se establece una conexión a Cloud SQL con objetos de datos PHP (PDO):

// Use a Data source name (DSN) to connect to Cloud SQL through the proxy
$dsn = 'mysql:host=127.0.0.1;port=3306;dbname=DATABASE_NAME';
// Instantiate your DB using the DSN, username, and password
$dbUser = 'DATABASE_USER';
$dbPass = 'PASSWORD';
$db = new PDO($dsn, $dbUser, $dbPass);

Sockets Unix y PDO

Invoca el proxy:

./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAME -dir=/cloudsql &

En los siguientes ejemplos, se establece una conexión a Cloud SQL con PDO:

// Use a Data source name (DSN) to connect to Cloud SQL through the proxy
$dsn = sprintf('mysql:unix_socket=/cloudsql/INSTANCE_CONNECTION_NAME;dbname=DATABASE_NAME';
// Instantiate your DB using the DSN, username, and password
$dbUser = 'DATABASE_USER';
$dbPass = 'PASSWORD';
$db = new PDO($dsn, $dbUser, $dbPass);

mysqli y TCP

Invoca el proxy:

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

En los siguientes ejemplos, se establece una conexión a Cloud SQL mediante mysqli:

// Instantiate your DB using the database host, port, name, username, and password
$dbName = 'DATABASE_NAME';
$dbUser = 'DATABASE_USER';
$dbPass = 'PASSWORD';
$mysqli = new mysqli('127.0.0.1', $dbUser, $dbPass, $dbName, 3306);

Sockets Unix y mysqli

Invoca el proxy:

./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAME -dir=/cloudsql &

En los siguientes ejemplos, se establece una conexión a Cloud SQL mediante mysqli:

// Instantiate your DB using the database name, socket, username, and password
$dbName = 'DATABASE_NAME';
$dbUser = 'DATABASE_USER';
$dbPass = 'PASSWORD';
$dbSocket = '/cloudsql/INSTANCE_CONNECTION_NAME';
$mysqli = new mysqli(null, $dbUser, $dbPass, $dbName, null, $dbSocket);

Ruby

mysql2 y TCP

Invoca el proxy:

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

En los siguientes ejemplos, se establece una conexión a Cloud SQL mediante la RubyGem mysql2:

require "mysql2"
client = Mysql2::Client.new host: "127.0.0.1", port: 3306,
    database: "DATABASE_NAME", username: "DATABASE_USER",
    password: "PASSWORD"

Sockets Unix y mysql2

Invoca el proxy:

./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAME -dir=/cloudsql &

En los siguientes ejemplos, se establece una conexión a Cloud SQL mediante la RubyGem mysql2:

require "mysql2"
client = Mysql2::Client.new socket: "/cloudsql/CONNECTION_NAME",
    database: "DATABASE_NAME", username: "DATABASE_USER",
    password: "PASSWORD"

Rails y TCP

Invoca el proxy:

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

En config/databases.yml, usa la siguiente configuración:

mysql_settings: &mysql_settings
  adapter: mysql2
  encoding: utf8
  pool: 5
  username: DATABASE_USER
  password: PASSWORD
  database: DATABASE_NAME
  host: 127.0.0.1:3306

Rails y sockets Unix

Invoca el proxy:

./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAME -dir=/cloudsql &

En config/databases.yml, usa la siguiente configuración:

mysql_settings: &mysql_settings
  adapter: mysql2
  encoding: utf8
  pool: 5
  username: DATABASE_USER
  password: PASSWORD
  database: DATABASE_NAME
  socket: /cloudsql/INSTANCE_CONNECTION_NAME

Configura el acceso para conexiones IP públicas

Puedes otorgar a cualquier aplicación acceso a la instancia de Cloud SQL mediante la autorización de direcciones IP públicas que la aplicación usa para conectarse.

No puedes especificar una red privada (por ejemplo, 10.x.x.x) como una red autorizada.

Direcciones IP públicas para instancias de MySQL:

  • IPv6: Las instancias no admiten IPv6.
  • IPv4: Las instancias tienen una dirección IPv4 estática que se les asigna de forma automática. Se realiza un cobro menor por la dirección IP cada vez que se apaga tu instancia (se desactiva).

Para configurar el acceso mediante conexiones IP públicas, sigue estos pasos:

Console

  1. Define la dirección IP de tu aplicación. Obtén más información.
  2. Autoriza la dirección IP de tu aplicación para conectarte a tu instancia.

    Para obtener más información, consulta la sección Cómo habilitar la IP pública y agregar una dirección o rango de direcciones autorizados.

  3. Puedes encontrar la dirección IP asignada a tu instancia en su página Detalles de la instancia. Este es el valor que necesitas para la string de conexión de tu aplicación.

gcloud

  1. Define la dirección IP de tu máquina cliente. Obtén más información.
  2. Autoriza la dirección IP de tu aplicación para conectarte a tu instancia.

    Para obtener más información, consulta la sección Cómo habilitar la IP pública y agregar una dirección o rango de direcciones autorizados.

  3. Recupera la dirección IP de la instancia:
    gcloud sql instances describe [INSTANCE_NAME]
    

    En el resultado, busca el campo ipAddress. Este es el valor que necesitas para la string de conexión de tu aplicación.

cURL

  1. Define la dirección IP de tu aplicación. Obtén más información.
  2. Autoriza la dirección IP de tu aplicación para conectarte a tu instancia.

    Para obtener más información, consulta la sección Cómo habilitar la IP pública y agregar una dirección o rango de direcciones autorizados.

  3. Recupera la dirección IP de la instancia:
    gcloud auth login
    ACCESS_TOKEN="$(gcloud auth print-access-token)"
    curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
           -X GET \
           https://www.googleapis.com/sql/v1beta4/projects/[PROJECT-ID]/instances/[INSTANCE_NAME]
    

    Toma nota del valor de ipAddresses.ipAddress (para IPv4). Este es el valor que necesitas para la string de conexión de la aplicación.

¿Necesitas ayuda? Para solucionar problemas del proxy, consulta Cómo solucionar problemas de conexión del proxy de Cloud SQL. También puedes consultar nuestra página de asistencia de Cloud SQL.

Configura el acceso para las aplicaciones con direcciones IP asignadas de forma dinámica

Algunas aplicaciones necesitan conectarse a tu instancia de Cloud SQL con una dirección IP asignada de forma dinámica o efímera. Este es el caso de las aplicaciones de plataforma como servicio (PaaS), entre otras.

La mejor solución para estas aplicaciones es conectarse mediante el proxy de Cloud SQL. Esta solución proporciona el mejor control de acceso para la instancia.

Prueba la conexión

Puedes usar el cliente MySQL a fin de probar tu capacidad de conexión desde tu entorno local. Si quieres obtener más información, consulta Conecta un cliente MySQL mediante una dirección IP pública y la página sobre cómo conectar el cliente MySQL con el proxy de Cloud SQL.

¿Necesitas ayuda? Para solucionar problemas del proxy, consulta Cómo solucionar problemas de conexión del proxy de Cloud SQL. También puedes consultar nuestra página de asistencia de Cloud SQL.

Cómo definir la dirección IP de tu aplicación

Para definir la dirección IP de una computadora que ejecuta tu aplicación a fin de que puedas autorizar el acceso a tu instancia de Cloud SQL desde esa dirección, debes usar una de las siguientes opciones:

  • Si la computadora no se encuentra detrás de un proxy, accede a esta y usa este vínculo para definir su dirección IP.
  • Si la computadora se encuentra detrás de un proxy, accede a esta y usa una herramienta o servicio como whatismyipaddress.com para definir su dirección IP verdadera.

Qué sigue