Verbindung herstellen

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 oder in einem VPC-Netzwerk (Virtual Private Cloud) privat aufbewahrt wird?
  • 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. Mehr erfahren

Verbindungsoptionen

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.

Private IP-Adresse

Eine private IP-Adresse ist eine IPv4- oder IPv6-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 Private IP-Verbindungen konfigurieren.

Öffentliche IP-Adresse

Eine öffentliche IP-Adresse ist eine IPv4- oder IPv6-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.

Autorisierungsoptionen

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:

Cloud SQL-Connector-Bibliotheken für Java und Python

Cloud SQL bietet Clientbibliotheken, die Verschlüsselung und IAM-basierte Autorisierung für das Herstellen einer Verbindung zu einer Cloud SQL-Instanz mithilfe von Java- und Python-Connectors ermöglichen.

Sie können diese Bibliotheken direkt in der Sprachumgebung verwenden. Sie bieten die gleiche Authentifizierung wie der Cloud SQL Auth-Proxy, ohne dass ein externer Prozess erforderlich ist. Eine Einführung finden Sie unter Verbindungen mithilfe von Cloud SQL-Connectors herstellen.

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.

Authentifizierungsoptionen

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 Verbinden

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

Verbindungsoption Weitere Informationen
Cloud SQL Auth-Proxy
gcloud
Cloud SQL-Sprachverbindungen
Cloud Shell
Verbindung mithilfe von Drittanbieter-Datenbankverwaltungstools herstellen
SQL Server Management Studio
SMSS 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 -instances=INSTANCE_CONNECTION_NAME=tcp:1433 &

Python

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

# 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

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.

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

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

const createPool = async () => {
  const config = {pool: {}, options: {}};
  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

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

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#

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

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

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

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

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

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

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