npmCLI & Toolingupdated 01 Nov 2026

@google-cloud/cloud-sql-connector review

Your SQL driver still needs a route to the database. @google-cloud/cloud-sql-connector 1.12.1 supplies Cloud SQL connection options for Node.js database drivers, with Google IAM authorization and certificate handling. You still use pg, mysql2 or tedious to run SQL and manage database connections. Private IP and PSC require access to the proper VPC. This guide follows the published 1.12.1 contract, which declares Node >=22, and separates connection setup from database login and network routing.

@google-cloud/cloud-sql-connector · v1.12.1 · GoogleCloudPlatform/cloud-sql-nodejs-connector · docs · reviewed by Keyoor

Verdict

Use @google-cloud/cloud-sql-connector when a Node.js service needs application-managed Cloud SQL connections and your network and IAM setup are ready. Before adopting it, prove one connection from the real runtime using the intended IP type and database user.

Answers from our run

@google-cloud/cloud-sql-connector or pg: which should you use?

pg: Use pg directly when your PostgreSQL deployment already has a connection path and authentication setup. It is also a companion driver when you keep the Cloud SQL connector. Use @google-cloud/cloud-sql-connector when a Node.js service needs application-managed Cloud SQL connections and your network and IAM setup are ready.

When should you not use @google-cloud/cloud-sql-connector?

Your database is outside Cloud SQL. Use the database's driver and connection settings instead of this Google-specific helper.

API stability3/5The pinned Connector implementation exposes getOptions, getTediousOptions, startLocalProxy and close, with driver-specific behavior visible in one file. That makes the integration boundary inspectable. The npm package requires Node >=22, and SQL Server takes a separate options path that rejects IAM login. Under the stated rubric, this is a documented API with runtime and driver constraints, not evidence of compatibility across every driver release.

Docs4/5The version-pinned README shows PostgreSQL, MySQL, SQL Server, IAM login, IP selection and a Unix socket route. It also states the VPC prerequisite and explains different IAM username formats for MySQL and PostgreSQL. Those details help diagnose real setup errors. You must still combine the connector instructions with driver lifecycle management and your deployment's network configuration, which keeps the score below the rubric's top anchor.

Maintenance4/5The pinned changelog records 1.12.1 on 8 October 2026 with dependency updates, following 1.12.0 on 2 September with PSC DNS and Global Write Endpoint support, Developer Edition connections and socket cleanup fixes. This is evidence of recent release work across dependencies and connection behavior. It does not establish support response times, resolved vulnerability coverage or a future maintenance commitment.

Ecosystem3/5The pinned README names pg, mysql2 and tedious as supported drivers and documents a Unix socket route for other integrations. That gives Node.js Cloud SQL applications several integration paths. The package remains tied to Google's credentials, instance naming and IAM setup, while pools and SQL belong to the drivers. This score reflects that useful but bounded integration scope, without turning downloads or repository attention into compatibility evidence.

Use it if

Your Node.js service connects to Google Cloud SQL and you want the connection helper inside the application process.
You already use pg or mysql2 and want automatic IAM database authentication after configuring the instance and its IAM database user.
You can grant the runtime's IAM principal Cloud SQL Client access and enable the Cloud SQL Admin API.
You need an explicit choice between public IP, private IP and Private Service Connect when constructing driver options.

Skip it if

Your database is outside Cloud SQL. Use the database's driver and connection settings instead of this Google-specific helper.
Your deployment cannot reach the required VPC for private IP or PSC. Changing ipType does not provide that route.
You need an ORM, query builder or connection pool from this package. Those responsibilities stay with your database tooling.
Your runtime is older than Node 22. The published 1.12.1 package declares Node >=22.
You require automatic IAM database authentication for SQL Server. getTediousOptions rejects IAM authentication.

Setup reality

Start with the deployment, before changing your query code. Version 1.12.1 declares Node >=22 in npm metadata. Install the connector and the driver you actually use. A successful npm install would establish neither Cloud SQL access nor a working database login. We did not install this package or execute database queries for this guide. The snippets are documentation-based illustrations checked against the version-pinned README and connector implementation, not live compatibility tests.

There are separate permission checks. The connector resolves Google credentials through Application Default Credentials, and its IAM principal needs the Cloud SQL Client role. Enable the Cloud SQL Admin API in the relevant project. With ordinary password authentication, the driver still needs its database user, password and database name. With automatic IAM authentication, configure the instance for IAM login and add the IAM database user first. PostgreSQL service-account usernames retain the project.iam portion, while MySQL uses the service account's short name. Copying the username between engines can therefore break login.

The instance connection name has the form project:region:instance. Choose ipType deliberately: PUBLIC is the default, while PRIVATE and PSC need an application attached to the proper VPC. The library does not establish that network attachment. Keep driver-specific configuration beside the connector options so you can diagnose network access, Google authorization and database login separately. SQL Server uses getTediousOptions rather than the ordinary driver-options path, and that method rejects automatic IAM database authentication.

End the driver's pool before calling connector.close(). The implementation closes connector-owned instance resources, proxy servers, sockets and tunnels, but it does not call your driver's pool shutdown method. The Unix socket proxy route can help with drivers that cannot consume the returned stream option. It requires a usable local socket path and is documented for MySQL and PostgreSQL, not SQL Server. The 1.12.1 changelog lists dependency updates. Read the pinned changelog alongside the package metadata when upgrading.

Ratings use a documentation-based five-point rubric: 1 means little usable support for this task, 3 means documented support with material integration work, and 5 means unusually complete evidence with few documented constraints. Intermediate scores sit between those anchors. These are editorial judgments about the retrieved API, documentation, release record and integration scope. They do not measure uptime, security, adoption or performance.

Patterns

Install the connector beside a PostgreSQL driver install-postgres

npm install @google-cloud/cloud-sql-connector@1.12.1 pg

Run on Node 22 or newer. This pins the connector only; resolve and test your driver's version separately.

Use connector options with a PostgreSQL pool postgres-query

import pg from 'pg';
import {Connector} from '@google-cloud/cloud-sql-connector';

const connector = new Connector();
let pool;
try {
  const options = await connector.getOptions({
    instanceConnectionName: 'my-project:region:my-instance',
    ipType: 'PUBLIC',
  });
  pool = new pg.Pool({
    ...options,
    user: process.env.DB_USER,
    password: process.env.DB_PASSWORD,
    database: process.env.DB_NAME,
    max: 5,
  });
  console.log((await pool.query('SELECT NOW()')).rows);
} finally {
  try {
    if (pool) await pool.end();
  } finally {
    connector.close();
  }
}

Documentation-based ESM illustration, not executed. Supply real runtime configuration. The pool runs SQL and ends before connector cleanup.

Configure a MySQL pool mysql-pool

import mysql from 'mysql2/promise';
import {Connector} from '@google-cloud/cloud-sql-connector';

const connector = new Connector();
const options = await connector.getOptions({
  instanceConnectionName: 'my-project:region:my-instance',
  ipType: 'PUBLIC',
});
const pool = mysql.createPool({
  ...options,
  user: process.env.DB_USER,
  password: process.env.DB_PASSWORD,
  database: process.env.DB_NAME,
});

Configuration fragment based on the pinned MySQL example. Keep the pool and connector alive for database work, then await pool.end() before connector.close().

Select private IP explicitly private-ip

const privateOptions = await connector.getOptions({
  instanceConnectionName: 'my-project:region:my-instance',
  ipType: 'PRIVATE',
});

Fragment using an existing Connector. Pass the result into your driver configuration. Your application must already have access to the proper VPC.

Select Private Service Connect psc-ip

const pscOptions = await connector.getOptions({
  instanceConnectionName: 'my-project:region:my-instance',
  ipType: 'PSC',
});

Fragment using an existing Connector. PSC also needs the proper VPC attachment; the option does not create it.

Configure a PostgreSQL IAM database user postgres-iam

import pg from 'pg';
import {Connector} from '@google-cloud/cloud-sql-connector';

const connector = new Connector();
const options = await connector.getOptions({
  instanceConnectionName: 'my-project:region:my-instance',
  authType: 'IAM',
});
const pool = new pg.Pool({
  ...options,
  user: 'test-sa@test-project.iam',
  database: 'db-name',
});

Configuration fragment for test-sa@test-project.iam.gserviceaccount.com. Enable IAM database authentication and create that IAM database user first. Omit the password and drain the pool before connector cleanup.

Configure a MySQL IAM database user mysql-iam

import mysql from 'mysql2/promise';
import {Connector} from '@google-cloud/cloud-sql-connector';

const connector = new Connector();
const options = await connector.getOptions({
  instanceConnectionName: 'my-project:region:my-instance',
  authType: 'IAM',
});
const pool = mysql.createPool({
  ...options,
  user: 'test-sa',
  database: 'db-name',
});

Configuration fragment for the same service account as the PostgreSQL example. MySQL uses the short username. Instance IAM configuration and a matching database user are still prerequisites; end the pool before closing the connector.

Start a PostgreSQL Unix socket proxy unix-socket

import {Connector} from '@google-cloud/cloud-sql-connector';

const connector = new Connector();
await connector.startLocalProxy({
  instanceConnectionName: 'my-project:region:my-instance',
  ipType: 'PUBLIC',
  listenOptions: {path: '.s.PGSQL.5432'},
});
// Configure your PostgreSQL client to use this socket directory.
// After closing that client:
// connector.close();

Proxy startup fragment, not a complete client. The documented PostgreSQL socket filename is .s.PGSQL.5432. Choose a usable directory and stop clients before connector.close(); the Unix socket route excludes SQL Server.

Supply Google credentials explicitly custom-google-auth

import {GoogleAuth} from 'google-auth-library';
import {Connector} from '@google-cloud/cloud-sql-connector';

const connector = new Connector({
  auth: new GoogleAuth({
    scopes: ['https://www.googleapis.com/auth/sqlservice.admin'],
  }),
});

Documentation-based configuration fragment. Install google-auth-library as a direct dependency when importing it. This changes the Google credential configuration, not the database user's permissions. Close the connector after database clients stop.

Alternatives

Package	Registry	Pick it when
pg	npm	Use pg directly when your PostgreSQL deployment already has a connection path and authentication setup. It is also a companion driver when you keep the Cloud SQL connector.
mysql2	npm	Use mysql2 directly when your MySQL deployment already supplies its connection path and authentication. With the Cloud SQL connector, mysql2 remains the driver rather than a replacement for Google IAM authorization.

More cli & tooling guides

commander · chalk · typescript · esbuild · yargs · click · the whole shelf →

How this guide is made: grounded in the library's documentation, release notes, changelog, and issue history, on a fixed rubric — not a hands-on install of every release. The 50 most-downloaded entries are additionally install-verified in clean containers. Corrections: contact the desk.