Informazioni sulle opzioni di connessione

Questa pagina fornisce una panoramica dei modi in cui puoi connetterti all'istanza Cloud SQL e descrive le opzioni di autenticazione e autorizzazione disponibili.

Panoramica

Quando cerchi come connetterti all'istanza Cloud SQL, devi tenere presente diverse opzioni, tra cui:

  • Vuoi che l'istanza Cloud SQL sia accessibile da Internet o che rimanga privata all'interno di una rete Virtual Private Cloud (VPC) o che sia accessibile pubblicamente e privatamente?
  • Intendi scrivere il tuo codice di connessione o connetterti utilizzando strumenti disponibili pubblicamente come il proxy Cloud SQL Auth o un client sqlcmd?
  • Vuoi richiedere la crittografia tramite SSL/TLS o consentire il traffico non criptato?

Nelle sezioni seguenti sono descritte le opzioni offerte da Cloud SQL per connettersi, autorizzare e autenticare il database.

  • Come connettersi: il percorso di rete che utilizzi per raggiungere la tua istanza:
    • Un indirizzo IP interno solo VPC (privato).
    • Un indirizzo IP esterno accessibile da Internet (pubblico).
  • Come autorizzare: le connessioni autorizzate e autorizzate a connettersi all'istanza Cloud SQL:
    • Proxy di Cloud SQL Auth e librerie di connettori Cloud SQL per Java e Python, che forniscono l'accesso in base a IAM.
    • Certificati SSL/TLS autogestiti: questi ultimi consentono solo le connessioni in base a chiavi pubbliche specifiche.
    • Reti autorizzate: un elenco di indirizzi IP autorizzati a connettersi.
  • Come eseguire l'autenticazione: il metodo per accedere al tuo database.
    • Autenticazione database integrata: accedi con il nome utente o la password impostati nel motore di database.

Utilizza le informazioni che seguono per decidere quale connessione, autorizzazione e opzioni di autenticazione sono più adatte alle tue esigenze.

Prima di iniziare

La concessione dell'accesso a un'applicazione non permette automaticamente all'account utente di database di connettersi all'istanza. Prima di poterti connettere a un'istanza, devi disporre di un account utente di database con cui connetterti. Per le nuove istanze, questo significa che devi aver configurato l'account utente predefinito. Scopri di più.

Opzioni di connessione

Le connessioni di database consumano risorse sul server e sull'applicazione di connessione. Utilizza sempre buone prassi di gestione delle connessioni per ridurre al minimo l'impatto della tua applicazione e ridurre la probabilità di superare i limiti di connessione di Cloud SQL. Per ulteriori informazioni, consulta Gestione delle connessioni ai database.

IP pubblico e privato

In Cloud SQL, l'IP pubblico indica che l'istanza è accessibile tramite la rete Internet pubblica. Al contrario, le istanze che utilizzano solo l'IP privato non sono accessibili tramite la rete Internet pubblica, ma sono accessibili tramite un Virtual Private Cloud (VPC). Le istanze Cloud SQL possono avere un indirizzo IP pubblico e privato.

IP privato

Un IP privato è un indirizzo IPv4 o IPv6 accessibile su un Virtual Private Cloud (VPC).

Puoi utilizzare questo indirizzo per connetterti da altre risorse con accesso al VPC. In genere le connessioni tramite IP privato forniscono latenza più bassa e vettori di attacco limitati, in quanto non richiedono l'attraversamento su Internet. Facoltativamente, puoi richiedere che tutte le connessioni utilizzino il proxy Cloud SQL o i certificati SSL autogestiti.

La configurazione dell'istanza con IP privato è preferibile quando si esegue la connessione da un client su una risorsa con accesso a un VPC. Per ulteriori informazioni sulle risorse che possono utilizzare l'IP privato, consulta i requisiti per l'IP privato.

Per i percorsi IP privati, i seguenti servizi e applicazioni si connettono direttamente alla tua istanza tramite Accesso VPC serverless:

  • Ambiente standard di App Engine
  • Ambiente flessibile di App Engine
  • Cloud Functions
  • Cloud Run

Scopri di più sull'utilizzo dell'IP privato con Cloud SQL

Per istruzioni su come aggiungere un IP privato alla tua istanza, consulta Configurazione della connettività IP privato.

IP pubblico

Un IP pubblico è un indirizzo IPv4 o IPv6 disponibile esternamente sulla rete Internet pubblica. Questo indirizzo può ricevere connessioni da dispositivi sia all'interno sia all'esterno della rete di Google, anche da luoghi come casa o ufficio.

Per proteggere la tua istanza, qualsiasi connessione a un'istanza Cloud SQL che utilizza un IP pubblico deve essere autorizzata utilizzando il proxy Cloud Auth o le reti autorizzate.

La configurazione dell'istanza con un IP pubblico è ideale in caso di connessione da un client che non soddisfa i requisiti di un VPC.

Per istruzioni su come aggiungere un IP pubblico alla tua istanza, consulta Configurazione della connettività IP pubblica.

Per informazioni sulla connessione di un client sqlcmd a un'istanza Cloud SQL tramite IP pubblico, consulta Connessione tramite un client di database.

Opzioni di autorizzazione

Proxy di Cloud SQL Auth

Il proxy Cloud SQL Auth ti consente di autorizzare e proteggere le tue connessioni utilizzando le autorizzazioni Identity and Access Management (IAM). Il proxy di autenticazione Cloud SQL convalida le connessioni utilizzando le credenziali per un account utente o di servizio e aggrega la connessione in un livello SSL/TLS autorizzato per un'istanza Cloud SQL. Per maggiori dettagli sul funzionamento del proxy di autenticazione Cloud SQL, vedi Informazioni sul proxy di autenticazione Cloud SQL.

L'utilizzo del proxy Cloud Auth è il metodo consigliato per autenticare le connessioni a un'istanza Cloud SQL, perché è il metodo più sicuro.

Il proxy Cloud Auth è una libreria open source distribuita come file eseguibile. Il proxy Cloud SQL Auth funge da server intermediario che rimane in ascolto delle connessioni in entrata, li aggrega a SSL/TLS e poi passa a un'istanza Cloud SQL.

Alcuni ambienti forniscono un meccanismo che si connette utilizzando il proxy Cloud SQL Auth. Per istruzioni sulla connessione tramite questi ambienti, consulta uno dei seguenti:

Librerie di connettori Cloud SQL per Java e Python

Cloud SQL offre librerie client che forniscono crittografia e autorizzazione basata su IAM durante la connessione a un'istanza Cloud SQL utilizzando connettori Java e Python.

Puoi utilizzare queste librerie direttamente dall'ambiente del linguaggio. Forniscono la stessa autenticazione del proxy Cloud SQL Auth senza richiedere un processo esterno. Per iniziare, consulta la sezione Connessione utilizzando i connettori di Cloud SQL.

Certificati SSL/TLS autogestiti

Invece di utilizzare il proxy Cloud SQL Auth per criptare le tue connessioni, puoi configurare certificati SSL/TLS client/server specifici per un'istanza Cloud SQL. Questi certificati vengono utilizzati sia per convalidare il client che per il server, per fare in modo che gli altri elementi siano oggetto di crittografia e per criptare le connessioni tra le due.

Consigliamo vivamente di utilizzare certificati SSL/TLS autogestiti per fornire la crittografia quando non si utilizza il proxy di autenticazione Cloud SQL. In caso contrario, i dati verranno trasmessi in modo non sicuro e potrebbero essere intercettati o controllati da terze parti.

Per iniziare a utilizzare i certificati SSL/TLS autogestiti, consulta la sezione Autorizzazione con certificati SSL/TLS.

Reti autorizzate

A meno che non utilizzi il proxy Cloud SQL Auth, le connessioni all'indirizzo IP pubblico di un'istanza sono consentite solo se la connessione proviene da una rete autorizzata. Le reti autorizzate sono indirizzi o intervalli di indirizzi IP che l'utente ha specificato come autorizzati a connettersi.

Per iniziare a utilizzare le reti autorizzate, consulta la pagina relativa all'autorizzazione con le reti autorizzate.

Opzioni di autenticazione

L'autenticazione fornisce il controllo dell'accesso tramite la verifica dell'identità di un utente. Per gli utenti finali, l'autenticazione viene ottenuta quando l'utente inserisce le credenziali (nome utente e password). Per le applicazioni, l'autenticazione viene ottenuta quando le credenziali di un utente vengono assegnate a un account di servizio.

Cloud SQL utilizza l'autenticazione integrata del database per l'autenticazione tramite nome utente e password. Per ulteriori informazioni, consulta Creazione e gestione degli utenti di SQL Server.

Strumenti per la connessione

La seguente tabella contiene alcune opzioni per la connessione a Cloud SQL:

Opzione di connessione Scopri di più
Proxy di autenticazione Cloud SQL
gcloud
Connettori di linguaggio Cloud SQL
Cloud Shell
Connettiti utilizzando strumenti di amministrazione di database di terze parti
SQL Server Management Studio
Esplorazione oggetti SMSS
Visual Studio

Esempi di codice

Puoi connetterti al proxy Cloud SQL Auth da qualsiasi linguaggio che ti consenta di connetterti a un socket TCP. Di seguito sono riportati alcuni snippet di codice di esempi completi su GitHub per aiutarti a comprendere come interagiscono nella tua applicazione.

Connessione con TCP

Istruzione di chiamata proxy Cloud SQL Auth:

./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAME=tcp:1433 &

Python

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

# Remember - storing secrets in plaintext is potentially unsafe. Consider using
# something like https://cloud.google.com/secret-manager/docs/overview to help keep
# secrets secret.
db_user = os.environ["DB_USER"]
db_pass = os.environ["DB_PASS"]
db_name = os.environ["DB_NAME"]
db_host = os.environ["DB_HOST"]

# Extract host and port from environment variable DB_HOST
host_args = db_host.split(":")
db_hostname, db_port = host_args[0], int(host_args[1])

# SQL Server drivers don't account for this
if db_hostname == "localhost":
    db_hostname = "127.0.0.1"

# The SQLAlchemy engine will help manage interactions, including automatically
# managing a pool of connections to your database
pool = sqlalchemy.create_engine(
    # Equivalent URL:
    # mssql+pytds://<db_user>:<db_pass>@/<host>:<port>/<db_name>?driver=ODBC+Driver+17+for+SQL+Server
    sqlalchemy.engine.url.URL.create(
        "mssql+pytds",
        username=db_user,
        password=db_pass,
        database=db_name,
        host=db_hostname,
        port=db_port,
    ),
    **db_config
)

Java

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

Nota:

  • CLOUD_SQL_CONNECTION_NAME deve essere rappresentato come <MY-PROJECT>:<INSTANCE-REGION>:<INSTANCE-NAME>
  • L'uso dell'argomento ipTypes=PRIVATE forza la connessione di SocketFactory con l'IP privato di un'istanza
  • Consulta qui i requisiti per la versione di fabbrica del socket JDBC per il file pom.xml.

// Note: For Java users, the Cloud SQL JDBC Socket Factory can provide authenticated connections
// which is preferred to using the Cloud SQL Proxy with Unix sockets.
// See https://github.com/GoogleCloudPlatform/cloud-sql-jdbc-socket-factory for details.

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

// ... Specify additional connection properties here.

// ...

// Initialize the connection pool using the configuration object.
DataSource pool = new HikariDataSource(config);

Node.js

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

const createPool = async () => {
  const config = {pool: {}, options: {}};

  // Check if a Secret Manager secret version is defined
  // If a version is defined, retrieve the secret from Secret Manager and set as the DB_PASS
  const {CLOUD_SQL_CREDENTIALS_SECRET} = process.env;
  if (CLOUD_SQL_CREDENTIALS_SECRET) {
    const secrets = await accessSecretVersion(CLOUD_SQL_CREDENTIALS_SECRET);
    try {
      process.env.DB_PASS = secrets.toString();
    } catch (err) {
      err.message = `Unable to parse secret from Secret Manager. Make sure that the secret is JSON formatted: \n ${err.message} `;
      throw err;
    }
  }

  config.user = process.env.DB_USER; // e.g. 'my-db-user'
  config.password = process.env.DB_PASS; // e.g. 'my-db-password'
  config.database = process.env.DB_NAME; // e.g. 'my-database'
  // set the server to '172.17.0.1' when connecting from App Engine Flex
  config.server = process.env.DEPLOYED ? '172.17.0.1' : '127.0.0.1';
  config.port = 1433;

  // ...
  config.options.trustServerCertificate = true;
  return await mssql.connect(config);
};

Go

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

var (
	dbUser    = mustGetenv("DB_USER") // e.g. 'my-db-user'
	dbPwd     = mustGetenv("DB_PASS") // e.g. 'my-db-password'
	dbTCPHost = mustGetenv("DB_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("mssql", dbURI)
if err != nil {
	return nil, fmt.Errorf("sql.Open: %v", err)
}

// ...

return dbPool, nil

C#

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

            // Equivalent connection string:
            // "User Id=<DB_USER>;Password=<DB_PASS>;Server=<DB_HOST>;Database=<DB_NAME>;"
            var connectionString = new SqlConnectionStringBuilder()
            {
                // Remember - storing secrets in plain text is potentially unsafe. Consider using
                // something like https://cloud.google.com/secret-manager/docs/overview to help keep
                // secrets secret.
                DataSource = Environment.GetEnvironmentVariable("DB_HOST"),     // e.g. '127.0.0.1'
                // Set Host to 'cloudsql' when deploying to App Engine Flexible environment
                UserID = Environment.GetEnvironmentVariable("DB_USER"),         // e.g. 'my-db-user'
                Password = Environment.GetEnvironmentVariable("DB_PASS"),       // e.g. 'my-db-password'
                InitialCatalog = Environment.GetEnvironmentVariable("DB_NAME"), // e.g. 'my-database'

                // The Cloud SQL proxy provides encryption between the proxy and instance
                Encrypt = false,
            };
            connectionString.Pooling = true;
            // ...
            return connectionString;

Ruby

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

development:
  adapter: sqlserver
  # Configure additional properties here.
  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("DB_HOST") { "127.0.0.1" }%> # '172.17.0.1' if deployed to GAE Flex
  port: <%= ENV.fetch("DB_PORT") { 1433 }%> 

PHP

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

// $username = 'your_db_user';
// $password = 'yoursupersecretpassword';
// $dbName = 'your_db_name';
// $dbHost = "127.0.0.1";

// Connect using TCP
$dsn = sprintf('sqlsrv:server=%s;Database=%s', $dbHost, $dbName);

// Connect to the database
$conn = new PDO($dsn, $username, $password, $connConfig);

Risolvi problemi

Se hai problemi di connessione, consulta le seguenti pagine per assistenza in merito al debug o alla ricerca di soluzioni a problemi noti:

Passaggi successivi