Connessione da Cloud Functions

Questa pagina contiene informazioni ed esempi per la connessione a un'istanza Cloud SQL da un servizio in esecuzione in Cloud Functions.

Per istruzioni dettagliate sull'esecuzione di un'applicazione web di esempio di Cloud Functions connessa a Cloud SQL, consulta la guida rapida per la connessione da Cloud Functions.

Cloud SQL è un servizio di database completamente gestito che semplifica la configurazione, la manutenzione, la gestione e l'amministrazione dei database relazionali nel cloud.

Cloud Functions è una soluzione di calcolo leggera che consente agli sviluppatori di creare funzioni autonome a uso specifico in grado di rispondere agli eventi Cloud senza la necessità di gestire un ambiente server o di runtime.

configura un'istanza Cloud SQL

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

    Abilita l'API

  2. Crea un'istanza Cloud SQL per MySQL.

    Per impostazione predefinita, Cloud SQL assegna un indirizzo IP pubblico a una nuova istanza. Hai anche la possibilità di assegnare un indirizzo IP privato. Per ulteriori informazioni sulle opzioni di connettività per entrambi, consulta la pagina Panoramica della connessione.

Configura Cloud Functions

I passaggi per configurare Cloud Functions dipendono dal tipo di indirizzo IP assegnato all'istanza Cloud SQL.

IP pubblico (predefinito)

Per configurare Cloud Functions per abilitare le connessioni a un'istanza Cloud SQL:

  • Verifica che l'istanza creata in precedenza abbia un indirizzo IP pubblico. Puoi verificarlo nella pagina Panoramica per l'istanza nella console Google Cloud. Se devi aggiungere un indirizzo IP pubblico, consulta Configurare l'IP pubblico.
  • Recupera il valore INSTANCE_CONNECTION_NAME dell'istanza. Questo valore è disponibile:
    • Nella pagina Panoramica dell'istanza, nella console Google Cloud, oppure
    • Esegui questo comando: gcloud sql instances describe [INSTANCE_NAME]
  • Configura l'account di servizio per la funzione. Se l'account di servizio di autorizzazione appartiene a un progetto diverso dall'istanza Cloud SQL, abilita l'API Cloud SQL Admin e aggiungi le autorizzazioni IAM elencate di seguito su entrambi i progetti. Verifica che l'account di servizio disponga delle autorizzazioni e dei ruoli Cloud SQL appropriati per la connessione a Cloud SQL.
    • Per connettersi a Cloud SQL, l'account di servizio richiede uno dei seguenti 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
  • Se utilizzi Cloud Functions (2nd gen) e non Cloud Functions (1ª generazione), è richiesto quanto segue (vedi anche Configurare Cloud Run):
    1. Inizia il deployment della funzione.
      Quando inizi a creare una Cloud Function nella console Google Cloud, il servizio Cloud Run sottostante non è stato ancora creato. Non puoi configurare una connessione Cloud SQL finché non viene creato questo servizio (tramite il deployment della Cloud Function).
    2. Nella console Google Cloud, in alto a destra nella pagina Dettagli funzione, in Con tecnologia Cloud Run, fai clic sul link per accedere al servizio Cloud Run sottostante.
    3. Nella pagina Dettagli servizio di Cloud Run, seleziona la scheda Modifica ed esegui il deployment di nuova revisione.
    4. Segui i passaggi standard (come in caso di modifiche alla configurazione) per impostare una nuova configurazione per una connessione Cloud SQL.
      Viene creata una nuova revisione Cloud Run e le revisioni successive ricevono automaticamente questa connessione Cloud SQL, a meno che non la modifichi esplicitamente.

IP privato

Se l'account di servizio di autorizzazione appartiene a un progetto diverso da quello contenente l'istanza Cloud SQL:

  • In entrambi i progetti, abilita l'API Cloud SQL Admin.
  • Per l'account di servizio del progetto che contiene l'istanza Cloud SQL, aggiungi le autorizzazioni IAM.
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:
  1. Assicurati che l'istanza Cloud SQL creata in precedenza abbia un indirizzo IP privato. Se devi aggiungerne uno, consulta Configurare l'IP privato per le istruzioni.
  2. Crea un connettore di accesso VPC serverless nella stessa rete VPC della tua istanza Cloud SQL. Tieni presente le seguenti condizioni:
    • A meno che non utilizzi un VPC condiviso, il connettore deve trovarsi nello stesso progetto e nella stessa regione della risorsa che lo utilizza, ma può inviare traffico a risorse di regioni diverse.
    • L'accesso VPC serverless supporta la comunicazione con le reti VPC connesse tramite Cloud VPN e il peering di rete VPC.
    • L'accesso VPC serverless non supporta le reti legacy.
  3. Configura Cloud Functions per l'utilizzo del connettore.
  4. Connettiti utilizzando l'indirizzo IP privato della tua istanza e la porta 3306.

Connessione a Cloud SQL

Dopo aver configurato Cloud Functions, puoi connetterti all'istanza Cloud SQL.

IP pubblico (predefinito)

Per i percorsi IP pubblici, Cloud Functions fornisce la crittografia e si connette tramite 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 il protocollo TCP per connettersi direttamente all'istanza Cloud SQL senza utilizzare il proxy di autenticazione Cloud SQL.

Connetti con TCP

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

Python

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

import os

import sqlalchemy

def connect_tcp_socket() -> sqlalchemy.engine.base.Engine:
    """Initializes a TCP connection pool for a Cloud SQL instance of MySQL."""
    # 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. 3306

    pool = sqlalchemy.create_engine(
        # Equivalent URL:
        # mysql+pymysql://<db_user>:<db_pass>@<db_host>:<db_port>/<db_name>
        sqlalchemy.engine.url.URL.create(
            drivername="mysql+pymysql",
            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, visualizza il file README su GitHub.

Nota:

  • INSTANCE_CONNECTION_NAME deve essere rappresentato come <MY-PROJECT>:<INSTANCE-REGION>:<INSTANCE-NAME>
  • Se utilizzi l'argomento ipTypes=PRIVATE, SocketIndustry forzerà la connessione all'IP privato associato a un'istanza
  • Consulta qui i requisiti di versione di fabbrica del socket JDBC per il file pom.xml.


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

public class TcpConnectionPoolFactory extends ConnectionPoolFactory {

  // Saving credentials in environment variables is convenient, but not secure - consider a more
  // secure solution such as 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:mysql://<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:mysql://%s:%s/%s", INSTANCE_HOST, DB_PORT, DB_NAME));
    config.setUsername(DB_USER); // e.g. "root", "mysql"
    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, visualizza il file README su GitHub.

const mysql = require('promise-mysql');
const fs = require('fs');

// createTcpPool initializes a TCP connection pool for a Cloud SQL
// instance of MySQL.
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 = {
    host: process.env.INSTANCE_HOST, // e.g. '127.0.0.1'
    port: process.env.DB_PORT, // e.g. '3306'
    user: process.env.DB_USER, // e.g. 'my-db-user'
    password: process.env.DB_PASS, // e.g. 'my-db-password'
    database: process.env.DB_NAME, // e.g. 'my-database'
    // ... Specify additional properties here.
    ...config,
  };
  // Establish a connection to the database.
  return mysql.createPool(dbConfig);
};

Go

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

package cloudsql

import (
	"crypto/tls"
	"crypto/x509"
	"database/sql"
	"errors"
	"fmt"
	"io/ioutil"
	"log"
	"os"

	"github.com/go-sql-driver/mysql"
)

// connectTCPSocket initializes a TCP connection pool for a Cloud SQL
// instance of MySQL.
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'
		dbName    = mustGetenv("DB_NAME")       // e.g. 'my-database'
		dbPort    = mustGetenv("DB_PORT")       // e.g. '3306'
		dbTCPHost = mustGetenv("INSTANCE_HOST") // e.g. '127.0.0.1' ('172.17.0.1' if deployed to GAE Flex)
	)

	dbURI := fmt.Sprintf("%s:%s@tcp(%s:%s)/%s?parseTime=true",
		dbUser, dbPwd, dbTCPHost, dbPort, dbName)

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

	// ...

	return dbPool, nil
}

PHP

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

namespace Google\Cloud\Samples\CloudSQL\MySQL;

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('mysql: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/mysql/connect-external-app',
                    $e->getMessage()
                ),
                $e->getCode(),
                $e
            );
        }

        return $conn;
    }
}

Best practice e altre informazioni

Puoi utilizzare il proxy di autenticazione Cloud SQL per testare l'applicazione localmente. Per istruzioni dettagliate, consulta la guida rapida all'utilizzo del proxy di autenticazione Cloud SQL.

Pool di connessioni

Le connessioni ai database sottostanti possono essere eliminate dal server di database stesso o dall'infrastruttura alla base di Cloud Functions. Ti consigliamo di utilizzare una libreria client che supporti i pool di connessioni che riconnettono automaticamente le connessioni client interrotte. Inoltre, consigliamo di utilizzare un pool di connessioni con ambito globale per aumentare la probabilità che la funzione riutili la stessa connessione per le chiamate successive della funzione e chiuda la connessione in modo naturale quando l'istanza viene rimossa (scalabilità automatica). Per esempi più dettagliati su come utilizzare i pool di connessioni, consulta Gestione delle connessioni ai database.

Limiti di connessione

Cloud SQL impone un limite massimo alle connessioni simultanee e questi limiti possono variare a seconda del motore del database scelto (consulta Quote e limiti di Cloud SQL). È consigliabile utilizzare una connessione con Cloud Functions, ma è importante impostare il numero massimo di connessioni su 1.

Se possibile, dovresti inizializzare un pool di connessioni solo per le funzioni che richiedono l'accesso al tuo database. Alcuni pool di connessioni creano connessioni preventivamente, il che può consumare risorse in eccesso e conteggiare ai fini dei limiti di connessioni. Per questo motivo, ti consigliamo di utilizzare l' inizializzazione lazy per ritardare la creazione di un pool di connessioni fino a quando non è necessario e includere il pool di connessioni solo nelle funzioni in cui viene utilizzato.

Per esempi più dettagliati su come limitare il numero di connessioni, consulta Gestione delle connessioni ai database.

Limiti di quota delle API

Cloud Functions fornisce un meccanismo che si connette tramite il proxy di autenticazione Cloud SQL, che utilizza l'API Cloud SQL Admin. Al proxy di autenticazione Cloud SQL si applicano limiti di quota API. La quota dell'API Cloud SQL Admin utilizzata è circa il doppio del numero di istanze Cloud SQL configurate per il numero totale di funzioni di cui è stato eseguito il deployment. Puoi impostare il numero massimo di chiamate simultanee per modificare la quota API prevista consumata. Cloud Functions impone inoltre limiti di frequenza al numero di chiamate API consentite ogni 100 secondi.

Passaggi successivi