Connexion depuis Cloud Functions

MySQL | PostgreSQL | SQL Server

Cette page contient des informations et des exemples de connexion à une instance Cloud SQL à partir d'un service s'exécutant dans Cloud Functions.

Pour obtenir des instructions détaillées sur l'exécution d'un exemple d'application Web Cloud Functions connectée à Cloud SQL, consultezDémarrage rapide pour la connexion à partir de Cloud Functions.

Cloud SQL est un service de base de données entièrement géré qui vous aide à configurer, maintenir, gérer et administrer vos bases de données relationnelles dans le cloud.

Cloud Functions est une solution de calcul légère permettant aux développeurs de créer des fonctions autonomes à usage unique qui répondent aux événements Cloud, sans avoir à gérer de serveur ni d'environnement d'exécution.

Configurer une instance Cloud SQL

Activez l'API Cloud SQL Admin dans le projet Google Cloud à partir duquel vous vous connectez, si ce n'est pas déjà fait :

Activer l'API
Créez une instance Cloud SQL pour SQL Server.
Par défaut, Cloud SQL attribue une adresse IP publique à une nouvelle instance. Vous avez également la possibilité d'attribuer une adresse IP privée. Pour en savoir plus sur les options de connectivité disponibles pour ces deux types d'adresses IP, consultez la page Présentation du processus de connexion.

Configurer Cloud Functions

La procédure à suivre pour configurer Cloud Functions dépend du type d'adresse IP que vous avez attribué à votre instance Cloud SQL.

Adresse IP publique (par défaut)

Cloud Functions permet de se connecter à Cloud SQL pour SQL Server via une adresse IP publique à l'aide des connecteurs Go, Java et Python.

Pour configurer Cloud Functions afin d'activer les connexions à une instance Cloud SQL, procédez comme suit :

Vérifiez que l'instance créée ci-dessus possède une adresse IP publique. Vous pouvez le vérifier sur la page Présentation de l'instance dans la console Google Cloud. Si vous devez ajouter une adresse IP publique, consultez la section Configurer une adresse IP publique.
Obtenez le INSTANCE_CONNECTION_NAME de l'instance. Cette valeur est disponible :
- Sur la page Présentation de l'instance, dans la console Google Cloud, ou
- En exécutant la commande suivante : gcloud sql instances describe [INSTANCE_NAME]
Configurez le compte de service pour votre fonction. Si le compte de service d'autorisation appartient à un projet différent de l'instance Cloud SQL, activez l'API Cloud SQL Admin et ajoutez les autorisations IAM répertoriées ci-dessous pour les deux projets. Vérifiez que le compte de service dispose des rôles et autorisations Cloud SQL appropriés pour se connecter à Cloud SQL.
- Pour se connecter à Cloud SQL, le compte de service doit bénéficier de l'un des rôles IAM suivants :
  - Cloud SQL Client (rôle à privilégier)
  - Cloud SQL Editor
  - Cloud SQL Admin
  Vous pouvez également attribuer manuellement les autorisations IAM suivantes :
  - cloudsql.instances.connect
  - cloudsql.instances.get
Si vous utilisez Cloud Functions (2e génération) et non Cloud Functions (1re génération), les éléments suivants sont obligatoires (voir également Configurer Cloud Run) :
1. Initialisez votre fonction.
  Lorsque vous commencez à créer une fonction Cloud dans la console Google Cloud, le service Cloud Run sous-jacent n'a pas encore été créé. Vous ne pouvez pas configurer une connexion Cloud SQL tant que ce service n'est pas créé (en déployant la fonction Cloud).
2. Dans la console Google Cloud, dans l'angle supérieur droit de la page Informations sur la fonction, sous Fourni par Cloud Run, cliquez sur le lien pour accéder au cloud sous-jacent.
3. Sur la page Détails du service de Cloud Run, sélectionnez l'onglet Modifier et déployer la nouvelle révision.
4. Suivez les étapes standards (comme pour tout changement de configuration) afin de définir une nouvelle configuration pour une connexion Cloud SQL.
  Cela crée une révision Cloud Run, après quoi les révisions suivantes reçoivent automatiquement cette connexion Cloud SQL, sauf si vous la modifiez explicitement.

Adresse IP privée

Si le compte de service d'autorisation appartient à un projet différent de celui contenant l'instance Cloud SQL, procédez comme suit :

Dans les deux projets, activez l'API Cloud SQL Admin.
Pour le compte de service du projet contenant l'instance Cloud SQL, ajoutez les autorisations IAM.

Un connecteur d'accès au VPC sans serveur utilise des adresses IP privées pour gérer la communication avec votre réseau VPC. Pour vous connecter directement avec des adresses IP privées, procédez comme suit :

Assurez-vous que l'instance Cloud SQL créée précédemment possède une adresse IP privée. Si vous devez en ajouter une, consultez la page Configurer une adresse IP privée pour savoir comment procéder.
Créez un connecteur d'Accès au VPC sans serveur dans le même réseau VPC que votre instance Cloud SQL. Veuillez noter les conditions suivantes :

À moins que vous n'utilisiez le VPC partagé, votre connecteur doit se trouver dans le même projet et la même région que la ressource qui l'utilise, mais il peut envoyer du trafic à des ressources se trouvant dans d'autres régions.
L'accès au VPC sans serveur accepte la communication avec les réseaux VPC connectés à l'aide de Cloud VPN et de l'appairage de réseaux VPC.
L'accès au VPC sans serveur n'est pas compatible avec les anciens réseaux.

Configurez Cloud Functions de façon à utiliser le connecteur.
Connectez-vous avec l'adresse IP privée et le port 1433 de votre instance.

Se connecter à Cloud SQL

Une fois que vous avez configuré Cloud Functions, vous pouvez vous connecter à votre instance Cloud SQL.

Adresse IP publique (par défaut)

Pour les chemins d'accès des adresses IP publiques, Cloud Functions assure le chiffrement et se connecte à l'aide du proxy d'authentification Cloud SQL via des sockets Unix.

Se connecter avec des connecteurs Cloud SQL

Les connecteurs Cloud SQL sont des bibliothèques propres aux langages de programmation qui fournissent le chiffrement et l'autorisation basée sur IAM lors de la connexion à une instance Cloud SQL.

Python

Pour afficher cet extrait dans le contexte d'une application Web, consultez le fichier README sur GitHub.

import os

from google.cloud.sql.connector import Connector, IPTypes
import pytds

import sqlalchemy

def connect_with_connector() -> sqlalchemy.engine.base.Engine:
    """
    Initializes a connection pool for a Cloud SQL instance of SQL Server.

    Uses the Cloud SQL Python Connector package.
    """
    # 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.

    instance_connection_name = os.environ[
        "INSTANCE_CONNECTION_NAME"
    ]  # e.g. 'project:region:instance'
    db_user = os.environ.get("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'

    ip_type = IPTypes.PRIVATE if os.environ.get("PRIVATE_IP") else IPTypes.PUBLIC

    connector = Connector(ip_type)

    connect_args = {}
    # If your SQL Server instance requires SSL, you need to download the CA
    # certificate for your instance and include cafile={path to downloaded
    # certificate} and validate_host=False. This is a workaround for a known issue.
    if os.environ.get("DB_ROOT_CERT"):  # e.g. '/path/to/my/server-ca.pem'
        connect_args = {
            "cafile": os.environ["DB_ROOT_CERT"],
            "validate_host": False,
        }

    def getconn() -> pytds.Connection:
        conn = connector.connect(
            instance_connection_name,
            "pytds",
            user=db_user,
            password=db_pass,
            db=db_name,
            **connect_args
        )
        return conn

    pool = sqlalchemy.create_engine(
        "mssql+pytds://",
        creator=getconn,
        # ...
    )
    return pool

Java

Pour afficher cet extrait dans le contexte d'une application Web, consultez le fichier README sur GitHub.

Remarque :

CLOUD_SQL_CONNECTION_NAME doit être représenté sous la forme <MY-PROJECT>:<INSTANCE-REGION>:<INSTANCE-NAME>.
Pour en savoir plus sur les exigences de version Socket Factory des sockets JDBC pour le fichier pom.xml, cliquez ici.


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

public class ConnectorConnectionPoolFactory 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 INSTANCE_CONNECTION_NAME =
      System.getenv("INSTANCE_CONNECTION_NAME");
  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");

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

    // The following is equivalent to setting the config options below:
    // jdbc:sqlserver://;user=<DB_USER>;password=<DB_PASS>;databaseName=<DB_NAME>;
    // socketFactoryClass=com.google.cloud.sql.sqlserver.SocketFactory;
    // socketFactoryConstructorArg=<INSTANCE_CONNECTION_NAME>

    // 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
        .setDataSourceClassName("com.microsoft.sqlserver.jdbc.SQLServerDataSource");
    config.setUsername(DB_USER); // e.g. "root", "sqlserver"
    config.setPassword(DB_PASS); // e.g. "my-password"
    config.addDataSourceProperty("databaseName", DB_NAME);

    config.addDataSourceProperty("socketFactoryClass",
        "com.google.cloud.sql.sqlserver.SocketFactory");
    config.addDataSourceProperty("socketFactoryConstructorArg", INSTANCE_CONNECTION_NAME);

    // The Java Connector provides SSL encryption, so it should be disabled
    // at the driver level.
    config.addDataSourceProperty("encrypt", "false");

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

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

Go

Pour afficher cet extrait dans le contexte d'une application Web, consultez le fichier README sur GitHub.

package cloudsql

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

	"cloud.google.com/go/cloudsqlconn"
	mssql "github.com/denisenkom/go-mssqldb"
)

type csqlDialer struct {
	dialer     *cloudsqlconn.Dialer
	connName   string
	usePrivate bool
}

// DialContext adheres to the mssql.Dialer interface.
func (c *csqlDialer) DialContext(ctx context.Context, network, addr string) (net.Conn, error) {
	var opts []cloudsqlconn.DialOption
	if c.usePrivate {
		opts = append(opts, cloudsqlconn.WithPrivateIP())
	}
	return c.dialer.Dial(ctx, c.connName, opts...)
}

func connectWithConnector() (*sql.DB, error) {
	mustGetenv := func(k string) string {
		v := os.Getenv(k)
		if v == "" {
			log.Fatalf("Fatal Error in connect_connector.go: %s environment variable not set.\n", 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'
		instanceConnectionName = mustGetenv("INSTANCE_CONNECTION_NAME") // e.g. 'project:region:instance'
		usePrivate             = os.Getenv("PRIVATE_IP")
	)

	dbURI := fmt.Sprintf("user id=%s;password=%s;database=%s;", dbUser, dbPwd, dbName)
	c, err := mssql.NewConnector(dbURI)
	if err != nil {
		return nil, fmt.Errorf("mssql.NewConnector: %w", err)
	}
	dialer, err := cloudsqlconn.NewDialer(context.Background())
	if err != nil {
		return nil, fmt.Errorf("cloudsqlconn.NewDailer: %w", err)
	}
	c.Dialer = &csqlDialer{
		dialer:     dialer,
		connName:   instanceConnectionName,
		usePrivate: usePrivate != "",
	}

	dbPool := sql.OpenDB(c)
	if err != nil {
		return nil, fmt.Errorf("sql.Open: %w", err)
	}
	return dbPool, nil
}

Adresse IP privée

Pour les chemins d'accès des adresses IP privées, votre application se connecte directement à votre instance via un réseau VPC. Cette méthode utilise TCP pour se connecter directement à l'instance Cloud SQL sans utiliser le proxy d'authentification Cloud SQL.

Se connecter avec TCP

Connectez-vous en utilisant l'adresse IP privée de votre instance Cloud SQL en tant qu'hôte et le port 1433.

Python

Pour afficher cet extrait dans le contexte d'une application Web, consultez le fichier README sur GitHub.

import os

import sqlalchemy

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

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

    return pool

Java

Pour afficher cet extrait dans le contexte d'une application Web, consultez le fichier README sur GitHub.

Remarque :

CLOUD_SQL_CONNECTION_NAME doit être représenté sous la forme <MY-PROJECT>:<INSTANCE-REGION>:<INSTANCE-NAME>.
L'utilisation de l'argument ipTypes=PRIVATE force la connexion de SocketFactory à l'adresse IP privée associée à une instance.
Pour en savoir plus sur les exigences de version Socket Factory des sockets JDBC pour le fichier pom.xml, cliquez ici.


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();

    // Configure which instance and what database user to connect with.
    config.setJdbcUrl(
        String.format("jdbc:sqlserver://%s:%s;databaseName=%s", INSTANCE_HOST, DB_PORT, DB_NAME));
    config.setUsername(DB_USER); // e.g. "root", "sqlserver"
    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

Pour afficher cet extrait dans le contexte d'une application Web, consultez le fichier README sur GitHub.

const mssql = require('mssql');

// createTcpPool initializes a TCP connection pool for a Cloud SQL
// instance of SQL Server.
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 = {
    server: process.env.INSTANCE_HOST, // e.g. '127.0.0.1'
    port: parseInt(process.env.DB_PORT), // e.g. 1433
    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'
    options: {
      trustServerCertificate: true,
    },
    // ... Specify additional properties here.
    ...config,
  };
  // Establish a connection to the database.
  return mssql.connect(dbConfig);
};

Go

Pour afficher cet extrait dans le contexte d'une application Web, consultez le fichier README sur GitHub.

package cloudsql

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

	_ "github.com/denisenkom/go-mssqldb"
)

// connectTCPSocket initializes a TCP connection pool for a Cloud SQL
// instance of SQL Server.
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.\n", 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. '1433'
		dbName    = mustGetenv("DB_NAME")       // e.g. 'my-database'
	)

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

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

	// ...

	return dbPool, nil
}

PHP

Pour afficher cet extrait dans le contexte d'une application Web, consultez le fichier README sur GitHub.

namespace Google\Cloud\Samples\CloudSQL\SQLServer;

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(
                'sqlsrv:server=%s;Database=%s',
                $instanceHost,
                $dbName
            );

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

        return $conn;
    }
}

Bonnes pratiques et autres informations

Vous pouvez utiliser le proxy d'authentification Cloud SQL lorsque vous testez votre application en local. Pour obtenir des instructions détaillées, consultez le guide de démarrage rapide pour l'utilisation du proxy d'authentification Cloud SQL.

Pools de connexions

Les connexions aux bases de données sous-jacentes peuvent être supprimées, soit par le serveur de base de données lui-même, soit par l'infrastructure qui sous-tend Cloud Functions. Nous vous recommandons d'utiliser une bibliothèque cliente compatible avec les pools de connexions qui restaurent automatiquement les connexions client interrompues. De plus, nous recommandons d'utiliser un pool de connexions globalement limité, car cela augmente la probabilité que votre fonction réutilise la même connexion pour les invocations ultérieures de la fonction et qu'elle ferme naturellement la connexion lorsque l'instance est évincée (autoscaling à la baisse). Pour obtenir des exemples plus détaillés d'utilisation des pools de connexions, consultez la page Gérer les connexions à la base de données.

Limites de connexion

Cloud SQL impose une limite maximale de connexions simultanées, laquelle peut varier en fonction du moteur de base de données choisi (consultez la page Quotas et limites de Cloud SQL). Il est recommandé d'utiliser une connexion avec Cloud Functions, mais il est important de définir le nombre maximal de connexions sur 1.

Lorsque cela est possible, veillez à n'initialiser un pool de connexions que pour les fonctions qui doivent accéder à votre base de données. Certains pools de connexions créent des connexions de manière préemptive, ce qui peut consommer des ressources excédentaires et être comptabilisé dans vos limites de connexion. Pour cette raison, il est recommandé d'utiliser l'initialisation différée pour retarder la création d'un pool de connexions jusqu'à ce que cela soit nécessaire et n'inclure le pool de connexions que dans les fonctions où il est utilisé.

Pour obtenir des exemples plus détaillés de limitation du nombre de connexions, consultez la page Gérer les connexions à la base de données.

Limites de quota d'API

Cloud Functions fournit un mécanisme permettant de se connecter à l'aide du proxy d'authentification Cloud SQL, qui utilise l'API Cloud SQL Admin. Les limites de quota d'API s'appliquent au proxy d'authentification Cloud SQL. Le quota de l'API Cloud SQL Admin utilisé correspond approximativement au double du nombre d'instances Cloud SQL configurées ou au nombre total de fonctions déployées. Vous pouvez définir le nombre maximal d'appels simultanés pour modifier le quota d'API que vous prévoyez d'utiliser. Cloud Functions impose également des limitations de débit sur le nombre d'appels d'API autorisés par tranche de 100 secondes.

Étapes suivantes

Apprenez-en plus sur Cloud Functions.
Apprenez-en plus sur le déploiement des fonctions Cloud.
Découvrez comment spécifier des déclencheurs pour Cloud Functions.
Découvrez comment configurer Cloud Functions.