Conectar-se ao cliente MySQL no Compute Engine

Nesta página, descrevemos como usar o cliente mysql, instalado em uma instância do Compute Engine, para se conectar ao Cloud SQL.

Use o IP particular, o IP público, o Cloud SQL Proxy ou a imagem Docker de proxy.

Antes de começar

Antes de estabelecer uma conexão com a instância do Cloud SQL, é necessário ter um usuário padrão (root) do banco de dados na instância.

Essa tarefa não inclui instruções para a configuração da instância do Google Compute Engine. Se você precisar de ajuda para criar e configurar uma instância do Google Compute Engine, consulte a documentação do Google Compute Engine.

IP particular

Para se conectar ao Cloud SQL por uma instância do Compute Engine usando IP particular, o acesso a serviços particulares precisa ser configurado para o ambiente, e a instância do Cloud SQL precisa ser configurada para usar IP particular. A instância do Compute Engine precisa estar na mesma região da instância do Cloud SQL e na rede configurada para uma conexão particular. Saiba mais.

1. Configure a instância para usar IP privado

Siga as instruções em Como configurar a conectividade do IP privado.

2. Abra uma conexão de terminal com a instância do Compute Engine.

Use as instruções apropriadas, dependendo do sistema operacional da instância:

Se a instância do Compute Engine estiver executando uma imagem pública do RHEL ou do CentOS, o SELinux poderá bloquear a conexão de proxy. Se isso acontecer, será necessário configurar o recurso SELinux para permitir a conexão.

Para mais informações sobre o SELinux para RHEL, consulte a documentação do RHEL (em inglês). Para mais informações sobre o SELinux para CentOS, consulte a documentação do CentOS (em inglês).

3. Instale o cliente mysql na instância do Compute Engine, se ele ainda não estiver instalado.

Debian/Ubuntu

Instale o cliente MySQL pelo gerenciador de pacotes:

sudo apt-get update
sudo apt-get install mariadb-server-10.3

CentOS/RHEL

Instale o cliente MySQL pelo gerenciador de pacotes:

sudo yum install mysql

openSUSE

Instale o cliente MySQL pelo gerenciador de pacotes:

sudo zypper install mysql-server

Outras plataformas

  1. Faça o download do MySQL Community Server referente à sua plataforma da página de downloads do MySQL Community Server (em inglês).
    O Community Server inclui o cliente MySQL.
  2. Instale o Community Server, seguindo as instruções na página de downloads.

Para mais informações sobre a instalação do MySQL, consulte Instalação e upgrade do MySQL (em inglês) no Manual de referência do MySQL.

4. Estabeleça conexão com o cliente mysql.

mysql --host=[CLOUD_SQL_PRIVATE_IP_ADDR] --user=root --password

IP público

Para se conectar usando IP público:

1. Adicione um endereço IPv4 estático à instância do Compute Engine, se ela ainda não tiver um.

Não é possível estabelecer uma conexão com o Compute Engine usando IPv6. Para informações sobre como adicionar um endereço IP estático, consulte Como reservar um novo endereço IP externo estático na documentação do Compute Engine.

2. Autorize o endereço IP estático da instância do Compute Engine como uma rede com permissão para conectar-se à instância do Cloud SQL.

Para mais informações, consulte Como configurar o acesso para conexões IP públicas.

3. Abra uma conexão de terminal com a instância do Compute Engine.

Use as instruções apropriadas, dependendo do sistema operacional da instância:

Se a instância do Compute Engine estiver executando uma imagem pública do RHEL ou do CentOS, o SELinux poderá bloquear a conexão de proxy. Se isso acontecer, será necessário configurar o recurso SELinux para permitir a conexão.

Para mais informações sobre o SELinux para RHEL, consulte a documentação do RHEL (em inglês). Para mais informações sobre o SELinux para CentOS, consulte a documentação do CentOS (em inglês).

4. Instale o cliente mysql na instância do Compute Engine, se ele ainda não estiver instalado.

Debian/Ubuntu

Instale o cliente MySQL pelo gerenciador de pacotes:

sudo apt-get update
sudo apt-get install mariadb-server-10.3

CentOS/RHEL

Instale o cliente MySQL pelo gerenciador de pacotes:

sudo yum install mysql

openSUSE

Instale o cliente MySQL pelo gerenciador de pacotes:

sudo zypper install mysql-server

Outras plataformas

  1. Faça o download do MySQL Community Server referente à sua plataforma da página de downloads do MySQL Community Server (em inglês).
    O Community Server inclui o cliente MySQL.
  2. Instale o Community Server, seguindo as instruções na página de downloads.

Para mais informações sobre a instalação do MySQL, consulte Instalação e upgrade do MySQL (em inglês) no Manual de referência do MySQL.

5. Estabeleça conexão com o cliente mysql.

mysql --host=[CLOUD_SQL_PUBLIC_IP_ADDR] --user=root --password
Run the following gcloud command to find the CLOUD_SQL_PUBLIC_IP_ADDR:

gcloud sql instances list

Para um exemplo de como estabelecer uma conexão usando SSL, consulte Como se conectar com SSL.

6. O prompt do mysql é exibido.

7. Se você precisar manter as conexões não utilizadas ativas:

Configure o TCP keepalive.

Para mais informações, consulte Como estabelecer comunicação entre as suas instâncias e a Internet na documentação do Compute Engine.

As conexões são mantidas ativas automaticamente para instâncias.

Cloud SQL Proxy

Para se conectar usando o proxy do Compute Engine:

1. Ative a API Cloud SQL Admin.

Ative a API

2. Crie uma conta de serviço.

  1. Acesse a página Contas de serviço no Console do Google Cloud.

    Acessar a página "Contas de serviço"

  2. Selecione o projeto que contém a instância do Cloud SQL.
  3. Clique em Criar conta de serviço.
  4. Na caixa de diálogo Criar conta de serviço, forneça um nome descritivo para a conta.
  5. Em Papel, selecione um dos seguintes papéis:
    • Cloud SQL > Cliente do Cloud SQL
    • Cloud SQL > Editor do Cloud SQL
    • Cloud SQL > Administrador do Cloud SQL
  6. Altere o ID da conta de serviço para um valor exclusivo e facilmente reconhecível.
  7. Clique em Fornecer uma nova chave privada e confirme se o tipo de chave é JSON.
  8. Clique em Criar

    O arquivo da chave privada é transferido para sua máquina. Você pode movê-lo para outro local. Mantenha-o protegido.

Se a instância do Google Compute Engine estiver em um projeto diferente da instância do Cloud SQL, verifique se a respectiva conta de serviço tem as permissões adequadas no projeto que contém a instância do Cloud SQL:

  1. Acesse a listagem de instâncias do Compute Engine no Console do Google Cloud.

    Acessar a listagem de instâncias do Compute Engine

  2. Se necessário, selecione o projeto associado à instância do Compute Engine.
  3. Selecione a instância do Compute Engine para exibir as propriedades dela.
  4. Nas propriedades da instância do Compute Engine, copie o nome da conta de serviço.
  5. Acesse a página Projetos do IAM e do administrador no Console do Google Cloud.

    Acessar a página "Projetos do IAM e do administrador"

  6. Selecione o projeto que contém a instância do Cloud SQL.
  7. Procure o nome da conta de serviço.
  8. Se a conta de serviço já estiver lá e tiver um papel que inclua a permissão cloudsql.instances.connect, prossiga para a etapa 4.

    Os papéis Cloud SQL Client, Cloud SQL Editor e Cloud SQL Admin fornecem a permissão necessária, assim como os papéis de projeto Editor e Owner herdados.

  9. Caso contrário, clique em Adicionar para adicioná-la.
  10. Na caixa de diálogo Adicionar membros , forneça o nome da conta de serviço e selecione uma função que inclua a permissão cloudsql.instances.connect (qualquer papel predefinido do Cloud SQL que não seja o Leitor funcionará).

    Como alternativa, é possível usar o papel básico de Editor ao selecionar Projeto > Editor. No entanto, ele inclui permissões em todo o Google Cloud.

    Caso não veja esses papéis, talvez o usuário do Google Cloud não tenha a permissão resourcemanager.projects.setIamPolicy. Para verificar suas permissões, acesse a página do IAM no Console do Google Cloud e pesquise seu ID de usuário.

  11. Clique em Add.

    Você verá a conta de serviço listada com o papel especificado.

3. Abra uma conexão de terminal com a instância do Compute Engine.

Use as instruções apropriadas, dependendo do sistema operacional da instância:

Se a instância do Compute Engine estiver executando uma imagem pública do RHEL ou do CentOS, o SELinux poderá bloquear a conexão de proxy. Se isso acontecer, será necessário configurar o recurso SELinux para permitir a conexão.

Para mais informações sobre o SELinux para RHEL, consulte a documentação do RHEL (em inglês). Para mais informações sobre o SELinux para CentOS, consulte a documentação do CentOS (em inglês).

4. Instale o cliente mysql na instância do Compute Engine, se ele ainda não estiver instalado.

Debian/Ubuntu

Instale o cliente MySQL pelo gerenciador de pacotes:

sudo apt-get update
sudo apt-get install mariadb-server-10.3

CentOS/RHEL

Instale o cliente MySQL pelo gerenciador de pacotes:

sudo yum install mysql

openSUSE

Instale o cliente MySQL pelo gerenciador de pacotes:

sudo zypper install mysql-server

Outras plataformas

  1. Faça o download do MySQL Community Server referente à sua plataforma da página de downloads do MySQL Community Server (em inglês).
    O Community Server inclui o cliente MySQL.
  2. Instale o Community Server, seguindo as instruções na página de downloads.

Para mais informações sobre a instalação do MySQL, consulte Instalação e upgrade do MySQL (em inglês) no Manual de referência do MySQL.

5. Instale o Cloud SQL Proxy na instância do Compute Engine.

Linux de 64 bits

  1. Faça o download do proxy:
    wget https://dl.google.com/cloudsql/cloud_sql_proxy.linux.amd64 -O cloud_sql_proxy
    
  2. Torne o proxy executável:
    chmod +x cloud_sql_proxy
    

Linux de 32 bits

  1. Faça o download do proxy:
    wget https://dl.google.com/cloudsql/cloud_sql_proxy.linux.386 -O cloud_sql_proxy
    
  2. Torne o proxy executável:
    chmod +x cloud_sql_proxy
    

Windows de 64 bits

Para fazer o download do proxy, clique com o botão direito em https://dl.google.com/cloudsql/cloud_sql_proxy_x64.exe e selecione Salvar link como. Renomeie o arquivo para cloud_sql_proxy.exe.

Windows de 32 bits

Para fazer o download do proxy, clique com o botão direito em https://dl.google.com/cloudsql/cloud_sql_proxy_x86.exe e selecione Salvar link como. Renomeie o arquivo para cloud_sql_proxy.exe.

Imagem de proxy do Docker

Por conveniência, a equipe do Cloud SQL mantém várias imagens de contêiner que contêm o Cloud SQL Proxy para uso pelos nossos clientes. Para mais informações sobre essas imagens, consulte o repositório do Cloud SQL Proxy no GitHub. É possível extrair a imagem mais recente na sua máquina local usando o Docker com o seguinte comando:
docker pull gcr.io/cloudsql-docker/gce-proxy:1.19.1

Outros SOs

Para outros sistemas operacionais não incluídos aqui, compile o proxy a partir da fonte.

6. Inicie o proxy.

Dependendo da linguagem e do ambiente, é possível iniciar o proxy usando soquetes TCP, soquetes Unix ou a imagem do proxy do Docker. O binário de proxy se conecta a uma ou mais instâncias do Cloud SQL especificadas na linha de comando e abre uma conexão local como TCP ou um soquete Unix. Outros aplicativos e serviços, como o código do aplicativo ou as ferramentas de cliente de gerenciamento de banco de dados, podem se conectar a instâncias do Cloud SQL por meio dessas conexões de soquete TCP ou Unix.

Sockets TCP

Para conexões TCP, o proxy detecta em localhost (127.0.0.1) por padrão. Portanto, quando você especifica tcp:PORT_NUMBER para uma instância, a conexão local é em 127.0.0.1:PORT_NUMBER.

Como alternativa, você pode especificar um endereço diferente para a conexão local. Por exemplo, veja como fazer o proxy detectar a conexão local em 0.0.0.0:1234:

  ./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAME=tcp:0.0.0.0:1234
  1. Copie o INSTANCE_CONNECTION_NAME. Isso pode ser encontrado na página Visão geral da instância no Console do Google Cloud ou executando o seguinte comando:

    gcloud sql instances describe INSTANCE_NAME
    .

    Por exemplo, myproject:myregion:myinstance.

  2. Se a instância tiver IP público e particular configurados e você quiser que o proxy use o endereço IP particular, forneça a seguinte opção ao iniciar o proxy:
    -ip_address_types=PRIVATE
  3. Se você estiver usando uma conta de serviço para autenticar o proxy, anote o local em que a chave privada foi criada na máquina cliente durante a criação da conta de serviço.
  4. Inicie o proxy.

    Algumas strings possíveis de chamada do proxy:

    • Usando autenticação do SDK do Cloud:
      ./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAME=tcp:3306
      
      A porta especificada não pode estar em uso, por exemplo, por um servidor de banco de dados local.
    • Usar uma conta de serviço e incluir explicitamente o nome da conexão da instância (recomendado para ambientes de produção):
      ./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAM=tcp:3306 \
                        -credential_file=PATH_TO_KEY_FILE &
      

    Para mais informações sobre as opções de proxy, consulte Opções para autenticar o proxy e Opções para especificar instâncias.

Sockets Unix

O Cloud SQL Proxy também pode detectar em um soquete Unix, que é um mecanismo padrão do Posix para usar uma pasta para gerenciar a comunicação entre dois processos em execução no mesmo host. As vantagens de usar soquetes Unix são a segurança aprimorada e a latência menor. No entanto, não é possível acessar um soquete Unix de uma máquina externa.

Para criar e usar um soquete Unix, o diretório de destino precisa existir e o proxy e o aplicativo precisam ter acesso de leitura e gravação a ele.

  1. Se você estiver usando a especificação explícita de instâncias, copie a INSTANCE_CONNECTION_NAME. Isso pode ser encontrado na página Visão geral da instância no Console do Google Cloud ou executando o seguinte comando:

    gcloud sql instances describe INSTANCE_NAME
    .

    Por exemplo, myproject:myregion:myinstance.

  2. Crie o diretório em que os soquetes do proxy ficarão:
    sudo mkdir /cloudsql; sudo chmod 777 /cloudsql
  3. Se você estiver usando uma conta de serviço para autenticar o proxy, anote o local em que a chave privada foi criada na máquina cliente durante a criação da conta de serviço.
  4. Abra uma nova janela de terminal e inicie o proxy.

    Algumas strings possíveis de chamada do proxy:

    • Usando uma conta de serviço e incluindo explicitamente o nome da conexão da instância (recomendado para ambientes de produção):
      ./cloud_sql_proxy -dir=/cloudsql -instances=INSTANCE_CONNECTION_NAME
      -credential_file=PATH_TO_KEY_FILE &
    • Usando a autenticação do Cloud SDK e a descoberta automática de instância:
      ./cloud_sql_proxy -dir=/cloudsql &

    É melhor iniciar o proxy em seu próprio terminal, assim você pode monitorar as respostas dele sem misturá-las com as respostas de outros programas.

    Para mais informações sobre as opções de proxy, consulte Opções para autenticar o proxy e Opções para especificar instâncias.

Imagem do proxy Docker

Para executar o Cloud SQL Proxy em um contêiner do Docker, use a imagem do Proxy Docker disponível no Google Container Registry.

Você pode iniciar o proxy usando soquetes TCP ou soquetes Unix, com os comandos mostrados abaixo. As opções usam uma INSTANCE_CONNECTION_NAME como a string de conexão para identificar uma instância do Cloud SQL. Encontre o INSTANCE_CONNECTION_NAME na Visão geral da sua instância no Google Cloud Console ou executando o comando a seguir:

gcloud sql instances describe INSTANCE_NAME
.

Por exemplo, myproject:myregion:myinstance.

Dependendo da linguagem e do ambiente, inicie o proxy usando os soquetes TCP ou Unix. Os soquetes Unix não são compatíveis com aplicativos desenvolvidos na linguagem de programação Java ou com o ambiente Windows.

Como usar soquetes TCP

docker run -d \\
  -v PATH_TO_KEY_FILE:/config \\
  -p 127.0.0.1:3306:3306 \\
  gcr.io/cloudsql-docker/gce-proxy:1.19.1 /cloud_sql_proxy \\
  -instances=INSTANCE_CONNECTION_NAME=tcp:0.0.0.0:3306 -credential_file=/config

Se você usa as credenciais fornecidas pela instância do Compute Engine, não inclua o parâmetro credential_file e a linha -v PATH_TO_KEY_FILE:/config.

Sempre especifique o prefixo 127.0.0.1 em "-p" para que o proxy não seja exposto fora do host local. O "0.0.0.0" no parâmetro das instâncias é necessário para tornar a porta acessível de fora do contêiner do Docker.

Como usar soquetes Unix

docker run -d -v /cloudsql:/cloudsql \\
  -v PATH_TO_KEY_FILE:/config \\
  gcr.io/cloudsql-docker/gce-proxy:1.19.1 /cloud_sql_proxy -dir=/cloudsql \\
  -instances=INSTANCE_CONNECTION_NAME -credential_file=/config

Se você usa as credenciais fornecidas pela instância do Compute Engine, não inclua o parâmetro credential_file e a linha -v PATH_TO_KEY_FILE:/config.

Se você usa uma imagem otimizada para contêiner, utilize um diretório gravável em vez de /cloudsql. Por exemplo:

-v /mnt/stateful_partition/cloudsql:/cloudsql

É possível especificar mais de uma instância, separadas por vírgulas. Também é possível usar metadados do Compute Engine para determinar dinamicamente a quais instâncias se conectar. Saiba mais sobre os parâmetros de proxy.

7. Inicie a sessão mysql.

A string da conexão usada depende de como você iniciou o proxy: usando um soquete TCP, um soquete Unix ou o docker.

Sockets TCP

  1. Inicie o cliente MySQL:
    mysql -u USERNAME -p --host 127.0.0.1
    

    Quando você estabelece a conexão com sockets TCP, o endereço de acesso do proxy é 127.0.0.1.

  2. Se solicitado, digite a senha.
  3. O prompt do mysql é exibido.

Como usar soquetes Unix

  1. Inicie o cliente MySQL:
    mysql -u USERNAME -p -S /cloudsql/INSTANCE_CONNECTION_NAME
    
  2. Digite a senha.
  3. O prompt do mysql é exibido.

Precisa de ajuda? Para ajuda na solução de problemas com o proxy, consulte Como solucionar problemas nas conexões do Cloud SQL Proxy ou veja a página de suporte do Cloud SQL.

Próximas etapas