Como usar o Cloud SQL para PostgreSQL

Nesta página, mostramos como se conectar a uma instância do Cloud SQL para PostgreSQL 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, depois verifique se ele 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 o faturamento estiver ativado. Caso contrário, siga as instruções para escolher uma região e ativar o faturamento.

  2. Ativar Cloud SQL API.

    Ativar a API

  3. Para implantar o aplicativo com a ferramenta gcloud, faça o download, a instalação e a inicialização do Cloud SDK:
    Fazer o download do SDK

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

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 para PostgreSQL.
  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 postgres no-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]
    

    Exemplo:

    connectionName: project1:us-central1:instance1
    

    Você também encontra esse valor na página 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 sua instância do Cloud SQL. No entanto, para testar o aplicativo localmente, é 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 sua 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

    Clique com o botão direito em https://dl.google.com/cloudsql/cloud_sql_proxy_x64.exe e selecione "Salvar link como…" para fazer o download do proxy, renomeando-o como cloud_sql_proxy.exe.

    Windows de 32 bits

    Clique com o botão direito em https://dl.google.com/cloudsql/cloud_sql_proxy_x86.exe e selecione "Salvar link como…" para fazer o download do proxy, renomeando-o como cloud_sql_proxy.exe.
    Caso seu sistema operacional não esteja incluído aqui, compile o proxy com base na origem.

  3. Execute o proxy:

    Dependendo da linguagem e do ambiente, inicie o proxy usando os soquetes TCP ou Unix.

    Soquetes TCP

    1. Copie o nome de conexão da instância na página Detalhes da instância.
    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 Cloud SDK:
        ./cloud_sql_proxy -instances=<INSTANCE_CONNECTION_NAME>=tcp:5432
        
        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:5432 \
                          -credential_file=<PATH_TO_KEY_FILE> &
        

      Para ver mais informações sobre opções de proxy, consulte Opções de autenticação do proxy e Opções para especificar 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 Cloud SDK 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 a saída dele sem misturá-la com a saída de outros programas.

      Para ver mais informações sobre opções de proxy, consulte Opções de autenticação do proxy e Opções para especificar 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 ver mais informações, consulte Conexão de cliente psql usando o Cloud SQL Proxy e Como conectar o cliente psql usando endereços IP.

Como configurar strings de conexão e adicionar uma biblioteca

  1. Configure o ambiente local para oferecer suporte a conexões de testes locais.

    Por exemplo, na amostra de código abaixo:

    export SQLALCHEMY_DATABASE_URI=postgresql+psycopg2://[USER_NAME]:[PASSWORD]@127.0.0.1:5432/[DATABASE_NAME]
    

  2. Para permitir que o aplicativo se conecte à instância do Cloud SQL quando implantado, adicione as variáveis de nome de usuário, senha, banco de dados e conexão de instância do Cloud SQL às variáveis do 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: >-
          postgresql+psycopg2://USER:PASSWORD@/DATABASE?host=/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.

    beta_settings:
        cloud_sql_instances: INSTANCE_CONNECTION_NAME
  4. Adicione a biblioteca apropriada de cliente do Python ao arquivo requirements.txt do aplicativo. Por exemplo, a amostra de código fornecida mostra psycopg2:

    Flask==0.12.2
    Flask-SQLAlchemy==2.3.2
    gunicorn==19.7.1
    psycopg2==2.7.4
    

  5. Instale as dependências do aplicativo usando virtualenv:

    Mac OS/Linux

    1. Crie um ambiente Python isolado em um diretório externo ao projeto e ative-o:
      virtualenv env
      source env/bin/activate
    2. Navegue até o diretório do projeto e instale as dependências:
      cd YOUR_PROJECT
      pip install  -r requirements.txt

    Windows

    Se você instalou o Cloud SDK, já deve ter o Python 2.7 instalado, normalmente em C:\python27_x64\ (para sistemas de 64 bits). Use o Powershell para executar seus pacotes Python.

    1. Localize a instalação do Powershell.
    2. Clique com o botão direito do mouse no atalho do Powershell e inicie-o como administrador.
    3. Tente executar o comando python. Se ele não for encontrado, adicione a pasta Python ao PATH do ambiente.
      $env:Path += ";C:\python27_x64\"
    4. Crie um ambiente Python isolado em um diretório externo ao projeto e ative-o:
      python -m virtualenv env
      env\Scripts\activate
    5. Navegue até o diretório do projeto e instale as dependências:
      cd YOUR_PROJECT
      python -m pip install -r requirements.txt

    Para ver mais informações sobre virtualenv, consulte Como instalar dependências localmente.

Como executar o código de amostra

A amostra de main.py abaixo usa a biblioteca Flask para criar um registro de visitante em uma instância do Cloud SQL. Ele 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 a seguir grava as informações de visita no Cloud SQL. Depois, ela lê e retorna as últimas 10 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'}

Testar e implantar

  1. Para testar o aplicativo no local:

    python main.py
    

  2. Após os testes locais, implante o 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 se ele e a instância do Cloud SQL estiverem 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" de IAM e Admin"

  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á existir e tiver um papel que inclua a permissão cloudsql.instances.connect, prossiga para 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 funcionará, exceto de leitor.

    Também é possível usar o papel primitivo de editor ao selecionar Projeto > Editor. No entanto, ele inclui permissões no 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 código de usuário.

  9. Clique em Adicionar.

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

Esta página foi útil? Conte sua opinião sobre:

Enviar comentários sobre…

Documentos do ambiente flexível do App Engine para Python