Manage database connections

MySQL  |  PostgreSQL  |  SQL Server

This page provides best practices and language-specific code samples to help youcreate applications that use Cloud SQL database connections effectively.

These samples are excerpts from a complete web applicationavailable to you on GitHub.Learn more.

For step-by-step instructions on running a sample webapplication connected to Cloud SQL, follow the linkfor your environment:

Connection pools

A connection pool is a cache of database connections that are shared and reusedto improve connection latency and performance. When your application needs adatabase connection, it borrows one from its pool temporarily; when theapplication is finished with the connection, it returns the connection to thepool, where it can be reused the next time the application needs a databaseconnection.

Connect with TCP

Python

To see this snippet in the context of a web application, viewthe README on GitHub.

importosimportsslimportsqlalchemydefconnect_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. 5432pool=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,),# ...)returnpool

Java

To see this snippet in the context of a web application, viewthe README on GitHub.

Note:

importcom.zaxxer.hikari.HikariConfig;importcom.zaxxer.hikari.HikariDataSource;importjavax.sql.DataSource;publicclassTcpConnectionPoolFactoryextendsConnectionPoolFactory{// 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.privatestaticfinalStringDB_USER=System.getenv("DB_USER");privatestaticfinalStringDB_PASS=System.getenv("DB_PASS");privatestaticfinalStringDB_NAME=System.getenv("DB_NAME");privatestaticfinalStringINSTANCE_HOST=System.getenv("INSTANCE_HOST");privatestaticfinalStringDB_PORT=System.getenv("DB_PORT");publicstaticDataSourcecreateConnectionPool(){// The configuration object specifies behaviors for the connection pool.HikariConfigconfig=newHikariConfig();// 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.returnnewHikariDataSource(config);}}

Node.js

To see this snippet in the context of a web application, viewthe README on GitHub.

constKnex=require('knex');constfs=require('fs');// createTcpPool initializes a TCP connection pool for a Cloud SQL// instance of Postgres.constcreateTcpPool=asyncconfig=>{// 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.constdbConfig={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.returnKnex(dbConfig);};

Go

To see this snippet in the context of a web application, viewthe README on GitHub.

packagecloudsqlimport("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.funcconnectTCPSocket()(*sql.DB,error){mustGetenv:=func(kstring)string{v:=os.Getenv(k)ifv==""{log.Fatalf("Fatal Error in connect_tcp.go: %s environment variable not set.",k)}returnv}// 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)iferr!=nil{returnnil,fmt.Errorf("sql.Open: %w",err)}// ...returndbPool,nil}

C#

To see this snippet in the context of a web application, viewthe README on GitHub.

usingNpgsql;usingSystem;namespaceCloudSql{publicclassPostgreSqlTcp{publicstaticNpgsqlConnectionStringBuilderNewPostgreSqlTCPConnectionString(){// Equivalent connection string:// "Uid=<DB_USER>;Pwd=<DB_PASS>;Host=<INSTANCE_HOST>;Database=<DB_NAME>;"varconnectionString=newNpgsqlConnectionStringBuilder(){// 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 environmentUsername=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.returnconnectionString;}}}

Ruby

To see this snippet in the context of a web application, viewthe README on GitHub.

tcp:&tcpadapter: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 Flexport:<%=ENV.fetch("DB_PORT"){5432}%>

PHP

To see this snippet in the context of a web application, viewthe README on 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;    }}

Connect with Unix sockets

Python

To see this snippet in the context of a web application, viewthe README on GitHub.

importosimportsqlalchemydefconnect_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"},),# ...)returnpool

Java

To see this snippet in the context of a web application, viewthe README on GitHub.

importcom.zaxxer.hikari.HikariConfig;importcom.zaxxer.hikari.HikariDataSource;importjavax.sql.DataSource;publicclassConnectorConnectionPoolFactoryextendsConnectionPoolFactory{// 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.privatestaticfinalStringINSTANCE_CONNECTION_NAME=System.getenv("INSTANCE_CONNECTION_NAME");privatestaticfinalStringINSTANCE_UNIX_SOCKET=System.getenv("INSTANCE_UNIX_SOCKET");privatestaticfinalStringDB_USER=System.getenv("DB_USER");privatestaticfinalStringDB_PASS=System.getenv("DB_PASS");privatestaticfinalStringDB_NAME=System.getenv("DB_NAME");publicstaticDataSourcecreateConnectionPool(){// The configuration object specifies behaviors for the connection pool.HikariConfigconfig=newHikariConfig();// 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);}// cloudSqlRefreshStrategy set to "lazy" is used to perform a// refresh when needed, rather than on a scheduled interval.// This is recommended for serverless environments to// avoid background refreshes from throttling CPU.config.addDataSourceProperty("cloudSqlRefreshStrategy","lazy");// ... Specify additional connection properties here.// ...// Initialize the connection pool using the configuration object.returnnewHikariDataSource(config);}}

Node.js

To see this snippet in the context of a web application, viewthe README on GitHub.

constKnex=require('knex');// createUnixSocketPool initializes a Unix socket connection pool for// a Cloud SQL instance of Postgres.constcreateUnixSocketPool=asyncconfig=>{// 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.returnKnex({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#

To see this snippet in the context of a web application, viewthe README on GitHub.

usingNpgsql;usingSystem;namespaceCloudSql{publicclassPostgreSqlUnix{publicstaticNpgsqlConnectionStringBuilderNewPostgreSqlUnixSocketConnectionString(){// Equivalent connection string:// "Server=<INSTANCE_UNIX_SOCKET>;Uid=<DB_USER>;Pwd=<DB_PASS>;Database=<DB_NAME>"varconnectionString=newNpgsqlConnectionStringBuilder(){// 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-userPassword=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.returnconnectionString;}}}

Go

To see this snippet in the context of a web application, viewthe README on GitHub.

packagecloudsqlimport("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.funcconnectUnixSocket()(*sql.DB,error){mustGetenv:=func(kstring)string{v:=os.Getenv(k)ifv==""{log.Fatalf("Fatal Error in connect_unix.go: %s environment variable not set.\n",k)}returnv}// 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)iferr!=nil{returnnil,fmt.Errorf("sql.Open: %w",err)}// ...returndbPool,nil}

Ruby

To see this snippet in the context of a web application, viewthe README on GitHub.

unix:&unixadapter: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

To see this snippet in the context of a web application, viewthe README on 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;    }}

Open and close connections

When you use a connection pool, you must open and close connections properly,so that your connections are always returned to the pool when you are done withthem. Unreturned or "leaked" connections are not reused, which wastes resourcesand can cause performance bottlenecks for your application.

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)withdb.connect()asconn:conn.execute(stmt,parameters={"time_cast":time_cast,"candidate":team})conn.commit()exceptExceptionase:# 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(Connectionconn=pool.getConnection()){// PreparedStatements can be more efficient and project against injections.Stringstmt="INSERT INTO votes (time_cast, candidate) VALUES (?, ?);";try(PreparedStatementvoteStmt=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(SQLExceptionex){// If something goes wrong, handle the error in this section. This might involve retrying or// adjusting parameters depending on the situation.// ...}

Node.js

/** * Insert a vote record into the database. * * @param {object} pool The Knex connection object. * @param {object} vote The vote record to insert. * @returns {Promise} */constinsertVote=async(pool,vote)=>{try{returnawaitpool('votes').insert(vote);}catch(err){throwError(err);}};

C#

usingNpgsql;usingSystem;namespaceCloudSql{publicclassPostgreSqlTcp{publicstaticNpgsqlConnectionStringBuilderNewPostgreSqlTCPConnectionString(){// Equivalent connection string:// "Uid=<DB_USER>;Pwd=<DB_PASS>;Host=<INSTANCE_HOST>;Database=<DB_NAME>;"varconnectionString=newNpgsqlConnectionStringBuilder(){// 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 environmentUsername=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.returnconnectionString;}}}

Go

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

Ruby

@vote=Vote.newcandidate:candidate# ActiveRecord creates and executes your SQL and automatically# handles the opening and closing of the database connection.if@vote.saverenderjson:"Vote successfully cast for\"#{@vote.candidate}\" at#{@vote.time_cast} PST!"elserenderjson:@vote.errors,status::unprocessable_entityend

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    );}
Note: Most PHP applications are not long-running. They start at the beginning of request processing and shut down when request processing ends. Database connections are closed when the application shuts down.

Connection count

Every database connection uses client and server-side resources. In addition,Cloud SQL imposes overall connection limits that cannot be exceeded.Creating and using fewer connections reduces overhead and helps you stayunder the connection limit.

Python

Java

Node.js

C#

Go

Ruby

PHP

PDO currently doesn't offer any functionality to configure connection limits.

Exponential backoff

If your application attempts to connect to the database and does not succeed,the database could be temporarily unavailable. In this case, sending repeatedconnection requests wastes resources. It is preferable to wait before sendingadditional connection requests in order to allow the database to becomeaccessible again. Using an exponential backoff or other delay mechanism achievesthis goal.

This retry only makes sense when first connecting, or when first grabbing aconnection from the pool. If errors happen in the middle of a transaction, theapplication must do the retrying, and it must retry from the beginning of atransaction. So even if your pool is configured properly, the application mightstill see errors if connections are lost.

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

// 'knex' uses a built-in retry strategy which does not implement backoff.// 'createRetryIntervalMillis' is how long to idle after failed connection creation before trying againconfig.pool.createRetryIntervalMillis=200;// 0.2 seconds

C#

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

Go

Thedatabase/sql package currently doesn't offer any functionality to configure exponential backoff.

Ruby

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

PHP

PDO currently doesn't offer any functionality to configure exponential backoff.

Connection timeout

There are many reasons why a connection attempt might not succeed. Networkcommunication is never guaranteed, and the database might be temporarily unableto respond. Make sure your application handles broken or unsuccessfulconnections gracefully.

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

// 'acquireTimeoutMillis' is the number of milliseconds before a timeout occurs when acquiring a// connection from the pool. This is slightly different from connectionTimeout, because acquiring// a pool connection does not always involve making a new connection, and may include multiple retries.// when making a connectionconfig.pool.acquireTimeoutMillis=60000;// 60 seconds// 'createTimeoutMillis` is the maximum number of milliseconds to wait trying to establish an// initial connection before retrying.// After acquireTimeoutMillis has passed, a timeout exception will be thrown.config.pool.createTimeoutMillis=30000;// 30 seconds// 'idleTimeoutMillis' is the number of milliseconds a connection must sit idle in the pool// and not be checked out before it is automatically closed.config.pool.idleTimeoutMillis=600000;// 10 minutes

C#

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

Go

Thedatabase/sql package currently doesn't offer any functionality to configure connection timeout. Timeout is configured at the driver level.

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,]

Connection duration

Limiting a connection's lifetime can help prevent abandoned connections fromaccumulating. You can use the connection pool to limit your connectionlifetimes.

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

The 'knex' Node.js library currently doesn't offer any functionality tocontrol the duration of a connection.

C#

// ConnectionIdleLifetime sets the time (in seconds) to wait before// closing idle connections in the pool if the count of all// connections exceeds MinPoolSize.connectionString.ConnectionIdleLifetime=300;

Go

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

Ruby

ActiveRecord currently doesn't offer any functionality to control the duration of a connection.

PHP

PDO currently doesn't offer any functionality to control the duration of a connection.

View the complete application

To see the complete application, click the link below.

Python

View thecomplete application for the Python programming language.

Java

View thecomplete application for the Java programming language.

Node.js

View thecomplete application for the Node.js programming language.

C#

View thecomplete application for the C# programming language.

Go

View thecomplete application for the Go programming language.

Ruby

View thecomplete application for the Ruby programming language.

PHP

View thecomplete application for the PHP programming language.

What's next

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-07-16 UTC.