Informationen zu Verbindungsoptionen

Diese Seite bietet eine Übersicht über die Möglichkeiten, eine Verbindung zu Ihrer Cloud SQL-Instanz herzustellen, und beschreibt die verfügbaren Authentifizierungs- und Autorisierungsoptionen.

Übersicht

Bei der Auswahl einer Verbindung zu Ihrer Cloud SQL-Instanz ist Folgendes zu beachten:

  • Möchten Sie, dass Ihre Cloud SQL-Instanz über das Internet zugänglich ist, in einem VPC-Netzwerk (Virtual Private Cloud) privat aufbewahrt wird oder sowohl öffentlich als auch privat darauf zugegriffen werden kann?
  • Möchten Sie Ihren eigenen Verbindungscode schreiben oder die Verbindung über öffentlich zugängliche Tools wie den Cloud SQL Auth-Proxy oder einen sqlcmd-Client herstellen?
  • Möchten Sie die Verschlüsselung über SSL/TLS erzwingen oder unverschlüsselten Traffic zulassen?

In den folgenden Abschnitten werden die Optionen beschrieben, die Cloud SQL zum Verbinden, Autorisieren und Authentifizieren bei Ihrer Datenbank bietet.

  • Verbindungsaufbau: Der Netzwerkpfad, über den Sie Ihre Instanz erreichen:
    • Eine interne, nur über VPC verfügbare (private) IP-Adresse.
    • Eine externe, über das Internet zugängliche (öffentliche) IP-Adresse.
  • Authentifizierung: Definiert, welche Verbindungen autorisiert sind und eine Verbindung zu Ihrer Cloud SQL-Instanz herstellen dürfen.
    • Cloud SQL Auth-Proxy und Cloud SQL-Connector-Bibliotheken für Java und Python: Diese bieten Zugriff anhand von IAM.
    • Selbstverwaltete SSL/TLS-Zertifikate: Diese ermöglichen nur Verbindungen mit bestimmten öffentlichen Schlüsseln.
    • Autorisierte Netzwerke: Eine Liste der IP-Adressen, zu denen eine Verbindung hergestellt werden kann.
  • Authentifizierung: Die Methode, mit der Sie sich in Ihrer Datenbank anmelden.
    • Integrierte Datenbankauthentifizierung: Anmeldung mit einem im Datenbankmodul festgelegten Nutzernamen/Passwort.

Anhand der folgenden Informationen können Sie entscheiden, welche Verbindungs-, Autorisierungs- und Authentifizierungsoptionen für Sie am besten geeignet sind.

Vorbereitung

Wenn Sie den Zugriff auf eine Anwendung gewähren, wird nicht automatisch ein Datenbanknutzerkonto für die Verbindung mit der Instanz aktiviert. Zum Herstellen einer Verbindung mit einer Instanz benötigen Sie für diese Verbindung ein entsprechendes Datenbanknutzerkonto. Für neue Instanzen bedeutet dies, dass das Standardnutzerkonto konfiguriert sein muss. Weitere Informationen finden Sie unter Nutzer mit integrierter Authentifizierung verwalten.

Verbindung mit Cloud SQL herstellen

Datenbankverbindungen nutzen Ressourcen des Servers und der Anwendung, von der die Verbindung ausgeht. Daher sollten Sie sich bei der Verbindungsverwaltung immer an Best Practices orientieren. So können Sie die Kosten für die Anwendung minimieren und die Wahrscheinlichkeit senken, dass die Verbindungslimits für Cloud SQL überschritten werden. Weitere Informationen finden Sie unter Datenbankverbindungen verwalten.

Öffentliche und private IP-Adressen

In Cloud SQL bedeutet öffentliche IP-Adresse, dass die Instanz über das öffentliche Internet zugänglich ist. Instanzen mit privaten Adressen sind aber nicht über das öffentliche Internet zugänglich, sondern nur über eine Virtual Private Cloud (VPC). Cloud SQL-Instanzen können eine öffentliche und eine private IP-Adresse haben.

Private IP-Adresse

Eine private IP-Adresse ist eine IPv4-Adresse, auf die über die Virtual Private Cloud (VPC) zugegriffen werden kann.

Sie können diese Adresse verwenden, um eine Verbindung von anderen Ressourcen mit Zugriff auf die VPC herzustellen. Verbindungen über private IP-Adressen bieten in der Regel eine geringere Latenz und eingeschränkte Angriffsvektoren, da sie keine Übertragung über das Internet erfordern. Optional können Sie festlegen, dass alle Verbindungen entweder den Cloud SQL-Proxy oder selbstverwaltete SSL-Zertifikate verwenden müssen.

Die Konfiguration Ihrer Instanz mit einer privaten IP-Adresse ist zu bevorzugen, wenn eine Verbindung von einem Client zu einer Ressource mit Zugriff auf eine VPC hergestellt wird. Weitere Informationen dazu, welche Ressourcen private IP-Adressen verwenden können, finden Sie unter Anforderungen für private IP-Adressen.

Bei privaten IP-Pfaden stellen die folgenden Dienste und Anwendungen über den serverlosen VPC-Zugriff direkt eine Verbindung zu Ihrer Instanz her:

  • App Engine-Standardumgebung
  • Flexible App Engine-Umgebung
  • Cloud Functions
  • Cloud Run

Mehr über die Verwendung einer privaten IP-Adresse mit Cloud SQL erfahren

Eine Anleitung zum Hinzufügen einer privaten IP-Adresse zu Ihrer Instanz finden Sie unter:

Öffentliche IP-Adresse

Eine öffentliche IP-Adresse ist eine IPv4-Adresse, die extern im öffentlichen Internet verfügbar ist. Über diese Adresse können Verbindungen von Geräten innerhalb und außerhalb des Google-Netzwerks hergestellt werden, auch von Standorten wie Ihrem Zuhause oder Ihrem Büro.

Damit Ihre Instanz besser geschützt ist, müssen alle Verbindungen zu einer Cloud SQL-Instanz über eine öffentliche IP-Adresse entweder über den Cloud SQL-Proxy oder über autorisierte Netzwerke autorisiert werden.

Die Konfiguration Ihrer Instanz mit einer öffentlichen IP-Adresse ist am besten, wenn die Verbindung von einem Client aus erfolgt, der die Anforderungen für eine VPC nicht erfüllt.

Hinweise zum Hinzufügen einer öffentlichen IP-Adresse zu Ihrer Instanz finden Sie unter Öffentliche IP-Verbindungen konfigurieren.

Informationen zum Herstellen einer Verbindung eines sqlcmd-Clients zu einer Cloud SQL-Instanz über öffentliche IP-Adressen finden Sie unter Verbindung über einen Datenbankclient herstellen.

Bei Cloud SQL autorisieren

Cloud SQL Language Connectors

Cloud SQL Language Connectors sind Bibliotheken, die für das Herstellen einer Verbindung zu einer Cloud SQL-Instanz eine Verschlüsselung sowie eine IAM-Autorisierung ermöglichen. Cloud SQL empfiehlt die Verwendung der Cloud SQL Language Connectors, um über andere Verbindungsoptionen eine Verbindung zur Cloud SQL-Instanz herzustellen.

Sie können diese Bibliotheken direkt in ihrer unterstützten Programmiersprache verwenden. Sie bieten die gleiche Authentifizierung wie der Cloud SQL Auth-Proxy, ohne dass ein externer Prozess erforderlich ist. Dies bietet eine höhere Sicherheit und geringere Konfigurationsanforderungen für die Verbindung mit Cloud SQL. Cloud SQL Language Connectors verwenden beim Herstellen einer Verbindung über eine öffentliche IP-Adresse oder eine private IP-Adresse denselben Code.

Eine Einführung finden Sie unter Cloud SQL Language Connectors.

Cloud SQL Auth-Proxy

Mit dem Cloud SQL Auth-Proxy können Sie Ihre Verbindungen mithilfe von IAM-Berechtigungen (Identity and Access Management) autorisieren und sichern. Der Cloud SQL Auth-Proxy validiert Verbindungen mithilfe von Anmeldedaten für einen Nutzer oder ein Dienstkonto und verpackt die Verbindung in einer SSL/TLS-Ebene, die für eine Cloud SQL-Instanz autorisiert ist. Weitere Informationen über die Funktionsweise des Cloud SQL Auth-Proxys finden Sie unter Informationen zum Cloud SQL Auth-Proxy.

Für die Authentifizierung von Verbindungen zu einer Cloud SQL-Instanz wird die Verwendung des Cloud SQL Auth-Proxys empfohlen, da dies die sicherste Methode ist.

Der Cloud SQL Auth-Proxy ist eine Open-Source-Bibliothek, die als ausführbare Binärdatei verteilt wird. Der Cloud SQL Auth-Proxy dient als Zwischenserver, der eingehende Verbindungen beobachtet, diese in SSL/TLS verpackt und dann an eine Cloud SQL-Instanz weiterleitet.

Einige Umgebungen bieten ein Verfahren, mit dem eine Verbindung über den Cloud SQL Auth-Proxy hergestellt werden kann. Eine Anleitung zum Herstellen einer Verbindung mit diesen Umgebungen finden Sie hier:

Selbstverwaltete SSL/TLS-Zertifikate

Anstatt den Cloud SQL Auth-Proxy zum Verschlüsseln Ihrer Verbindungen zu verwenden, können Sie SSL/TLS-Client-Server-Zertifikate einrichten, die speziell auf eine Cloud SQL-Instanz zugeschnitten sind. Diese Zertifikate werden verwendet, um den Client und den Server gegenseitig zu validieren und Verbindungen zwischen ihnen zu verschlüsseln.

Es wird dringend empfohlen, für die Verschlüsselung selbstverwaltete SSL/TLS-Zertifikate zu verwenden, wenn Sie den Cloud SQL Auth-Proxy nicht nutzen. Andernfalls werden Ihre Daten nicht sicher übertragen und können von Dritten abgefangen oder eingesehen werden.

Informationen zum Einstieg in selbstverwaltete SSL/TLS-Zertifikate finden Sie unter Mit SSL/TLS-Zertifikaten autorisieren.

Autorisierte Netzwerke

Sofern nicht der Cloud SQL Auth-Proxy verwendet wird, sind Verbindungen zur öffentlichen IP-Adresse einer Instanz nur zulässig, wenn die Verbindung aus einem autorisierten Netzwerk stammt. Autorisierte Netzwerke sind IP-Adressen oder Bereiche, für die der Nutzer die Verbindungsberechtigung angegeben hat.

Informationen zum Einstieg in autorisierte Netzwerke finden Sie unter Mit autorisierten Netzwerken autorisieren.

Bei Cloud SQL authentifizieren

Die Authentifizierung ermöglicht eine Zugriffssteuerung, indem die Identität eines Nutzers geprüft wird. Für Endnutzer wird die Authentifizierung ausgeführt, wenn sie ihre Anmeldedaten (einen Nutzernamen und ein Passwort) eingeben. Bei Anwendungen erfolgt die Authentifizierung, wenn die Anmeldedaten eines Nutzers einem Dienstkonto zugewiesen werden.

Cloud SQL verwendet die integrierte Authentifizierung der Datenbank, die sich mit einem Nutzernamen und Passwort authentifiziert. Weitere Informationen finden Sie unter SQL Server-Nutzer erstellen und verwalten.

Tools zum Herstellen einer Verbindung zu Cloud SQL

Die folgende Tabelle enthält einige Optionen für die Verbindung zu Cloud SQL:

Verbindungsoption Weitere Informationen
Cloud SQL Auth-Proxy
gcloud CLI
Cloud SQL-Sprachverbindungen
Cloud Shell
Cloud Code
Verbindung mithilfe von Drittanbieter-Datenbankverwaltungstools herstellen
SQL Server Management Studio
SSMS Object Explorer
Visual Studio

Codebeispiele

Sie können eine Verbindung mit dem Cloud SQL Auth-Proxy mit jeder Sprache herstellen, die eine Verbindung zu einem TCP-Socket ermöglicht. Unten finden Sie einige Code-Snippets aus vollständigen Beispielen auf GitHub, damit Sie verstehen, wie sie in Ihrer Anwendung zusammenarbeiten.

Verbindung mit TCP herstellen

Anweisung zum Aufrufen des Cloud SQL Auth-Proxys:

./cloud-sql-proxy INSTANCE_CONNECTION_NAME &

Python

Wenn Sie dieses Snippet im Kontext einer Webanwendung sehen möchten, rufen Sie die README-Datei auf GitHub auf.

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

Wenn Sie dieses Snippet im Kontext einer Webanwendung sehen möchten, rufen Sie die README-Datei auf GitHub auf.

Hinweis:

  • CLOUD_SQL_CONNECTION_NAME sollte als <MY-PROJECT>:<INSTANCE-REGION>:<INSTANCE-NAME> dargestellt werden.
  • Die Verwendung des Arguments ipTypes=PRIVATE erzwingt, dass die SocketFactory eine Verbindung zur zugeordneten privaten IP-Adresse einer Instanz herstellen kann.
  • Die Anforderungen für die JDBC Socket Factory-Version der pom.xml-Datei finden Sie hier. 


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

Wenn Sie dieses Snippet im Kontext einer Webanwendung sehen möchten, rufen Sie die README-Datei auf GitHub auf.

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

Einfach loslegen (Go)

Wenn Sie dieses Snippet im Kontext einer Webanwendung sehen möchten, rufen Sie die README-Datei auf GitHub auf.

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
}

C#

Wenn Sie dieses Snippet im Kontext einer Webanwendung sehen möchten, rufen Sie die README-Datei auf GitHub auf.

using Microsoft.Data.SqlClient;
using System;

namespace CloudSql
{
    public class SqlServerTcp
    {
        public static SqlConnectionStringBuilder NewSqlServerTCPConnectionString()
        {
            // Equivalent connection string:
            // "User Id=<DB_USER>;Password=<DB_PASS>;Server=<INSTANCE_HOST>;Database=<DB_NAME>;"
            var connectionString = new SqlConnectionStringBuilder()
            {
                // 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.
                DataSource = Environment.GetEnvironmentVariable("INSTANCE_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;
            // Specify additional properties here.
            return connectionString;
        }
    }
}

Ruby

Wenn Sie dieses Snippet im Kontext einer Webanwendung sehen möchten, rufen Sie die README-Datei auf GitHub auf.

tcp: &tcp
  adapter: sqlserver
  # 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") { 1433 }%>

PHP

Wenn Sie dieses Snippet im Kontext einer Webanwendung sehen möchten, rufen Sie die README-Datei auf GitHub auf.

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

Fehlerbehebung

Wenn beim Herstellen der Verbindung Probleme auftreten, lesen Sie die folgenden Seiten für das Debugging oder zur Suche nach Lösungen für bekannte Probleme:

Nächste Schritte