Connettiti dall'ambiente standard di App Engine

Questa pagina contiene informazioni ed esempi per la connessione a un un'istanza Cloud SQL da un servizio in esecuzione nell'ambiente standard App Engine.

Cloud SQL è un servizio di database completamente gestito che ti consente di configurare, gestire e amministrare i database relazionali nel cloud.

App Engine è una piattaforma serverless completamente gestita sviluppare e ospitare applicazioni web su larga scala. Puoi scegliere tra diversi linguaggi, librerie e framework più diffusi per sviluppare le tue app, App Engine si occupa del provisioning dei server e della scalabilità delle istanze di app in base alla domanda.

Configura un'istanza Cloud SQL

  1. Abilita l'API Cloud SQL Admin nel progetto Google Cloud da cui ti connetti, se non l'hai ancora fatto:

    Enable the API

  2. Crea un'istanza Cloud SQL per PostgreSQL. Ti consigliamo di scegliere una località dell'istanza Cloud SQL nella stessa regione del servizio Cloud Run per una latenza migliore, per evitare alcuni costi di rete e per ridurre i rischi di errori tra regioni.

    Per impostazione predefinita, Cloud SQL assegna un indirizzo IP pubblico a una nuova istanza. Puoi anche scegliere di assegnare un indirizzo IP privato. Per maggiori informazioni sulle opzioni di connettività per entrambi, consulta le Panoramica della connessione .

Configura l'ambiente standard di App Engine

I passaggi per configurare l'ambiente standard di App Engine dipendono dal tipo di indirizzo IP assegnato all'istanza Cloud SQL.

IP pubblico (predefinito)

Per configurare l'ambiente standard di App Engine in modo da abilitare le connessioni a un'istanza Cloud SQL utilizzando l'IP pubblico:

  • Assicurati che l'istanza abbia un indirizzo IP pubblico. Puoi verificarlo nella pagina Panoramica dell'istanza nella console Google Cloud. Se devi aggiungerne uno, controlla Pagina Configurazione IP pubblico per istruzioni.
  • Recupera il INSTANCE_CONNECTION_NAME per la tua istanza. Puoi trovare questo valore nella pagina Panoramica della tua istanza nella console Google Cloud o eseguendo il seguente comando gcloud sql instances describe: 
    gcloud sql instances describe INSTANCE_NAME
    Sostituisci INSTANCE_NAME con il nome del tuo account Cloud SQL in esecuzione in un'istanza Compute Engine.
    • Sostituisci la variabile INSTANCE_NAME con il nome dell'istanza.
  • Assicurati che l'account di servizio utilizzato dalla tua app per autenticare le chiamate Cloud SQL dispone della Ruolo Cloud SQL e autorizzazioni.
    • L'account di servizio per il tuo servizio richiede uno dei seguenti requisiti Ruoli IAM:
      • Cloud SQL Client (opzione preferita)
      • Cloud SQL Editor
      • Cloud SQL Admin
      In alternativa, puoi assegnare manualmente le seguenti autorizzazioni IAM:
      • cloudsql.instances.connect
      • cloudsql.instances.get
      Per istruzioni dettagliate sull'aggiunta di ruoli IAM a un account di servizio, consulta Concessione di ruoli agli account di servizio.

    Per impostazione predefinita, l'app autorizzerà le connessioni utilizzando un Account di servizio App Engine. Account di servizio identità è nel formato PROJECT_ID@appspot.gserviceaccount.com.

    Se l'account di servizio che concede l'autorizzazione appartiene a un progetto diverso dall'istanza Cloud SQL, sarà necessario aggiungere le autorizzazioni IAM e l'API di amministrazione Cloud SQL per entrambi i progetti.

IP privato

Se l'account di servizio di autorizzazione appartiene a un progetto diverso da quello una contenente l'istanza Cloud SQL, segui questi passaggi:

  • In entrambi i progetti, abilita l'API Cloud SQL Admin.
  • Aggiungi le autorizzazioni IAM per l'account di servizio nel progetto che contiene l'istanza Cloud SQL.
Un connettore di accesso VPC serverless utilizza indirizzi IP privati per gestire la comunicazione con la tua rete VPC. Per connetterti direttamente con indirizzi IP privati, devi seguire questi passaggi:
  1. Assicurati che l'istanza Cloud SQL creata in precedenza abbia un l'indirizzo IP privato. Se devi aggiungerne uno, consulta Configurare l'IP privato per istruzioni.
  2. Crea un connettore di accesso VPC serverless nello stesso VPC come istanza Cloud SQL. Tieni presente le seguenti condizioni:
    • A meno che non utilizzi VPC condiviso, il connettore deve trovarsi nello stesso progetto regione come risorsa che la utilizza, ma può inviare traffico alle risorse regioni diverse.
    • L'accesso VPC serverless supporta la comunicazione con le reti VPC connesse tramite Cloud VPN e il peering di reti VPC.
    • L'accesso VPC serverless non supporta le reti legacy.
  3. Configura l'ambiente standard di App Engine per utilizzare il connettore.
  4. Connettiti utilizzando l'indirizzo IP privato e la porta 5432 dell'istanza.

Connettiti a Cloud SQL

Dopo aver configurato l'ambiente standard App Engine, puoi connetterti all'istanza Cloud SQL.

IP pubblico (predefinito)

Per i percorsi IP pubblici, l'ambiente standard di App Engine fornisce crittografia e si connette utilizzando il proxy di autenticazione Cloud SQL in due modi:

IP privato

Per i percorsi IP privati, l'applicazione si connette direttamente all'istanza tramite una rete VPC. Questo metodo utilizza TCP per connettersi direttamente all'istanza Cloud SQL senza utilizzare il proxy di autenticazione Cloud SQL.

Connetti tramite TCP

Connettiti utilizzando l'indirizzo IP privato dell'istanza Cloud SQL come host e la porta 5432.

Python

Per visualizzare questo snippet nel contesto di un'applicazione web, visualizza il file README su 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

Per visualizzare questo snippet nel contesto di un'applicazione web, consulta il file README su GitHub.

Nota:

  • CLOUD_SQL_CONNECTION_NAME deve essere rappresentato come &lt;MY-PROJECT&gt;:&lt;INSTANCE-REGION&gt;:&lt;INSTANCE-NAME&gt;
  • L'utilizzo dell'argomento ipTypes=PRIVATE forza SocketFactory a connettersi all'IP privato associato di un'istanza
  • Consulta i requisiti di versione di fabbrica del socket JDBC per pom.xml qui . 


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

Per visualizzare questo snippet nel contesto di un'applicazione web, consulta il file README su 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);
};

Vai

Per visualizzare questo snippet nel contesto di un'applicazione web, consulta il file README su 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#

Per visualizzare questo snippet nel contesto di un'applicazione web, consulta il file README su 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

Per visualizzare questo snippet nel contesto di un'applicazione web, visualizza il file README su 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

Per visualizzare questo snippet nel contesto di un'applicazione web, visualizza il file README su 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;
    }
}

Best practice e altre informazioni

Puoi utilizzare il proxy di autenticazione Cloud SQL durante il test la tua applicazione in locale. Consulta le guida rapida per l'utilizzo del proxy di autenticazione Cloud SQL per istruzioni dettagliate.

Pool di connessioni

Le connessioni ai database sottostanti potrebbero essere interrotte dal server del database stesso o dall'infrastruttura sottostante. Per ovviare a questo problema, ti consigliamo di utilizzare una libreria client che supporti pool di connessioni e la riconnessione automatica.

Limiti di connessione

Ogni istanza App Engine in esecuzione nell'ambiente standard non può avere più di 100 connessioni simultanee a un'istanza. Per le app PHP 5.5, il limite è di 60 connessioni simultanee. Questo limite si applica a ogni istanza dell'applicazione. Ciò significa che ogni istanza L'applicazione App Engine può avere così tante connessioni al database, e, man mano che scala, il numero totale di connessioni per deployment può crescere. Per ulteriori informazioni, consulta Eseguire la scalabilità degli elementi.

Puoi limitare il numero massimo di connessioni utilizzate per istanza utilizzando un pool di connessioni. Per esempi più dettagliati su come limitare il numero di connessioni, consulta la pagina Gestire le connessioni al database.

Le applicazioni App Engine sono soggette a limiti di tempo per le richieste a seconda dell'utilizzo e completamente gestito di Google Cloud. Per ulteriori informazioni, scopri come vengono gestite le istanze nell'ambiente standard di App Engine standard e in quello flessibile di App Engine.

Limiti di quota dell'API

App Engine fornisce un meccanismo che si connette utilizzando il proxy di autenticazione Cloud SQL, che utilizza l'API Cloud SQL Admin. I limiti di quota dell'API si applicano al proxy di autenticazione Cloud SQL. Quando l'API Cloud SQL Admin viene avviata, utilizza una quota di due e in seguito una media di due ogni ora. La quota predefinita è 180 richieste al minuto per utente. Le applicazioni App Engine soggetti a quote e limiti aggiuntivi, come illustrato in alla pagina Quote di App Engine.