À propos des options de connexion

MySQL | PostgreSQL | SQL Server

Cette page présente les différentes manières de se connecter à l'instance Cloud SQL et décrit les options d'authentification et d'autorisation disponibles.

Présentation

Lorsque vous envisagez de vous connecter à votre instance Cloud SQL, vous devez tenir compte de nombreux éléments, tels que :

• Souhaitez-vous que votre instance Cloud SQL soit accessible depuis Internet ou reste privée dans un réseau de cloud privé virtuel (VPC), ou qu'elle soit accessible à la fois publiquement et de manière privée ?
• Comptez-vous écrire votre propre code de connexion ou vous connecter à l'aide d'outils accessibles publiquement, comme par exemple le proxy d'authentification Cloud SQL ou un client psql ?
• Voulez-vous imposer le chiffrement via SSL/TLS ou autoriser le trafic non chiffré ?

Les sections suivantes présentent les options fournies par Cloud SQL pour se connecter, autoriser et s'authentifier auprès de votre base de données.

• Comment se connecter : chemin réseau à utiliser pour atteindre votre instance :
  • Une adresse IP interne uniquement, VPC uniquement (privée).
  • Une adresse IP externe et accessible à Internet (publique).
• Comment s'authentifier : connexions autorisées vous permettant de vous connecter à votre instance Cloud SQL :
  • Les bibliothèques de connecteurs Cloud SQL et de proxy d'authentification Cloud SQL pour Java et Python, qui fournissent un accès basé sur IAM.
  • Certificats SSL/TLS autogérés : ils n'autorisent que les connexions basées sur des clés publiques spécifiques.
  • Réseaux autorisés : liste des adresses IP autorisées à se connecter.
• Comment s'authentifier : méthode de connexion à votre base de données.
  • Authentification intégrée à la base de données : connectez-vous à l'aide d'un nom d'utilisateur/mot de passe défini dans le moteur de base de données.
  • Authentification de la base de données IAM : connectez-vous avec une adresse e-mail ou avec un jeton OAuth 2.0 comme mot de passe.

Utilisez les informations suivantes pour déterminer les options de connexion, d'autorisation et d'authentification qui répondent le mieux à vos besoins.

Vous pouvez créer un compte pour évaluer les performances de Cloud SQL en conditions réelles. Les nouveaux clients bénéficient également de 300 $ de crédits gratuits à dépenser sur Cloud SQL pour exécuter, tester et déployer des charges de travail. Des frais ne vous seront facturés que si vous choisissez de passer à une version payante.

Inscrivez-vous pour essayer Cloud SQL gratuitement.

Avant de commencer

Le fait d'accorder l'accès à une application ne permet pas automatiquement à un compte utilisateur de base de données de se connecter à l'instance. Pour pouvoir vous connecter à cette dernière, vous devez disposer d'un compte utilisateur de base de données permettant d'établir la connexion. Pour les nouvelles instances, cela signifie que vous devez avoir configuré le compte utilisateur par défaut. Pour en savoir plus, consultez la page Gérer les utilisateurs avec l'authentification intégrée.

Établir une connexion avec Cloud SQL

Les connexions aux bases de données consomment des ressources sur le serveur et sur l'application de connexion. Suivez toujours les bonnes pratiques en matière de gestion des connexions afin de réduire au maximum l'encombrement de votre application et les risques de dépassement des limites de connexion Cloud SQL. Pour en savoir plus, consultez la page Gérer les connexions à la base de données.

Adresses IP publique et privée

Dans Cloud SQL, une adresse IP publique signifie que l'instance est accessible via l'Internet public. En revanche, les instances qui n'utilisent que des adresses IP privées ne sont pas accessibles via l'Internet public, mais le sont via un cloud privé virtuel (VPC). Les instances Cloud SQL peuvent avoir une adresse IP publique et une adresse IP privée.

Adresse IP privée

Une adresse IP privée est une adresse IPv4 qui est accessible sur un cloud privé virtuel (VPC).

Vous pouvez utiliser cette adresse pour vous connecter à partir d'autres ressources ayant accès au VPC. Les connexions via une adresse IP privée offrent généralement une latence plus faible et des vecteurs d'attaque limités, car leur transit par Internet n'est pas nécessaire. Si vous le souhaitez, vous pouvez exiger que toutes les connexions utilisent le proxy Cloud SQL ou les certificats SSL autogérés.

Lorsque la connexion s'effectue à partir d'un client sur une ressource ayant accès à un réseau VPC, il est préférable d'utiliser une adresse IP privée. Pour en savoir plus sur les ressources pouvant utiliser une adresse IP privée, consultez la page Conditions requises pour utiliser une adresse IP privée.

Pour les chemins d'accès des adresses IP privées, les services et applications suivants se connectent directement à votre instance via l'accès au VPC sans serveur :

• Environnement standard App Engine
• Environnement flexible App Engine
• Cloud Run Functions
• Cloud Run

Découvrez comment utiliser une adresse IP privée avec Cloud SQL.

Pour obtenir des instructions sur l'ajout d'une adresse IP privée à votre instance, consultez l'une des pages suivantes :

• Configurer la connectivité IP privée
• Se connecter à une instance à l'aide de Private Service Connect

Adresse IP publique

Une adresse IP publique est une adresse IPv4 qui est accessible en externe sur l'Internet public. Cette adresse peut recevoir des connexions provenant d'appareils internes et externes au réseau Google, y compris depuis votre domicile ou votre bureau.

Pour sécuriser votre instance, les connexions à une instance Cloud SQL utilisant une adresse IP publique doivent être autorisées via le proxy d'authentification Cloud SQL ou les réseaux autorisés.

La configuration d'une instance avec une adresse IP publique est préférable lorsque vous vous connectez depuis un client qui ne répond pas aux exigences d'un VPC.

Pour savoir comment ajouter une adresse IP publique à votre instance, consultez la page Configurer la connectivité IP publique.

Pour en savoir plus sur la connexion d'un client psql à une instance Cloud SQL à l'aide d'une adresse IP publique, consultez la page Se connecter à l'aide d'un client de base de données.

Adresses IP attribuées de manière dynamique

Certaines applications doivent se connecter à votre instance Cloud SQL au moyen d'une adresse IP attribuée de manière dynamique ou éphémère. C'est le cas, entre autres, des applications PaaS (Platform as a Service).

Vous devez dans ces conditions utiliser le proxy d'authentification Cloud SQL.

Accorder des autorisations avec Cloud SQL

Remarque : Ces options vous permettent seulement de contrôler quelles connexions sont autorisées à se connecter à votre instance. Vous devez toujours fournir un nom d'utilisateur et un mot de passe de base de données pour vous authentifier auprès du moteur de base de données.

Connecteurs de langage Cloud SQL

Les connecteurs de langage Cloud SQL sont des bibliothèques clientes qui fournissent des fonctionnalités de chiffrement et d'autorisation IAM lors de la connexion à une instance Cloud SQL. Cloud SQL recommande d'utiliser les connecteurs de langage Cloud SQL pour se connecter à votre instance Cloud SQL plutôt que d'autres options de connexion.

Vous pouvez utiliser ces bibliothèques directement à partir de leur langage de programmation compatible. Elles fournissent la même authentification que le proxy d'authentification Cloud SQL, sans processus externe. Cela permet de renforcer la sécurité et de réduire les exigences de configuration pour la connexion à Cloud SQL. Les connecteurs de langage Cloud SQL utilisent également le même code lorsque la connexion est établie à l'aide d'une adresse IP publique ou d'une adresse IP privée.

Pour commencer, consultez la section À propos des connecteurs de langage Cloud SQL.

Proxy d'authentification Cloud SQL

Le proxy d'authentification Cloud SQL vous permet d'authentifier et de sécuriser vos connexions à l'aide des autorisations IAM (Identity and Access Management). Le proxy d'authentification Cloud SQL valide les connexions en utilisant les identifiants d'un utilisateur ou d'un compte de service et en encapsulant la connexion dans une couche SSL/TLS qui est autorisée pour une instance Cloud SQL. Pour en savoir plus sur le fonctionnement du proxy d'authentification Cloud SQL, consultez la page À propos du proxy d'authentification Cloud SQL.

L'utilisation du proxy d'authentification Cloud SQL est recommandée pour l'authentification des connexions à une instance Cloud SQL, car il s'agit de la méthode la plus sécurisée.

Le proxy d'authentification Cloud SQL est une bibliothèque Open Source distribuée en tant que binaire exécutable. Le proxy d'authentification Cloud SQL agit comme un serveur intermédiaire qui écoute les connexions entrantes, les encapsule en SSL/TLS, puis les transmet à une instance Cloud SQL.

Certains environnements fournissent un mécanisme de connexion à l'aide du proxy d'authentification Cloud SQL. Pour savoir comment vous connecter à l'aide de ces environnements, consultez l'une des pages suivantes :

• Se connecter depuis Cloud Run
• Se connecter depuis des fonctions Cloud Run
• Se connecter depuis l'environnement standard App Engine
• Se connecter depuis l'environnement flexible App Engine
• Se connecter depuis Google Kubernetes Engine

Certificats SSL/TLS autogérés

Au lieu d'utiliser le proxy d'authentification Cloud SQL pour chiffrer vos connexions, il est possible de configurer des certificats SSL/TLS client/serveur spécifiques à une instance Cloud SQL. Ces certificats permettent à la fois de valider le client/serveur et de chiffrer les connexions entre eux.

Il est fortement recommandé d'utiliser des certificats SSL/TLS autogérés pour assurer le chiffrement lorsque vous n'utilisez pas le proxy d'authentification Cloud SQL. À défaut, vos données sont transmises de manière non sécurisée, et peuvent être interceptées ou inspectées par un tiers.

Pour commencer à utiliser les certificats SSL/TLS autogérés, consultez la section Autoriser avec des certificats SSL/TLS.

Réseaux autorisés

Remarque : Nous vous recommandons vivement de toujours employer des certificats SSL/TLS autogérés lorsque vous utilisez des réseaux autorisés pour authentifier les connexions. À moins d'être chiffré, votre trafic peut faire l'objet d'interception par des tiers.

À moins d'utiliser le proxy d'authentification Cloud SQL, les connexions à l'adresse IP publique d'une instance ne sont autorisées que si elles proviennent d'un réseau autorisé. Les réseaux autorisés sont des adresses IP ou des plages spécifiées par l'utilisateur auxquelles il est possible de se connecter.

Avertissement : Faites preuve de prudence lorsque vous ajoutez des réseaux autorisés. Étant donné que tous les appareils d'un réseau partagent souvent la même adresse IP externe, autoriser une seule adresse peut autoriser tous les appareils du même réseau, plutôt qu'un seul client.

Pour commencer à utiliser les réseaux autorisés, consultez la page Autoriser avec des réseaux autorisés.

S'authentifier auprès de Cloud SQL

L'authentification permet de contrôler les accès en validant l'identité d'un utilisateur. Pour les utilisateurs finaux, l'authentification est réalisée lorsque l'utilisateur saisit des identifiants (un nom d'utilisateur et un mot de passe). Pour les applications, l'authentification est effectuée lorsque les identifiants d'un utilisateur sont attribués à un compte de service.

Cloud SQL utilise l'authentification intégrée à la base de données qui authentifie à l'aide d'un nom d'utilisateur et d'un mot de passe. Pour en savoir plus, consultez la page Créer et gérer des utilisateurs PostgreSQL.

Cloud SQL est également intégré à IAM pour vous aider à surveiller et à gérer l'accès à la base de données des utilisateurs et des comptes de service. Cette fonctionnalité s'appelle l'authentification IAM pour les bases de données.

En savoir plus sur l'authentification IAM pour les bases de données.

Découvrez comment créer et gérer des utilisateurs qui utilisent l'authentification de la base de données IAM.

Outils permettant de se connecter à Cloud SQL

Le tableau suivant contient des options permettant de se connecter à Cloud SQL :

Option de connexion	En savoir plus
Proxy d'authentification Cloud SQL	À propos du proxy d'authentification Cloud SQL Se connecter à l'aide du proxy d'authentification Cloud SQL Se connecter à l'aide de l'image Docker du proxy d'authentification Cloud SQL
gcloud CLI	gcloud sql connect
Connecteurs de langage Cloud SQL	Se connecter à l'aide des connecteurs Cloud SQL pour Java, Python et Go.
Cloud Shell	Se connecter via Cloud Shell
Cloud Code	Se connecter via Cloud Code dans l'IDE JetBrains
Se connecter à l'aide d'outils d'administration de bases de données tiers
pgAdmin	pgAdmin.org pour PostgreSQL
Toad Edge	Toad Edge pour PostgreSQL
Blendo	Connecter PostgreSQL à Google Cloud SQL avec Blendo

Exemples de code

Vous pouvez vous connecter au proxy d'authentification Cloud SQL au moyen de n'importe quel langage permettant la connexion à un socket Unix ou TCP. Vous trouverez ci-dessous des extraits de code tirés d'exemples complets disponibles sur GitHub pour vous aider à comprendre comment ils fonctionnent ensemble dans votre application.

Se connecter avec TCP

Instruction d'appel du proxy d'authentification Cloud SQL :

./cloud-sql-proxy INSTANCE_CONNECTION_NAME &

Python

Pour afficher cet extrait dans le contexte d'une application Web, consultez le fichier README sur 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

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

    // 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

Pour afficher cet extrait dans le contexte d'une application Web, consultez le fichier README sur 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);
};

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"

	// 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#

Pour afficher cet extrait dans le contexte d'une application Web, consultez le fichier README sur 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

Pour afficher cet extrait dans le contexte d'une application Web, consultez le fichier README sur 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

Pour afficher cet extrait dans le contexte d'une application Web, consultez le fichier README sur 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;
    }
}

Se connecter avec des sockets Unix

Instruction d'appel du proxy d'authentification Cloud SQL :

./cloud-sql-proxy --unix-socket /cloudsql INSTANCE_CONNECTION_NAME &

Python

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

import os

import sqlalchemy


def connect_unix_socket() -> sqlalchemy.engine.base.Engine:
    """Initializes a Unix socket 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_user = os.environ["DB_USER"]  # e.g. 'my-database-user'
    db_pass = os.environ["DB_PASS"]  # e.g. 'my-database-password'
    db_name = os.environ["DB_NAME"]  # e.g. 'my-database'
    unix_socket_path = os.environ[
        "INSTANCE_UNIX_SOCKET"
    ]  # e.g. '/cloudsql/project:region:instance'

    pool = sqlalchemy.create_engine(
        # Equivalent URL:
        # postgresql+pg8000://<db_user>:<db_pass>@/<db_name>
        #                         ?unix_sock=<INSTANCE_UNIX_SOCKET>/.s.PGSQL.5432
        # Note: Some drivers require the `unix_sock` query parameter to use a different key.
        # For example, 'psycopg2' uses the path set to `host` in order to connect successfully.
        sqlalchemy.engine.url.URL.create(
            drivername="postgresql+pg8000",
            username=db_user,
            password=db_pass,
            database=db_name,
            query={"unix_sock": f"{unix_socket_path}/.s.PGSQL.5432"},
        ),
        # ...
    )
    return pool

Java

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

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 INSTANCE_UNIX_SOCKET = System.getenv("INSTANCE_UNIX_SOCKET");
  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 URL is equivalent to setting the config options below:
    // jdbc:postgresql:///<DB_NAME>?cloudSqlInstance=<INSTANCE_CONNECTION_NAME>&
    // socketFactory=com.google.cloud.sql.postgres.SocketFactory&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", DB_NAME));
    config.setUsername(DB_USER); // e.g. "root", _postgres"
    config.setPassword(DB_PASS); // e.g. "my-password"

    config.addDataSourceProperty("socketFactory", "com.google.cloud.sql.postgres.SocketFactory");
    config.addDataSourceProperty("cloudSqlInstance", INSTANCE_CONNECTION_NAME);

    // Unix sockets are not natively supported in Java, so it is necessary to use the Cloud SQL
    // Java Connector to connect. When setting INSTANCE_UNIX_SOCKET, the connector will 
    // call an external package that will enable Unix socket connections.
    // Note: For Java users, the Cloud SQL Java Connector can provide authenticated connections
    // which is usually preferable to using the Cloud SQL Proxy with Unix sockets.
    // See https://github.com/GoogleCloudPlatform/cloud-sql-jdbc-socket-factory for details.
    if (INSTANCE_UNIX_SOCKET != null) {
      config.addDataSourceProperty("unixSocketPath", INSTANCE_UNIX_SOCKET);
    }



    // ... 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 Knex = require('knex');

// createUnixSocketPool initializes a Unix socket connection pool for
// a Cloud SQL instance of Postgres.
const createUnixSocketPool = 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.
  return Knex({
    client: 'pg',
    connection: {
      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'
      host: process.env.INSTANCE_UNIX_SOCKET, // e.g. '/cloudsql/project:region:instance'
    },
    // ... Specify additional properties here.
    ...config,
  });
};

C#

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

using Npgsql;
using System;

namespace CloudSql
{
    public class PostgreSqlUnix
    {
        public static NpgsqlConnectionStringBuilder NewPostgreSqlUnixSocketConnectionString()
        {
            // Equivalent connection string:
            // "Server=<INSTANCE_UNIX_SOCKET>;Uid=<DB_USER>;Pwd=<DB_PASS>;Database=<DB_NAME>"
            var connectionString = new NpgsqlConnectionStringBuilder()
            {
                // The Cloud SQL proxy provides encryption between the proxy and instance.
                SslMode = SslMode.Disable,

                // 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_UNIX_SOCKET"), // e.g. '/cloudsql/project:region:instance'
                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'
            };
            connectionString.Pooling = true;
            // Specify additional properties here.
            return connectionString;
        }
    }
}

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"

	// 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"
)

// connectUnixSocket initializes a Unix socket connection pool for
// a Cloud SQL instance of Postgres.
func connectUnixSocket() (*sql.DB, error) {
	mustGetenv := func(k string) string {
		v := os.Getenv(k)
		if v == "" {
			log.Fatalf("Fatal Error in connect_unix.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'
		unixSocketPath = mustGetenv("INSTANCE_UNIX_SOCKET") // e.g. '/cloudsql/project:region:instance'
		dbName         = mustGetenv("DB_NAME")              // e.g. 'my-database'
	)

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

	// 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
}

Ruby

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

unix: &unix
  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" } %>
  # Specify the Unix socket path as host
  host: "<%= ENV["INSTANCE_UNIX_SOCKET"] %>"

PHP

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

namespace Google\Cloud\Samples\CloudSQL\Postgres;

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

class DatabaseUnix
{
    public static function initUnixDatabaseConnection(): 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'
            $instanceUnixSocket = getenv('INSTANCE_UNIX_SOCKET'); // e.g. '/cloudsql/project:region:instance'

            // Connect using UNIX sockets
            $dsn = sprintf(
                'pgsql:dbname=%s;host=%s',
                $dbName,
                $instanceUnixSocket
            );

            // 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 $instanceUnixSocket (for UNIX socket mode). ' .
                        'The PHP error was %s',
                    $e->getMessage()
                ),
                (int) $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()
                ),
                (int) $e->getCode(),
                $e
            );
        }

        return $conn;
    }
}

Résoudre les problèmes

Si vous rencontrez des problèmes de connexion, consultez les pages suivantes pour obtenir des conseils de débogage ou de recherche de solutions à des problèmes connus :

• Déboguer les problèmes de connexion
• Erreurs de connectivité connues
• Dépannage des problèmes de connexion au proxy d'authentification Cloud SQL
• Problèmes de connexion courants

Étape suivante

• Découvrez comment vous connecter grâce au guide de démarrage rapide de Cloud SQL pour PostgreSQL.
• Découvrez les bonnes pratiques de gestion des connexions à la base de données.
• Apprenez-en davantage sur l'authentification IAM pour les bases de données.
• Découvrez comment vous connecter à l'aide d'un client psql à partir d'une machine locale ou de Compute Engine.
• Découvrez comment configurer la connectivité IP.
• Apprenez-en plus sur le proxy d'authentification Cloud SQL.
• Apprenez-en plus sur les Options de support.