Como usar o Cloud SQL para MySQL

Nesta página, você aprende como se conectar a uma instância do Cloud SQL para MySQL segunda geração a partir de um aplicativo do App Engine e como fazer leituras e gravações no Cloud SQL. O Cloud SQL é um banco de dados SQL que reside na nuvem do Google.

Para saber mais sobre o Cloud SQL, consulte a documentação do Cloud SQL. Para informações sobre preços e limites do Cloud SQL, consulte a página de preços do Cloud SQL. Os aplicativos do App Engine também estão sujeitos às cotas dessa plataforma.

Antes de começar

  1. Crie ou selecione um projeto do GCP no Console do GCP e verifique se o projeto inclui um aplicativo do App Engine e se o faturamento está ativado:
    Acessar o App Engine

    O Painel será aberto se houver um aplicativo do App Engine no projeto e se o faturamento estiver ativado. Caso contrário, siga as instruções para escolher uma região e ativar o faturamento.

  2. Ative a API Cloud SQL.

    Ative a API

  3. Para implantar o aplicativo com a ferramenta gcloud, você precisa fazer o download, instalar e inicializar o SDK do Cloud:
    Fazer o download do SDK

    Se a ferramenta gcloud já estiver instalada e você quiser configurá-la para usar um ID do projeto do GCP diferente do inicializado, consulte Como gerenciar as configurações do SDK do Cloud.

Como configurar a instância do Cloud SQL

Para criar e configurar uma instância do Cloud SQL, siga estas etapas:

  1. Crie uma instância do Cloud SQL segunda geração.
  2. Defina a senha do usuário padrão na instância do Cloud SQL caso ainda não o tenha feito:
    gcloud sql users set-password root --host=% --instance [INSTANCE_NAME] --password [PASSWORD]
    
  3. Se não quiser usar o usuário padrão para se conectar, crie um usuário.
  4. Registre o nome da conexão da instância:
    gcloud sql instances describe [INSTANCE_NAME]
    

    Por exemplo:

    connectionName: project1:us-central1:instance1
    

    Você também encontra esse valor na página de Detalhes da instância no Console do Google Cloud Platform.

  5. Crie um banco de dados na instância do Cloud SQL.
    gcloud sql databases create [DATABASE_NAME] --instance=[INSTANCE_NAME]
    
    Para mais informações sobre como criar e gerenciar bancos de dados, consulte a documentação do Cloud SQL.

Como configurar o ambiente local

Depois de implantado, seu aplicativo usa o Cloud SQL Proxy incorporado ao ambiente de execução do App Engine para se comunicar com a instância do Cloud SQL. No entanto, para testar o aplicativo no local, é necessário instalar e usar uma cópia local do Cloud SQL Proxy no ambiente de desenvolvimento.

Para executar tarefas administrativas básicas na instância do Cloud SQL, use o cliente de administração do banco de dados ou o Console do GCP.

  1. Autentique a ferramenta gcloud para usar o proxy para se conectar a partir da máquina local:

    gcloud auth application-default login
    
  2. Instale o Cloud SQL Proxy:

    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
      

    macOS de 64 bits

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

    macOS de 32 bits

    1. Faça o download do proxy:
      curl -o cloud_sql_proxy https://dl.google.com/cloudsql/cloud_sql_proxy.darwin.386
      
    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 como 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 como cloud_sql_proxy.exe.
    Se seu sistema operacional não estiver incluído aqui, também é possível compilar o proxy a partir da fonte.
  3. Execute o proxy:

    Dependendo da linguagem e do ambiente, é possível iniciar o proxy usando os soquetes TCP ou Unix.

    Soquetes TCP

    1. Copie o nome de conexão da instância da página Detalhes da instância.

      Por exemplo: myproject:us-central1:myinstance.

    2. 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.
    3. 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.
      • Usando uma conta de serviço e a especificação explícita de uma instância (recomendado para ambientes de produção):
        ./cloud_sql_proxy -instances=<INSTANCE_CONNECTION_NAME>=tcp:3306 \
                          -credential_file=<PATH_TO_KEY_FILE> &
        

      Para mais informações sobre as opções de proxy, consulte Opções de autenticação de proxy e Opções de especificação de instâncias.

    Soquetes Unix

    1. Se estiver usando a especificação explícita de instâncias, copie o nome de conexão da instância da página Detalhes da instância.
    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 a especificação explícita de uma 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 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 de autenticação de proxy e Opções de especificação de instâncias.

  4. Para usar o cliente de administração, instale uma cópia local e conecte-se usando o proxy ou endereços IP.

    Para mais informações, consulte Como conectar o Cliente MySQL usando o Cloud SQL Proxy e Como conectar o Cliente MySQL usando Endereços IP.

Como configurar strings de conexão e adicionar uma biblioteca

  1. Configure o ambiente local para que seja compatível com conexões de testes locais.

    Por exemplo, na amostra de código abaixo:

    export SQLALCHEMY_DATABASE_URI=mysql+pymysql://[USER_NAME]:[PASSWORD]@127.0.0.1:3306/[DATABASE_NAME]
    
  2. Para permitir que o aplicativo se conecte à instância do Cloud SQL no momento da implantação, adicione as variáveis do Cloud SQL de usuário, senha, banco de dados e nome de conexão da instância às variáveis de ambiente relacionadas no arquivo app.yaml:

    env_variables:
        # Replace user, password, database, and instance connection name with the values obtained
        # when configuring your Cloud SQL instance.
        SQLALCHEMY_DATABASE_URI: >-
          mysql+pymysql://USER:PASSWORD@/DATABASE?unix_socket=/cloudsql/INSTANCE_CONNECTION_NAME

  3. Adicione a seção beta_settings ao app.yaml usando o nome de conexão da instância do Cloud SQL.

    # Replace project and instance with the values obtained  when configuring your
    # Cloud SQL instance.
    beta_settings:
        cloud_sql_instances: INSTANCE_CONNECTION_NAME
  4. Adicione a biblioteca de cliente do Python apropriada ao arquivo requirements.txt do aplicativo. Por exemplo, no código de amostra fornecido, mostramos SQLAlchemy com PyMySQL (links em inglês):

    Flask==1.1.1
    Flask-SQLAlchemy==2.4.1
    gunicorn==19.9.0
    PyMySQL==0.9.3
    

Como executar o código de amostra

No exemplo de main.py abaixo, usamos o framework Flask (link em inglês) para criar um registro de visitante em uma instância do Cloud SQL. Ela também usa o SQLAlchemy, que processa o pool de conexões e o fechamento.

Antes de executar a amostra, crie as tabelas necessárias e verifique se o banco de dados está configurado corretamente:

python create_tables.py
A amostra abaixo grava as informações de visita no Cloud SQL. Em seguida, ela as lê e retorna as últimas dez visitas:
# Environment variables are defined in app.yaml.
app.config['SQLALCHEMY_DATABASE_URI'] = os.environ['SQLALCHEMY_DATABASE_URI']
app.config['SQLALCHEMY_TRACK_MODIFICATIONS'] = False

db = SQLAlchemy(app)

class Visit(db.Model):
    id = db.Column(db.Integer, primary_key=True)
    timestamp = db.Column(db.DateTime())
    user_ip = db.Column(db.String(46))

    def __init__(self, timestamp, user_ip):
        self.timestamp = timestamp
        self.user_ip = user_ip

@app.route('/')
def index():
    user_ip = request.remote_addr

    # Keep only the first two octets of the IP address.
    if is_ipv6(user_ip):
        user_ip = ':'.join(user_ip.split(':')[:2])
    else:
        user_ip = '.'.join(user_ip.split('.')[:2])

    visit = Visit(
        user_ip=user_ip,
        timestamp=datetime.datetime.utcnow()
    )

    db.session.add(visit)
    db.session.commit()

    visits = Visit.query.order_by(sqlalchemy.desc(Visit.timestamp)).limit(10)

    results = [
        'Time: {} Addr: {}'.format(x.timestamp, x.user_ip)
        for x in visits]

    output = 'Last 10 visits:\n{}'.format('\n'.join(results))

    return output, 200, {'Content-Type': 'text/plain; charset=utf-8'}

Como testar e implantar

  1. Para testar seu aplicativo localmente:

    python main.py
    
  2. Após os testes locais, implante seu aplicativo no App Engine:

    gcloud app deploy
    

  3. Para iniciar o navegador e ver o aplicativo em http://[YOUR_PROJECT_ID].appspot.com, execute o seguinte comando:

    gcloud app browse
    

Como executar o Cloud SQL e o App Engine em projetos separados

Use uma conta de serviço para permitir o acesso do aplicativo do App Engine ao Cloud SQL caso ele e a instância do Cloud SQL estejam em projetos diferentes do Google Cloud Platform.

Essa conta de serviço representa o aplicativo do App Engine. Ela é gerada por padrão quando você cria um projeto do Google Cloud Platform.

  1. Se o aplicativo do App Engine estiver no mesmo projeto que a instância do Cloud SQL, ignore esta seção e vá para Como configurar o ambiente local. Caso contrário, prossiga para a próxima etapa.
  2. Identifique a conta de serviço associada ao aplicativo do App Engine. A conta padrão é denominada [PROJECT-ID]@appspot.gserviceaccount.com.

    É possível verificar a conta de serviço do App Engine na página Permissões de IAM. Lembre-se de selecionar o projeto do aplicativo do App Engine, e não a instância do Cloud SQL.

    Acessar a página "Permissões de IAM"

  3. Acesse a página Projetos do IAM e do administrador no Console do Google Cloud Platform.

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

  4. Selecione o projeto que contém a instância do Cloud SQL.
  5. Procure o nome da conta de serviço.
  6. Se a conta de serviço já estiver incluída e tiver um papel que contenha a permissão cloudsql.instances.connect, prossiga para a seção Como configurar o ambiente local.

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

  7. Caso contrário, clique em Adicionar para incluir a conta.
  8. Na caixa de diálogo Adicionar membros, insira o nome da conta de serviço e selecione um papel que inclua a permissão cloudsql.instances.connect. Qualquer papel predefinido do Cloud SQL é aceito, exceto o de visualizador.

    Também é possível usar o papel primário de Editor ao selecionar Projeto > Editor. No entanto, ele inclui permissões em todo o Google Cloud Platform.

    Se esses papéis não estiverem sendo exibidos, é provável que seu usuário do Google Cloud Platform não tenha a permissão resourcemanager.projects.setIamPolicy. Para verificar suas permissões, acesse a página IAM no Console do Google Cloud Platform e procure seu ID do usuário.

  9. Clique em Adicionar.

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