Estabeleça ligação a partir do Cloud Run

Esta página contém informações e exemplos para estabelecer ligação a uma instância do Cloud SQL a partir de um serviço em execução no Cloud Run.

Para obter instruções passo a passo sobre a execução de uma aplicação Web de exemplo do Cloud Run ligada ao Cloud SQL, consulte o início rápido para estabelecer ligação a partir do Cloud Run.

O Cloud SQL é um serviço de base de dados totalmente gerido que ajuda na configuração, manutenção, gestão e administração das suas bases de dados relacionais na nuvem.

O Cloud Run é uma plataforma de computação gerida que lhe permite executar contentores diretamente na parte superior da Google Cloud infraestrutura.

Configure uma instância do Cloud SQL

  1. Ative a API Cloud SQL Admin no Google Cloud projeto a partir do qual está a estabelecer ligação, se ainda não o tiver feito:

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the API

  2. Crie uma instância do Cloud SQL para PostgreSQL. Recomendamos que escolha uma localização da instância do Cloud SQL na mesma região que o seu serviço do Cloud Run para ter uma melhor latência, evitar alguns custos de rede e reduzir os riscos de falhas entre regiões.

    Por predefinição, o Cloud SQL atribui um endereço IP público a uma nova instância. Também tem a opção de atribuir um endereço IP privado. Para mais informações sobre as opções de conetividade para ambos, consulte a página Vista geral da ligação.

  3. Quando cria a instância, pode escolher a hierarquia do certificado do servidor (AC) para a instância e, em seguida, configurar a hierarquia como a serverCaMode para a instância. Tem de selecionar a opção de AC por instância (GOOGLE_MANAGED_INTERNAL_CA) como o modo de AC do servidor para instâncias às quais quer estabelecer ligação a partir de aplicações Web.

Configure o Cloud Run

Os passos para configurar o Cloud Run dependem do tipo de endereço IP que atribuiu à sua instância do Cloud SQL. Se encaminhar todo o tráfego de saída através da saída da VPC direta ou de um conetor do Acesso a VPC sem servidor, use um endereço IP privado. Compare os dois métodos de saída da rede.

IP público (predefinição)

  • Certifique-se de que a instância tem um endereço IP público. Pode validar esta situação na página Vista geral da sua instância na Google Cloud consola. Se precisar de adicionar um, consulte a página de configuração do IP público para ver instruções.
  • Obtenha o INSTANCE_CONNECTION_NAME para a sua instância. Pode encontrar este valor na página Vista geral da sua instância na Google Cloud consola ou executando o seguinte comando: gcloud sql instances describe 
    gcloud sql instances describe INSTANCE_NAME
    Substitua INSTANCE_NAME pelo nome da sua instância do Cloud SQL.
  • Obtenha o CLOUD_RUN_SERVICE_ACCOUNT_NAME para o seu serviço do Cloud Run. Pode encontrar este valor na página IAM do projeto que está a alojar o serviço Cloud Run na Google Cloud consola ou executando o seguinte comando gcloud run services describe no projeto que está a alojar o serviço Cloud Run: 
    gcloud run services describe CLOUD_RUN_SERVICE_NAME
--region CLOUD_RUN_SERVICE_REGION --format="value(spec.template.spec.serviceAccountName)"
    Substitua as seguintes variáveis:
    • CLOUD_RUN_SERVICE_NAME: o nome do seu serviço do Cloud Run
    • CLOUD_RUN_SERVICE_REGION: a região do seu serviço do Cloud Run
  • Configure a conta de serviço para o seu serviço do Cloud Run. Para estabelecer ligação ao Cloud SQL, certifique-se de que a conta de serviço tem a Cloud SQL Client função do IAM.
  • Se estiver a adicionar uma ligação do Cloud SQL a um novo serviço, tem de ter o serviço em contentores e carregado para o Container Registry ou o Artifact Registry. Se ainda não tiver uma ligação, consulte estas instruções sobre como criar e implementar uma imagem de contentor.

  • Se estiver a estabelecer ligação a instâncias configuradas com a opção de autoridade de certificação (AC) partilhada (GOOGLE_MANAGED_CAS_CA) ou a opção de AC gerida pelo cliente (CUSTOMER_MANAGED_CAS_CA) como o modo de AC do servidor, selecione o ambiente de execução de segunda geração quando selecionar o ambiente de execução para o serviço. Ambas as opções do modo de CA do servidor requerem que se ligue à instância com o proxy Auth do Cloud SQL v2.

    Se o seu serviço for executado num ambiente de execução de primeira geração, então: Só pode estabelecer ligação a instâncias do Cloud SQL configuradas com a opção de autoridade de certificação (AC) por instância (GOOGLE_MANAGED_INTERNAL_CA) como modo de AC do servidor. O ambiente de execução de primeira geração do Cloud Run incorpora o proxy Auth do Cloud SQL v1. Para mais informações sobre os requisitos de ligação ao Cloud SQL para o proxy Auth do Cloud SQL, consulte os requisitos para usar o proxy Auth do Cloud SQL.

Tal como qualquer alteração de configuração, a definição de uma nova configuração para a ligação do Cloud SQL leva à criação de uma nova revisão do Cloud Run. As revisões subsequentes também recebem automaticamente esta ligação do Cloud SQL, a menos que faça atualizações explícitas para a alterar.

Consola

  1. Aceda ao Cloud Run

  2. Comece a configurar o serviço. Para adicionar ligações do Cloud SQL a um serviço existente, faça o seguinte:

    1. Na lista Serviços, clique no nome do serviço pretendido.
    2. Clique em Editar e implementar nova revisão.
  3. Ative a ligação a uma instância do Cloud SQL:
    1. Clique em Recipientes e, de seguida, em Definições.
    2. Desloque a página até Ligações do Cloud SQL.
    3. Clique em Adicionar associação.
    4. Clique no botão Ativar o administrador do Cloud SQL se ainda não tiver ativado a API Admin do Cloud SQL.

    Adicione uma ligação do Cloud SQL

    • Se estiver a adicionar uma ligação a uma instância do Cloud SQL no seu projeto, selecione a instância do Cloud SQL pretendida no menu.
    • Se estiver a usar uma instância do Cloud SQL de outro projeto, selecione string de ligação personalizada no menu e introduza o nome de ligação da instância completo no formato PROJECT-ID:REGION:INSTANCE-ID.
    • Para eliminar uma associação, coloque o cursor à direita da associação para apresentar o ícone Eliminar e clique nele.

  4. Clique em Criar ou Implementar.

Linha de comandos

Antes de usar qualquer um dos seguintes comandos, faça as seguintes substituições:

  • IMAGE com a imagem que está a implementar
  • SERVICE_NAME com o nome do seu serviço do Cloud Run

  • INSTANCE_CONNECTION_NAME com o nome de ligação da instância da sua instância do Cloud SQL ou uma lista de nomes de ligações delimitados por vírgulas.

    Se estiver a implementar um novo contentor, use o seguinte comando:

    gcloud run deploy \
  --image=IMAGE \
  --add-cloudsql-instances=INSTANCE_CONNECTION_NAME
     Se estiver a atualizar um serviço existente, use o seguinte comando: 
    gcloud run services update SERVICE_NAME \
  --add-cloudsql-instances=INSTANCE_CONNECTION_NAME

Terraform

O código seguinte cria um contentor base do Cloud Run com uma instância do Cloud SQL ligada.

resource "google_cloud_run_v2_service" "default" {
  name     = "cloudrun-service"
  location = "us-central1"

  deletion_protection = false # set to "true" in production

  template {
    containers {
      image = "us-docker.pkg.dev/cloudrun/container/hello:latest" # Image to deploy

      volume_mounts {
        name       = "cloudsql"
        mount_path = "/cloudsql"
      }
    }
    volumes {
      name = "cloudsql"
      cloud_sql_instance {
        instances = [google_sql_database_instance.default.connection_name]
      }
    }
  }
  client     = "terraform"
  depends_on = [google_project_service.secretmanager_api, google_project_service.cloudrun_api, google_project_service.sqladmin_api]
}

  1. Aplique as alterações introduzindo terraform apply.
  2. Valide as alterações verificando o serviço Cloud Run, clicando no separador Revisões e, de seguida, no separador Ligações.

IP privado

Se a conta de serviço de autorização pertencer a um projeto diferente do que contém a instância do Cloud SQL, faça o seguinte:

  • Em ambos os projetos, ative a API Admin do Cloud SQL.
  • Para a conta de serviço no projeto que contém a instância do Cloud SQL, adicione as autorizações IAM.
A saída direta da VPC e os conetores usam endereços IP privados para processar a comunicação com a sua rede VPC. Para estabelecer ligação diretamente com endereços IP privados através de um destes métodos de saída, faça o seguinte:
  1. Certifique-se de que a instância do Cloud SQL criada anteriormente tem um endereço IP privado. Para adicionar um endereço IP interno, consulte o artigo Configurar IP privado.
  2. Configure o método de saída para estabelecer ligação à mesma rede VPC que a instância do Cloud SQL. Tenha em atenção as seguintes condições:
    • A saída da VPC direta e o acesso a VPC sem servidor suportam a comunicação com redes VPC ligadas através do Cloud VPN e do intercâmbio das redes da VPC.
    • A saída da VPC direta e o Acesso a VPC sem servidor não suportam redes antigas.
    • A menos que esteja a usar a VPC partilhada, um conector tem de partilhar o mesmo projeto e região que o recurso que o usa, embora o conector possa enviar tráfego para recursos em diferentes regiões.
  3. Estabeleça ligação através do endereço IP privado e da porta da sua instância 5432.

Estabeleça ligação ao Cloud SQL

Depois de configurar o Cloud Run, pode estabelecer ligação à sua instância do Cloud SQL.

IP público (predefinição)

Para caminhos de IP público, o Cloud Run fornece encriptação e estabelece ligação através do proxy Auth do Cloud SQL de duas formas:

Use o Secret Manager

A Google recomenda que use o Secret Manager para armazenar informações confidenciais, como credenciais SQL. Pode transmitir segredos como variáveis de ambiente ou montá-los como um volume com o Cloud Run.

Depois de criar um segredo no Secret Manager, atualize um serviço existente com o seguinte comando:

Linha de comandos

gcloud run services update SERVICE_NAME \
  --add-cloudsql-instances=INSTANCE_CONNECTION_NAME
  --update-env-vars=INSTANCE_CONNECTION_NAME=INSTANCE_CONNECTION_NAME_SECRET \
  --update-secrets=DB_USER=DB_USER_SECRET:latest \
  --update-secrets=DB_PASS=DB_PASS_SECRET:latest \
  --update-secrets=DB_NAME=DB_NAME_SECRET:latest

Terraform

O seguinte cria recursos secretos para armazenar de forma segura os valores do utilizador, da palavra-passe e do nome da base de dados através de google_secret_manager_secret e google_secret_manager_secret_version. Tenha em atenção que tem de atualizar a conta de serviço de computação do projeto para ter acesso a cada segredo.


# Create dbuser secret
resource "google_secret_manager_secret" "dbuser" {
  secret_id = "dbusersecret"
  replication {
    auto {}
  }
  depends_on = [google_project_service.secretmanager_api]
}

# Attaches secret data for dbuser secret
resource "google_secret_manager_secret_version" "dbuser_data" {
  secret      = google_secret_manager_secret.dbuser.id
  secret_data = "secret-data" # Stores secret as a plain txt in state
}

# Update service account for dbuser secret
resource "google_secret_manager_secret_iam_member" "secretaccess_compute_dbuser" {
  secret_id = google_secret_manager_secret.dbuser.id
  role      = "roles/secretmanager.secretAccessor"
  member    = "serviceAccount:${data.google_project.project.number}-compute@developer.gserviceaccount.com" # Project's compute service account
}



# Create dbpass secret
resource "google_secret_manager_secret" "dbpass" {
  secret_id = "dbpasssecret"
  replication {
    auto {}
  }
  depends_on = [google_project_service.secretmanager_api]
}

# Attaches secret data for dbpass secret
resource "google_secret_manager_secret_version" "dbpass_data" {
  secret      = google_secret_manager_secret.dbpass.id
  secret_data = "secret-data" # Stores secret as a plain txt in state
}

# Update service account for dbpass secret
resource "google_secret_manager_secret_iam_member" "secretaccess_compute_dbpass" {
  secret_id = google_secret_manager_secret.dbpass.id
  role      = "roles/secretmanager.secretAccessor"
  member    = "serviceAccount:${data.google_project.project.number}-compute@developer.gserviceaccount.com" # Project's compute service account
}



# Create dbname secret
resource "google_secret_manager_secret" "dbname" {
  secret_id = "dbnamesecret"
  replication {
    auto {}
  }
  depends_on = [google_project_service.secretmanager_api]
}

# Attaches secret data for dbname secret
resource "google_secret_manager_secret_version" "dbname_data" {
  secret      = google_secret_manager_secret.dbname.id
  secret_data = "secret-data" # Stores secret as a plain txt in state
}

# Update service account for dbname secret
resource "google_secret_manager_secret_iam_member" "secretaccess_compute_dbname" {
  secret_id = google_secret_manager_secret.dbname.id
  role      = "roles/secretmanager.secretAccessor"
  member    = "serviceAccount:${data.google_project.project.number}-compute@developer.gserviceaccount.com" # Project's compute service account
}

Atualize o recurso principal do Cloud Run para incluir os novos segredos.

resource "google_cloud_run_v2_service" "default" {
  name     = "cloudrun-service"
  location = "us-central1"

  deletion_protection = false # set to "true" in production

  template {
    containers {
      image = "us-docker.pkg.dev/cloudrun/container/hello:latest" # Image to deploy

      # Sets a environment variable for instance connection name
      env {
        name  = "INSTANCE_CONNECTION_NAME"
        value = google_sql_database_instance.default.connection_name
      }
      # Sets a secret environment variable for database user secret
      env {
        name = "DB_USER"
        value_source {
          secret_key_ref {
            secret  = google_secret_manager_secret.dbuser.secret_id # secret name
            version = "latest"                                      # secret version number or 'latest'
          }
        }
      }
      # Sets a secret environment variable for database password secret
      env {
        name = "DB_PASS"
        value_source {
          secret_key_ref {
            secret  = google_secret_manager_secret.dbpass.secret_id # secret name
            version = "latest"                                      # secret version number or 'latest'
          }
        }
      }
      # Sets a secret environment variable for database name secret
      env {
        name = "DB_NAME"
        value_source {
          secret_key_ref {
            secret  = google_secret_manager_secret.dbname.secret_id # secret name
            version = "latest"                                      # secret version number or 'latest'
          }
        }
      }

      volume_mounts {
        name       = "cloudsql"
        mount_path = "/cloudsql"
      }
    }
    volumes {
      name = "cloudsql"
      cloud_sql_instance {
        instances = [google_sql_database_instance.default.connection_name]
      }
    }
  }
  client     = "terraform"
  depends_on = [google_project_service.secretmanager_api, google_project_service.cloudrun_api, google_project_service.sqladmin_api]
}

Aplique as alterações introduzindo terraform apply.

O comando de exemplo usa a versão secreta, latest. No entanto, a Google recomenda fixar o segredo a uma versão específica, SECRET_NAME:v1.

IP privado

Para caminhos de IP privado, a sua aplicação liga-se diretamente à sua instância através de uma rede VPC. Este método usa o TCP para se ligar diretamente à instância do Cloud SQL sem usar o proxy Auth do Cloud SQL.

Estabeleça ligação com TCP

Estabeleça ligação através do endereço IP privado da sua instância do Cloud SQL como anfitrião e porta 5432.

Python

Para ver este fragmento no contexto de uma app Web, consulte o ficheiro README no GitHub.

import os
import ssl

import sqlalchemy


def connect_tcp_socket() -> sqlalchemy.engine.base.Engine:
    """Initializes a TCP connection pool for a Cloud SQL instance of Postgres."""
    # Note: Saving credentials in environment variables is convenient, but not
    # secure - consider a more secure solution such as
    # Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
    # keep secrets safe.
    db_host = os.environ[
        "INSTANCE_HOST"
    ]  # e.g. '127.0.0.1' ('172.17.0.1' if deployed to GAE Flex)
    db_user = os.environ["DB_USER"]  # e.g. 'my-db-user'
    db_pass = os.environ["DB_PASS"]  # e.g. 'my-db-password'
    db_name = os.environ["DB_NAME"]  # e.g. 'my-database'
    db_port = os.environ["DB_PORT"]  # e.g. 5432

    pool = sqlalchemy.create_engine(
        # Equivalent URL:
        # postgresql+pg8000://<db_user>:<db_pass>@<db_host>:<db_port>/<db_name>
        sqlalchemy.engine.url.URL.create(
            drivername="postgresql+pg8000",
            username=db_user,
            password=db_pass,
            host=db_host,
            port=db_port,
            database=db_name,
        ),
        # ...
    )
    return pool

Java

Para ver este fragmento no contexto de uma app Web, consulte o ficheiro README no GitHub.

Nota: 


import com.zaxxer.hikari.HikariConfig;
import com.zaxxer.hikari.HikariDataSource;
import javax.sql.DataSource;

public class TcpConnectionPoolFactory extends ConnectionPoolFactory {

  // Note: Saving credentials in environment variables is convenient, but not
  // secure - consider a more secure solution such as
  // Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
  // keep secrets safe.
  private static final String DB_USER = System.getenv("DB_USER");
  private static final String DB_PASS = System.getenv("DB_PASS");
  private static final String DB_NAME = System.getenv("DB_NAME");

  private static final String INSTANCE_HOST = System.getenv("INSTANCE_HOST");
  private static final String DB_PORT = System.getenv("DB_PORT");


  public static DataSource createConnectionPool() {
    // The configuration object specifies behaviors for the connection pool.
    HikariConfig config = new HikariConfig();

    // The following URL is equivalent to setting the config options below:
    // jdbc:postgresql://<INSTANCE_HOST>:<DB_PORT>/<DB_NAME>?user=<DB_USER>&password=<DB_PASS>
    // See the link below for more info on building a JDBC URL for the Cloud SQL JDBC Socket Factory
    // https://github.com/GoogleCloudPlatform/cloud-sql-jdbc-socket-factory#creating-the-jdbc-url

    // Configure which instance and what database user to connect with.
    config.setJdbcUrl(String.format("jdbc:postgresql://%s:%s/%s", INSTANCE_HOST, DB_PORT, DB_NAME));
    config.setUsername(DB_USER); // e.g. "root", "postgres"
    config.setPassword(DB_PASS); // e.g. "my-password"


    // ... Specify additional connection properties here.
    // ...

    // Initialize the connection pool using the configuration object.
    return new HikariDataSource(config);
  }
}

Node.js

Para ver este fragmento no contexto de uma app Web, consulte o ficheiro README no GitHub.

const Knex = require('knex');
const fs = require('fs');

// createTcpPool initializes a TCP connection pool for a Cloud SQL
// instance of Postgres.
const createTcpPool = async config => {
  // Note: Saving credentials in environment variables is convenient, but not
  // secure - consider a more secure solution such as
  // Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
  // keep secrets safe.
  const dbConfig = {
    client: 'pg',
    connection: {
      host: process.env.INSTANCE_HOST, // e.g. '127.0.0.1'
      port: process.env.DB_PORT, // e.g. '5432'
      user: process.env.DB_USER, // e.g. 'my-user'
      password: process.env.DB_PASS, // e.g. 'my-user-password'
      database: process.env.DB_NAME, // e.g. 'my-database'
    },
    // ... Specify additional properties here.
    ...config,
  };
  // Establish a connection to the database.
  return Knex(dbConfig);
};

Ir

Para ver este fragmento no contexto de uma app Web, consulte o ficheiro README no GitHub.

package cloudsql

import (
	"database/sql"
	"fmt"
	"log"
	"os"

	// Note: If connecting using the App Engine Flex Go runtime, use
	// "github.com/jackc/pgx/stdlib" instead, since v5 requires
	// Go modules which are not supported by App Engine Flex.
	_ "github.com/jackc/pgx/v5/stdlib"
)

// connectTCPSocket initializes a TCP connection pool for a Cloud SQL
// instance of Postgres.
func connectTCPSocket() (*sql.DB, error) {
	mustGetenv := func(k string) string {
		v := os.Getenv(k)
		if v == "" {
			log.Fatalf("Fatal Error in connect_tcp.go: %s environment variable not set.", k)
		}
		return v
	}
	// Note: Saving credentials in environment variables is convenient, but not
	// secure - consider a more secure solution such as
	// Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
	// keep secrets safe.
	var (
		dbUser    = mustGetenv("DB_USER")       // e.g. 'my-db-user'
		dbPwd     = mustGetenv("DB_PASS")       // e.g. 'my-db-password'
		dbTCPHost = mustGetenv("INSTANCE_HOST") // e.g. '127.0.0.1' ('172.17.0.1' if deployed to GAE Flex)
		dbPort    = mustGetenv("DB_PORT")       // e.g. '5432'
		dbName    = mustGetenv("DB_NAME")       // e.g. 'my-database'
	)

	dbURI := fmt.Sprintf("host=%s user=%s password=%s port=%s database=%s",
		dbTCPHost, dbUser, dbPwd, dbPort, dbName)


	// dbPool is the pool of database connections.
	dbPool, err := sql.Open("pgx", dbURI)
	if err != nil {
		return nil, fmt.Errorf("sql.Open: %w", err)
	}

	// ...

	return dbPool, nil
}

C#

Para ver este fragmento no contexto de uma app Web, consulte o ficheiro README no GitHub.

using Npgsql;
using System;

namespace CloudSql
{
    public class PostgreSqlTcp
    {
        public static NpgsqlConnectionStringBuilder NewPostgreSqlTCPConnectionString()
        {
            // Equivalent connection string:
            // "Uid=<DB_USER>;Pwd=<DB_PASS>;Host=<INSTANCE_HOST>;Database=<DB_NAME>;"
            var connectionString = new NpgsqlConnectionStringBuilder()
            {
                // Note: Saving credentials in environment variables is convenient, but not
                // secure - consider a more secure solution such as
                // Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
                // keep secrets safe.
                Host = Environment.GetEnvironmentVariable("INSTANCE_HOST"),     // e.g. '127.0.0.1'
                // Set Host to 'cloudsql' when deploying to App Engine Flexible environment
                Username = Environment.GetEnvironmentVariable("DB_USER"), // e.g. 'my-db-user'
                Password = Environment.GetEnvironmentVariable("DB_PASS"), // e.g. 'my-db-password'
                Database = Environment.GetEnvironmentVariable("DB_NAME"), // e.g. 'my-database'

                // The Cloud SQL proxy provides encryption between the proxy and instance.
                SslMode = SslMode.Disable,
            };
            connectionString.Pooling = true;
            // Specify additional properties here.
            return connectionString;
        }
    }
}

Ruby

Para ver este fragmento no contexto de uma app Web, consulte o ficheiro README no GitHub.

tcp: &tcp
  adapter: postgresql
  # Configure additional properties here.
  # Note: Saving credentials in environment variables is convenient, but not
  # secure - consider a more secure solution such as
  # Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
  # keep secrets safe.
  username: <%= ENV["DB_USER"] %>  # e.g. "my-database-user"
  password: <%= ENV["DB_PASS"] %> # e.g. "my-database-password"
  database: <%= ENV.fetch("DB_NAME") { "vote_development" } %>
  host: <%= ENV.fetch("INSTANCE_HOST") { "127.0.0.1" }%> # '172.17.0.1' if deployed to GAE Flex
  port: <%= ENV.fetch("DB_PORT") { 5432 }%>

PHP

Para ver este fragmento no contexto de uma app Web, consulte o ficheiro README no GitHub.

namespace Google\Cloud\Samples\CloudSQL\Postgres;

use PDO;
use PDOException;
use RuntimeException;
use TypeError;

class DatabaseTcp
{
    public static function initTcpDatabaseConnection(): PDO
    {
        try {
            // Note: Saving credentials in environment variables is convenient, but not
            // secure - consider a more secure solution such as
            // Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
            // keep secrets safe.
            $username = getenv('DB_USER'); // e.g. 'your_db_user'
            $password = getenv('DB_PASS'); // e.g. 'your_db_password'
            $dbName = getenv('DB_NAME'); // e.g. 'your_db_name'
            $instanceHost = getenv('INSTANCE_HOST'); // e.g. '127.0.0.1' ('172.17.0.1' for GAE Flex)

            // Connect using TCP
            $dsn = sprintf('pgsql:dbname=%s;host=%s', $dbName, $instanceHost);

            // Connect to the database
            $conn = new PDO(
                $dsn,
                $username,
                $password,
                # ...
            );
        } catch (TypeError $e) {
            throw new RuntimeException(
                sprintf(
                    'Invalid or missing configuration! Make sure you have set ' .
                        '$username, $password, $dbName, and $instanceHost (for TCP mode). ' .
                        'The PHP error was %s',
                    $e->getMessage()
                ),
                $e->getCode(),
                $e
            );
        } catch (PDOException $e) {
            throw new RuntimeException(
                sprintf(
                    'Could not connect to the Cloud SQL Database. Check that ' .
                        'your username and password are correct, that the Cloud SQL ' .
                        'proxy is running, and that the database exists and is ready ' .
                        'for use. For more assistance, refer to %s. The PDO error was %s',
                    'https://cloud.google.com/sql/docs/postgres/connect-external-app',
                    $e->getMessage()
                ),
                $e->getCode(),
                $e
            );
        }

        return $conn;
    }
}

Práticas recomendadas e outras informações

Pode usar o proxy Auth do Cloud SQL quando testar a sua aplicação localmente. Consulte o início rápido para usar o proxy Auth do Cloud SQL para ver instruções detalhadas.

Também pode testar através do proxy do Cloud SQL através de um contentor Docker.

Conjuntos de ligações

As ligações às bases de dados subjacentes podem ser interrompidas pelo próprio servidor da base de dados ou pela infraestrutura da plataforma. Recomendamos a utilização de uma biblioteca de cliente que suporte pools de ligações que restabeleçam automaticamente as ligações de cliente interrompidas. Pode usar o agrupamento de ligações gerido com as suas instâncias do Cloud SQL, o que lhe permite dimensionar as suas cargas de trabalho otimizando a utilização de recursos e a latência de ligação para as suas instâncias do Cloud SQL através do agrupamento. Para ver informações detalhadas sobre a funcionalidade de agrupamento de ligações geridas, consulte o artigo Vista geral do agrupamento de ligações geridas.

Para ver exemplos mais detalhados sobre como usar pools de ligações, consulte a página Gerir ligações à base de dados.

Limites de ligação

As edições MySQL e PostgreSQL do Cloud SQL impõem um limite máximo nas ligações simultâneas, e estes limites podem variar consoante o motor de base de dados escolhido (consulte a página Quotas e limites do Cloud SQL).

As instâncias de contentores do Cloud Run estão limitadas a 100 ligações a uma base de dados do Cloud SQL. Cada instância de um serviço ou uma tarefa do Cloud Run pode ter 100 ligações à base de dados e, à medida que este serviço ou tarefa é dimensionado, o número total de ligações por implementação pode aumentar.

Pode limitar o número máximo de ligações usadas por instância através de um conjunto de ligações. Para ver exemplos mais detalhados sobre como limitar o número de associações, consulte a página Gerir associações de bases de dados.

Limites de quota da API

O Cloud Run fornece um mecanismo que se liga através do proxy Auth do Cloud SQL, que usa a API Cloud SQL Admin. Os limites de quota da API aplicam-se ao proxy Auth do Cloud SQL. A quota da API Admin do Cloud SQL usada é aproximadamente duas vezes o número de instâncias do Cloud SQL configuradas pelo número de instâncias do Cloud Run de um serviço específico implementado em qualquer altura. Pode limitar ou aumentar o número de instâncias do Cloud Run para modificar a quota da API esperada consumida.

O que se segue?