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.

É possível usar o IP particular, o IP público, o proxy do Cloud SQL Auth ou a imagem do Docker do proxy do Cloud SQL Auth.

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.

  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 Como instalar e fazer upgrade 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:


Para orientações passo a passo sobre esta tarefa diretamente no editor do Cloud Shell, clique em Orientações:

Orientações


As seções a seguir guiam você pelas mesmas etapas que você encontra clicando em Orientações.

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.

  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 Como instalar e fazer upgrade 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.

Proxy do Cloud SQL Auth

Para se conectar-usando o proxy do Cloud SQL Auth a partir 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. Altere o ID da conta de serviço para um valor exclusivo e reconhecível e, em seguida, clique em Criar.
  6. Em Papel, selecione um dos seguintes papéis, clique em Continuar e em Concluído:
    • Cloud SQL > Cliente do Cloud SQL
    • Cloud SQL > Editor do Cloud SQL
    • Cloud SQL > Administrador do Cloud SQL
  7. Clique no menu de ações da sua nova conta de serviço e selecione Gerenciar chaves.
  8. Clique no menu suspenso Adicionar chave e clique em Criar nova chave.
  9. Confirme se o tipo de chave é JSON e 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.

  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 Como instalar e fazer upgrade do MySQL.

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

Linux de 64 bits

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

Linux de 32 bits

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

Windows de 64 bits

Clique com o botão direito do mouse em https://dl.google.com/cloudsql/cloud_sql_proxy_x64.exe e selecione Salvar link como para fazer o download do proxy do Cloud SQL Auth. Renomeie o arquivo para cloud_sql_proxy.exe.

Windows de 32 bits

Clique com o botão direito do mouse em https://dl.google.com/cloudsql/cloud_sql_proxy_x86.exe e selecione Salvar link como para fazer o download do proxy do Cloud SQL Auth. Renomeie o arquivo para cloud_sql_proxy.exe.

Imagem do Docker do proxy do Cloud SQL Auth

Por conveniência, várias imagens de contêiner que contêm o proxy do Cloud SQL Auth estão disponíveis no GitHub no repositório do proxy do Cloud SQL Auth. É 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 do Cloud SQL Auth da origem.

6. Iniciar o proxy do Cloud SQL Auth.

Dependendo da linguagem e do ambiente, é possível iniciar o proxy do Cloud SQL Auth usando soquetes TCP, soquetes Unix ou a imagem do Docker do proxy Cloud SQL Auth. O binário de proxy do Cloud SQL Auth se conecta a uma ou mais instâncias do Cloud SQL especificadas na linha de comando e abre uma conexão local tanto como um soquete TCP como um 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 do Cloud SQL Auth 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 do Cloud SQL Auth detectar em 0.0.0.0:1234 para a conexão local:

  ./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 do Cloud SQL Auth use o endereço IP particular, forneça a opção a seguir ao iniciar o proxy do Cloud SQL Auth:
    -ip_address_types=PRIVATE
  3. Se você estiver usando uma conta de serviço para autenticar o proxy do Cloud SQL Auth, anote o local em que o arquivo da chave privada foi criado na máquina do cliente durante a criação da conta de serviço.
  4. Iniciar o proxy do Cloud SQL Auth.

    Algumas strings possíveis de invocação do proxy do Cloud SQL Auth:

    • 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 do Cloud SQL Auth, consulte Opções para autenticar o proxy do Cloud SQL Auth e Opções para especificar instâncias.

Sockets Unix

O proxy do Cloud SQL Auth também pode detectar em um soquete Unix, mecanismo padrão do Posix para usar uma pasta que gerencia 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 do Cloud SQL Auth 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 onde ficarão os soquetes do proxy do Cloud SQL Auth:
    sudo mkdir /cloudsql; sudo chmod 777 /cloudsql
  3. Se você estiver usando uma conta de serviço para autenticar o proxy do Cloud SQL Auth, anote o local em que o arquivo da chave privada foi criado na máquina do cliente durante a criação da conta de serviço.
  4. Abra uma nova janela do terminal e inicie o proxy do Cloud SQL Auth.

    Algumas strings possíveis de invocação do proxy do Cloud SQL Auth:

    • 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 -dir=/cloudsql -instances=INSTANCE_CONNECTION_NAME
      -credential_file=PATH_TO_KEY_FILE &
    • Usando a autenticação do SDK do Cloud e a descoberta automática de instâncias:
      ./cloud_sql_proxy -dir=/cloudsql &

    É melhor iniciar o proxy do Cloud SQL Auth no próprio terminal dele, 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 do Cloud SQL Auth, consulte Opções para autenticar o proxy do Cloud SQL Auth e Opções para especificar instâncias.

Imagem do Docker do proxy do Cloud SQL Auth

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

Inicie o proxy do Cloud SQL Auth usando soquetes TCP ou 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 página Visão geral da instância no Google Cloud Console ou executando este comando:

gcloud sql instances describe INSTANCE_NAME
.

Por exemplo, myproject:myregion:myinstance.

Dependendo da linguagem e do ambiente, inicie o proxy do Cloud SQL Auth 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 do Cloud SQL Auth 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 o parâmetro do proxy do Cloud SQL Auth..

7. Inicie a sessão mysql.

A string de conexão usada depende de como você iniciou o proxy do Cloud SQL Auth usando um soquete TCP, um soquete Unix ou Docker.

Sockets TCP

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

    Quando você se conecta usando soquetes TCP, o proxy do Cloud SQL Auth é acessado por 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 Solução de problemas de conexões do proxy do Cloud SQL Auth ou consulte a página Suporte do Cloud SQL.

A seguir