Datenbankverbindungen verwalten

Diese Seite enthält Best Practices und sprachspezifische Codebeispiele, mit denen Sie Anwendungen erstellen können, die Cloud SQL-Datenbankverbindungen effektiv nutzen.

Die Beispiele sind Auszüge aus einer vollständigen Webanwendung, die Ihnen auf GitHub zur Verfügung steht. Weitere Informationen

Um eine Schritt-für-Schritt-Anleitung zum Ausführen einer mit Cloud SQL verbundenen Beispiel-Webanwendung zu erhalten, klicken Sie auf den Link für Ihre Umgebung:

Verbindungspools

Ein Verbindungspool ist ein Cache von Datenbankverbindungen, die zur Verbesserung der Verbindungslatenz und -leistung gemeinsam genutzt und wiederverwendet werden. Wenn eine Anwendung eine Datenbankverbindung benötigt, leiht sie sich vorübergehend eine aus dem Pool aus. Sobald die Anwendung die Verbindung nicht mehr benötigt, gibt sie sie an den Pool zurück. Dort steht sie zur erneuten Verwendung zur Verfügung.

Verbindungen öffnen und schließen

Wenn Sie einen Verbindungspool verwenden, müssen Sie die Verbindungen ordnungsgemäß öffnen und schließen, damit sie immer wieder an den Pool zurückgegeben werden, sobald Sie sie nicht mehr brauchen. Nicht zurückgegebene oder "verlorene" Verbindungen werden nicht wiederverwendet, was Ressourcen verschwendet und zu Leistungsengpässen für Ihre Anwendung führen kann.

Python

# Preparing a statement before hand can help protect against injections.
stmt = sqlalchemy.text(
    "INSERT INTO votes (time_cast, candidate) VALUES (:time_cast, :candidate)"
)
try:
    # Using a with statement ensures that the connection is always released
    # back into the pool at the end of statement (even if an error occurs)
    with db.connect() as conn:
        conn.execute(stmt, parameters={"time_cast": time_cast, "candidate": team})
        conn.commit()
except Exception as e:
    # If something goes wrong, handle the error in this section. This might
    # involve retrying or adjusting parameters depending on the situation.
    # ...

Java

// Using a try-with-resources statement ensures that the connection is always released back
// into the pool at the end of the statement (even if an error occurs)
try (Connection conn = pool.getConnection()) {

  // PreparedStatements can be more efficient and project against injections.
  String stmt = "INSERT INTO votes (time_cast, candidate) VALUES (?, ?);";
  try (PreparedStatement voteStmt = conn.prepareStatement(stmt);) {
    voteStmt.setTimestamp(1, now);
    voteStmt.setString(2, team);

    // Finally, execute the statement. If it fails, an error will be thrown.
    voteStmt.execute();
  }
} catch (SQLException ex) {
  // If something goes wrong, handle the error in this section. This might involve retrying or
  // adjusting parameters depending on the situation.
  // ...
}

Node.js

try {
  const stmt = 'INSERT INTO votes (time_cast, candidate) VALUES (?, ?)';
  // Pool.query automatically checks out, uses, and releases a connection
  // back into the pool, ensuring it is always returned successfully.
  await pool.query(stmt, [timestamp, team]);
} catch (err) {
  // If something goes wrong, handle the error in this section. This might
  // involve retrying or adjusting parameters depending on the situation.
  // ...
}

C#

using MySql.Data.MySqlClient;
using System;

namespace CloudSql
{
    public class MySqlTcp
    {
        public static MySqlConnectionStringBuilder NewMysqlTCPConnectionString()
        {
            // Equivalent connection string:
            // "Uid=<DB_USER>;Pwd=<DB_PASS>;Host=<INSTANCE_HOST>;Database=<DB_NAME>;"
            var connectionString = new MySqlConnectionStringBuilder()
            {
                // 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.
                Server = 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'
                Database = Environment.GetEnvironmentVariable("DB_NAME"), // e.g. 'my-database'

                // The Cloud SQL proxy provides encryption between the proxy and instance.
                SslMode = MySqlSslMode.Disabled,
            };
            connectionString.Pooling = true;
            // Specify additional properties here.
            return connectionString;

        }
    }
}

Go

insertVote := "INSERT INTO votes(candidate, created_at) VALUES(?, NOW())"
_, err := db.Exec(insertVote, team)

Ruby

@vote = Vote.new candidate: candidate

# ActiveRecord creates and executes your SQL and automatically
# handles the opening and closing of the database connection.
if @vote.save
  render json: "Vote successfully cast for \"#{@vote.candidate}\" at #{@vote.time_cast} PST!"
else
  render json: @vote.errors, status: :unprocessable_entity
end

PHP

// Use prepared statements to guard against SQL injection.
$sql = 'INSERT INTO votes (time_cast, candidate) VALUES (NOW(), :voteValue)';

try {
    $statement = $conn->prepare($sql);
    $statement->bindParam('voteValue', $value);

    $res = $statement->execute();
} catch (PDOException $e) {
    throw new RuntimeException(
        'Could not insert vote into database. The PDO exception was ' .
        $e->getMessage(),
        $e->getCode(),
        $e
    );
}

Verbindungsanzahl

Jede Datenbankverbindung nutzt client- und serverseitige Ressourcen. Darüber hinaus sind in Cloud SQL Verbindungslimits festgelegt, die nicht überschritten werden können. Das Erstellen und Verwenden von weniger Verbindungen verringert den Aufwand und hilft Ihnen, das Verbindungslimit einzuhalten.

Python

# Pool size is the maximum number of permanent connections to keep.
pool_size=5,
# Temporarily exceeds the set pool_size if no connections are available.
max_overflow=2,
# The total number of concurrent connections for your application will be
# a total of pool_size and max_overflow.

Java

// maximumPoolSize limits the total number of concurrent connections this pool will keep. Ideal
// values for this setting are highly variable on app design, infrastructure, and database.
config.setMaximumPoolSize(5);
// minimumIdle is the minimum number of idle connections Hikari maintains in the pool.
// Additional connections will be established to meet this value unless the pool is full.
config.setMinimumIdle(5);

Node.js

// 'connectionLimit' is the maximum number of connections the pool is allowed
// to keep at once.
connectionLimit: 5,

C#

// MaximumPoolSize sets maximum number of connections allowed in the pool.
connectionString.MaximumPoolSize = 5;
// MinimumPoolSize sets the minimum number of connections in the pool.
connectionString.MinimumPoolSize = 0;

Go

// Set maximum number of connections in idle connection pool.
db.SetMaxIdleConns(5)

// Set maximum number of open connections to the database.
db.SetMaxOpenConns(7)

Ruby

# 'pool' is the maximum number of permanent connections to keep.
pool: 5

PHP

PDO bietet derzeit keine Funktion zum Konfigurieren von Verbindungslimits.

Exponentielle Backoffs

Wenn Ihre Anwendung erfolglos versucht, eine Verbindung zur Datenbank herzustellen, ist die Datenbank möglicherweise vorübergehend nicht verfügbar. In diesem Fall verschwendet das Senden wiederholter Verbindungsanfragen Ressourcen. Es ist besser, vor dem Senden zusätzlicher Verbindungsanfragen zu warten, damit die Datenbank wieder zugänglich ist. Mit einem exponentiellen Backoff oder einem anderen Verzögerungsmechanismus wird dieses Ziel erreicht.

Dieser Wiederholungsversuch ist nur bei der ersten Verbindung oder beim ersten Zugriff auf eine Verbindung aus dem Pool sinnvoll. Wenn während einer Transaktion Fehler auftreten, muss die Anwendung den Wiederholungsversuch ausführen und dabei die Transaktion von vorn starten. Selbst wenn der Pool ordnungsgemäß konfiguriert ist, können bei Verbindungsunterbrechungen in der Anwendung Fehler auftreten.

Python

# SQLAlchemy automatically uses delays between failed connection attempts,
# but provides no arguments for configuration.

Java

// Hikari automatically delays between failed connection attempts, eventually reaching a
// maximum delay of `connectionTimeout / 2` between attempts.

Node.js

// The mysql module automatically uses exponential delays between failed
// connection attempts.

C#

Policy
    .Handle<MySqlException>()
    .WaitAndRetry(new[]
    {
        TimeSpan.FromSeconds(1),
        TimeSpan.FromSeconds(2),
        TimeSpan.FromSeconds(5)
    })
    .Execute(() => connection.Open());

Go

Das Paket database/sql bietet derzeit keine Funktion zum Konfigurieren von exponentiellen Backoffs.

Ruby

# ActiveRecord automatically uses delays between failed connection attempts,
# but provides no arguments for configuration.

PHP

PDO bietet derzeit keine Funktion zum Konfigurieren von exponentiellen Backoffs.

Zeitüberschreitung der Verbindung

Es gibt viele Gründe, warum ein Verbindungsversuch fehlschlagen kann. Die Netzwerkkommunikation kann niemals garantiert werden und die Datenbank reagiert möglicherweise vorübergehend nicht. Achten Sie darauf, dass Ihre Anwendung unterbrochene oder fehlgeschlagene Verbindungen ordnungsgemäß verarbeitet.

Python

# 'pool_timeout' is the maximum number of seconds to wait when retrieving a
# new connection from the pool. After the specified amount of time, an
# exception will be thrown.
pool_timeout=30,  # 30 seconds

Java

// setConnectionTimeout is the maximum number of milliseconds to wait for a connection checkout.
// Any attempt to retrieve a connection from this pool that exceeds the set limit will throw an
// SQLException.
config.setConnectionTimeout(10000); // 10 seconds
// idleTimeout is the maximum amount of time a connection can sit in the pool. Connections that
// sit idle for this many milliseconds are retried if minimumIdle is exceeded.
config.setIdleTimeout(600000); // 10 minutes

Node.js

// 'connectTimeout' is the maximum number of milliseconds before a timeout
// occurs during the initial connection to the database.
connectTimeout: 10000, // 10 seconds
// 'acquireTimeout' is the maximum number of milliseconds to wait when
// checking out a connection from the pool before a timeout error occurs.
acquireTimeout: 10000, // 10 seconds
// 'waitForConnections' determines the pool's action when no connections are
// free. If true, the request will queued and a connection will be presented
// when ready. If false, the pool will call back with an error.
waitForConnections: true, // Default: true
// 'queueLimit' is the maximum number of requests for connections the pool
// will queue at once before returning an error. If 0, there is no limit.
queueLimit: 0, // Default: 0

C#

// ConnectionTimeout sets the time to wait (in seconds) while
// trying to establish a connection before terminating the attempt.
connectionString.ConnectionTimeout = 15;

Go

Das Paket database/sql bietet derzeit keine Funktion zum Konfigurieren von Zeitlimits für Verbindungen. Zeitlimits werden auf Treiberebene konfiguriert.

Ruby

# 'timeout' is the maximum number of seconds to wait when retrieving a
# new connection from the pool. After the specified amount of time, an
# ActiveRecord::ConnectionTimeoutError will be raised.
timeout: 5000

PHP

// Here we set the connection timeout to five seconds and ask PDO to
// throw an exception if any errors occur.
[
    PDO::ATTR_TIMEOUT => 5,
    PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
]

Verbindung beenden

Nutzer mit der Berechtigung PROCESS in Cloud SQL können Verbindungen auflisten, die sie nicht verwalten. In MySQL 5.7.x müssen Nutzer die Berechtigung SUPER und in MySQL 8.0.x die Berechtigung CONNECTION_ADMIN haben, um eine KILL-Anweisung für diese Verbindungen auszuführen. Die Anweisung KILL beendet die Verbindung eines anderen MySQL-Nutzers (außer Cloud SQL-Administratornutzer). Nutzer ohne diese Berechtigungen können nur Verbindungen auflisten und beenden, die sie verwalten.

Sie können die Verbindungen zu einer Instanz mit dem MySQL-Client und dem Befehl SHOW PROCESSLIST auflisten. Verwenden Sie Id, um die Verbindung zu beenden. Beispiel:

mysql> SHOW PROCESSLIST;
mysql> KILL 6;

Verbindungsdauer

Durch die Begrenzung der Verbindungsdauer kann verhindert werden, dass sich abgebrochene Verbindungen ansammeln. Die Verbindungsdauer können Sie über den Verbindungspool begrenzen.

Python

# 'pool_recycle' is the maximum number of seconds a connection can persist.
# Connections that live longer than the specified amount of time will be
# re-established
pool_recycle=1800,  # 30 minutes

Java

// maxLifetime is the maximum possible lifetime of a connection in the pool. Connections that
// live longer than this many milliseconds will be closed and reestablished between uses. This
// value should be several minutes shorter than the database's timeout value to avoid unexpected
// terminations.
config.setMaxLifetime(1800000); // 30 minutes

Node.js

Die Node.js-Bibliothek mysql bietet derzeit keine Funktion zum Steuern der Verbindungsdauer.

C#

// ConnectionLifeTime sets the lifetime of a pooled connection
// (in seconds) that a connection lives before it is destroyed
// and recreated. Connections that are returned to the pool are
// destroyed if it's been more than the number of seconds
// specified by ConnectionLifeTime since the connection was
// created. The default value is zero (0) which means the
// connection always returns to pool.
connectionString.ConnectionLifeTime = 1800; // 30 minutes

Go

// Set Maximum time (in seconds) that a connection can remain open.
db.SetConnMaxLifetime(1800 * time.Second)

Ruby

ActiveRecord bietet derzeit keine Funktion zum Steuern der Verbindungsdauer.

PHP

PDO bietet derzeit keine Funktion zum Steuern der Verbindungsdauer.

Klicken Sie unten auf den jeweiligen Link, um sich die vollständige Anwendung anzusehen.

Python

Sehen Sie sich die vollständige Anwendung für die Programmiersprache Python an.

Java

Sehen Sie sich die vollständige Anwendung für die Programmiersprache Java an.

Node.js

Sehen Sie sich die vollständige Anwendung für die Programmiersprache Node.js an.

C#

Sehen Sie sich die vollständige Anwendung für die Programmiersprache C# an.

Go

Sehen Sie sich die vollständige Anwendung für die Programmiersprache Go an.

Ruby

Sehen Sie sich die vollständige Anwendung für die Programmiersprache Ruby an.

PHP

Sehen Sie sich die vollständige Anwendung für die Programmiersprache PHP an.

Nächste Schritte