Cloud SQL Node.js Connector

The Cloud SQL Node.js Connector is a Cloud SQL connector designed for use with the Node.js runtime. Using a Cloud SQL connector provides a native alternative to the Cloud SQL Auth Proxy while providing the following benefits:

• IAM Authorization: uses IAM permissions to control who/what can connect to your Cloud SQL instances
• Improved Security: uses robust, updated TLS 1.3 encryption and identity verification between the client connector and the server-side proxy, independent of the database protocol.
• Convenience: removes the requirement to use and distribute SSL certificates, as well as manage firewalls or source/destination IP addresses.
• (optionally) IAM DB Authentication: provides support for Cloud SQL’s automatic IAM DB AuthN feature.

The Cloud SQL Node.js Connector is a package to be used alongside a database driver. Currently supported drivers are:

• pg (PostgreSQL)
• mysql2 (MySQL)
• tedious (SQL Server)

Installation

You can install the library using npm install:

1npm install @google-cloud/cloud-sql-connector

APIs and Services

This library requires the following to successfully make Cloud SQL Connections:

• IAM principal (user, service account, etc.) with the Cloud SQL Client role. This IAM principal will be used for credentials.
• The Cloud SQL Admin API to be enabled within your Google Cloud Project. By default, the API will be called in the project associated with the IAM principal.

Credentials

This library uses the Application Default Credentials (ADC) strategy for resolving credentials. Please see these instructions for how to set your ADC (Google Cloud Application vs Local Development, IAM user vs service account credentials), or consult the Node.js google-auth-library.

Usage

The connector package is meant to be used alongside a database driver, in the following examples you can see how to create a new connector and get valid options that can then be used when starting a new connection.

For even more examples, check the examples/ folder.

Using with PostgreSQL

Here is how to start a new pg connection pool.

1import pg from 'pg';
2import {Connector} from '@google-cloud/cloud-sql-connector';
3const {Pool} = pg;
4
5const connector = new Connector();
6const clientOpts = await connector.getOptions({
7  instanceConnectionName: 'my-project:region:my-instance',
8  ipType: 'PUBLIC',
9});
10const pool = new Pool({
11  ...clientOpts,
12  user: 'my-user',
13  password: 'my-password',
14  database: 'db-name',
15  max: 5,
16});
17const {rows} = await pool.query('SELECT NOW()');
18console.table(rows); // prints returned time value from server
19
20await pool.end();
21connector.close();

Using with MySQL

Here is how to start a new mysql2 connection pool.

1import mysql from 'mysql2/promise';
2import {Connector} from '@google-cloud/cloud-sql-connector';
3
4const connector = new Connector();
5const clientOpts = await connector.getOptions({
6  instanceConnectionName: 'my-project:region:my-instance',
7  ipType: 'PUBLIC',
8});
9const pool = await mysql.createPool({
10  ...clientOpts,
11  user: 'my-user',
12  password: 'my-password',
13  database: 'db-name',
14});
15const conn = await pool.getConnection();
16const [result] = await conn.query(`SELECT NOW();`);
17console.table(result); // prints returned time value from server
18
19await pool.end();
20connector.close();

Using with SQL Server

Here is how to start a new tedious connection.

1const {Connection, Request} = require('tedious');
2const {Connector} = require('@google-cloud/cloud-sql-connector');
3
4const connector = new Connector();
5const clientOpts = await connector.getTediousOptions({
6  instanceConnectionName: process.env.SQLSERVER_CONNECTION_NAME,
7  ipType: 'PUBLIC',
8});
9const connection = new Connection({
10  // Please note that the `server` property here is not used and is only defined
11  // due to a bug in the tedious driver (ref: https://github.com/tediousjs/tedious/issues/1541)
12  // With that in mind, do not try to change this value since it will have no
13  // impact in how the connector works, this README will be updated to remove
14  // this property declaration as soon as the tedious driver bug is fixed
15  server: '0.0.0.0',
16  authentication: {
17    type: 'default',
18    options: {
19      userName: 'my-user',
20      password: 'my-password',
21    },
22  },
23  options: {
24    ...clientOpts,
25    // Please note that the `port` property here is not used and is only defined
26    // due to a bug in the tedious driver (ref: https://github.com/tediousjs/tedious/issues/1541)
27    // With that in mind, do not try to change this value since it will have no
28    // impact in how the connector works, this README will be updated to remove
29    // this property declaration as soon as the tedious driver bug is fixed
30    port: 9999,
31    database: 'my-database',
32  },
33});
34
35connection.connect(err => {
36  if (err) {
37    throw err;
38  }
39  let result;
40  const req = new Request('SELECT GETUTCDATE()', err => {
41    if (err) {
42      throw err;
43    }
44  });
45  req.on('error', err => {
46    throw err;
47  });
48  req.on('row', columns => {
49    result = columns;
50  });
51  req.on('requestCompleted', () => {
52    console.table(result);
53  });
54  connection.execSql(req);
55});
56
57connection.close();
58connector.close();

Using a Local Proxy Tunnel (Unix domain socket)

Another possible way to use the Cloud SQL Node.js Connector is by creating a local proxy server that tunnels to the secured connection established using the Connector.startLocalProxy() method instead of Connector.getOptions().

[!NOTE]

The startLocalProxy() method is currently only supported for MySQL and PostgreSQL as it uses a Unix domain socket which SQL Server does not currently support.

This alternative approach enables usage of the Connector library with unsupported drivers such as Prisma. Here is an example on how to use it with its PostgreSQL driver:

1import {Connector} from '@google-cloud/cloud-sql-connector';
2import {PrismaClient} from '@prisma/client';
3
4const connector = new Connector();
5await connector.startLocalProxy({
6  instanceConnectionName: 'my-project:us-east1:my-instance',
7  listenOptions: { path: '.s.PGSQL.5432' },
8});
9const hostPath = process.cwd();
10
11const datasourceUrl =
12 `postgresql://my-user:password@localhost/dbName?host=${hostPath}`;
13const prisma = new PrismaClient({ datasourceUrl });
14
15connector.close();
16await prisma.$disconnect();

For examples on each of the supported Cloud SQL databases consult our Prisma samples.

Specifying IP Address Type

The Cloud SQL Connector for Node.js can be used to connect to Cloud SQL instances using both public and private IP addresses, as well as Private Service Connect (PSC). Specifying which IP address type to connect to can be configured within getOptions through the ipType argument.

By default, connections will be configured to 'PUBLIC' and connect over public IP, to configure connections to use an instance's private IP, use 'PRIVATE' for ipType as follows:

Note: If specifying Private IP or Private Service Connect, your application must be attached to the proper VPC network to connect to your Cloud SQL instance. For most applications this will require the use of a VPC Connector.

Example on how to use a Private IP

1const clientOpts = await connector.getOptions({
2  instanceConnectionName: 'my-project:region:my-instance',
3  ipType: 'PRIVATE',
4});

Example on how to use a Private Service Connect (PSC) IP

1const clientOpts = await connector.getOptions({
2  instanceConnectionName: 'my-project:region:my-instance',
3  ipType: 'PSC',
4});

Example on how to use IpAddressTypes in TypeScript

1import {Connector, IpAddressTypes} from '@google-cloud/cloud-sql-connector';
2const clientOpts = await connector.getOptions({
3  instanceConnectionName: 'my-project:region:my-instance',
4  ipType: IpAddressTypes.PSC,
5});

Automatic IAM Database Authentication

Connections using Automatic IAM database authentication are supported when using Postgres or MySQL drivers.

Make sure to configure your Cloud SQL Instance to allow IAM authentication and add an IAM database user.

A Connector can be configured to connect to a Cloud SQL instance using automatic IAM database authentication with getOptions through the authType argument.

1const clientOpts = await connector.getOptions({
2  instanceConnectionName: 'my-project:region:my-instance',
3  authType: 'IAM',
4});

When configuring a connection for IAM authentication, the password argument can be omitted and the user argument should be formatted as follows:

Postgres: For an IAM user account, this is the user's email address. For a service account, it is the service account's email without the .gserviceaccount.com domain suffix.

MySQL: For an IAM user account, this is the user's email address, without the @ or domain name. For example, for test-user@gmail.com, set the user field to test-user. For a service account, this is the service account's email address without the @project-id.iam.gserviceaccount.com suffix.

Examples using the test-sa@test-project.iam.gserviceaccount.com service account to connect can be found below.

Postgres Automatic IAM Authentication Example

1import pg from 'pg';
2import {Connector} from '@google-cloud/cloud-sql-connector';
3const {Pool} = pg;
4
5const connector = new Connector();
6const clientOpts = await connector.getOptions({
7  instanceConnectionName: 'my-project:region:my-instance',
8  authType: 'IAM',
9});
10const pool = new Pool({
11  ...clientOpts,
12  user: 'test-sa@test-project.iam',
13  database: 'db-name',
14  max: 5,
15});
16const {rows} = await pool.query('SELECT NOW()');
17console.table(rows); // prints returned time value from server
18
19await pool.end();
20connector.close();

MySQL Automatic IAM Authentication Example

1import mysql from 'mysql2/promise';
2import {Connector} from '@google-cloud/cloud-sql-connector';
3
4const connector = new Connector();
5const clientOpts = await connector.getOptions({
6  instanceConnectionName: 'my-project:region:my-instance',
7  authType: 'IAM',
8});
9const pool = await mysql.createPool({
10  ...clientOpts,
11  user: 'test-sa',
12  database: 'db-name',
13});
14const conn = await pool.getConnection();
15const [result] = await conn.query(`SELECT NOW();`);
16console.table(result); // prints returned time value from server
17
18await pool.end();
19connector.close();

Example on how to use AuthTypes in TypeScript

For TypeScript users, the AuthTypes type can be imported and used directly for automatic IAM database authentication.

1import {AuthTypes, Connector} from '@google-cloud/cloud-sql-connector';
2const clientOpts = await connector.getOptions({
3  instanceConnectionName: 'my-project:region:my-instance',
4  authType: AuthTypes.IAM,
5});

Using With Google Auth Library: Node.js Client Credentials

One can use google-auth-library credentials with this library by providing an AuthClient or GoogleAuth instance to the Connector.

1npm install google-auth-library

1import {GoogleAuth} from 'google-auth-library';
2import {Connector} from '@google-cloud/cloud-sql-connector';
3
4const connector = new Connector({
5  auth: new GoogleAuth({
6    scopes: ['https://www.googleapis.com/auth/sqlservice.admin']
7  }),
8});

This can be useful when configuring credentials that differ from Application Default Credentials. See the documentation on the google-auth-library for more information.

Setting a custom quota project

The custom Google Auth Library auth property can also be used to set auth-specific properties such as a custom quota project. Following up from the previous example, here's how you can set a custom quota project using a custom auth credential:

1import {GoogleAuth} from 'google-auth-library';
2import {Connector} from '@google-cloud/cloud-sql-connector';
3
4const connector = new Connector({
5  auth: new GoogleAuth({
6    clientOptions: {
7      quotaProjectId: '<custom quota project>',
8    },
9  }),
10});

Additional customization via Environment Variables

It is possible to change some of the library default behavior via environment variables. Here is a quick reference to supported values and their effect:

• GOOGLE_APPLICATION_CREDENTIALS: If defined the connector will use this file as a custom credential files to authenticate to Cloud SQL APIs. Should be a path to a JSON file. You can find more on how to get a valid credentials file here.
• GOOGLE_CLOUD_QUOTA_PROJECT: Used to set a custom quota project to Cloud SQL APIs when defined.

Using DNS domain names to identify instances

The connector can be configured to use DNS to look up an instance. This would allow you to configure your application to connect to a database instance, and centrally configure which instance in your DNS zone.

Configure your DNS Records

Add a DNS TXT record for the Cloud SQL instance to a private DNS server or a private Google Cloud DNS Zone used by your application.

Note: You are strongly discouraged from adding DNS records for your Cloud SQL instances to a public DNS server. This would allow anyone on the internet to discover the Cloud SQL instance name.

For example: suppose you wanted to use the domain name prod-db.mycompany.example.com to connect to your database instance my-project:region:my-instance. You would create the following DNS record:

• Record type: TXT
• Name: prod-db.mycompany.example.com – This is the domain name used by the application
• Value: my-project:region:my-instance – This is the instance name

Configure the connector

Configure the connector as described above, replacing the connector ID with the DNS name.

Adapting the MySQL + database/sql example above:

1import mysql from 'mysql2/promise';
2import {Connector} from '@google-cloud/cloud-sql-connector';
3
4const connector = new Connector();
5const clientOpts = await connector.getOptions({
6  domainName: 'prod-db.mycompany.example.com',
7  ipType: 'PUBLIC',
8});
9
10const pool = await mysql.createPool({
11  ...clientOpts,
12  user: 'my-user',
13  password: 'my-password',
14  database: 'db-name',
15});
16const conn = await pool.getConnection();
17const [result] = await conn.query(`SELECT NOW();`);
18console.table(result); // prints returned time value from server
19
20await pool.end();
21connector.close();

Automatic failover using DNS domain names

For example: suppose application is configured to connect using the domain name prod-db.mycompany.example.com. Initially the private DNS zone has a TXT record with the value my-project:region:my-instance. The application establishes connections to the my-project:region:my-instance Cloud SQL instance. Configure the connector using the domainName option:

Then, to reconfigure the application to use a different database instance, change the value of the prod-db.mycompany.example.com DNS record from my-project:region:my-instance to my-project:other-region:my-instance-2

The connector inside the application detects the change to this DNS record. Now, when the application connects to its database using the domain name prod-db.mycompany.example.com, it will connect to the my-project:other-region:my-instance-2 Cloud SQL instance.

The connector will automatically close all existing connections to my-project:region:my-instance. This will force the connection pools to establish new connections. Also, it may cause database queries in progress to fail.

The connector will poll for changes to the DNS name every 30 seconds by default. You may configure the frequency of the connections using the Connector's failoverPeriod option. When this is set to 0, the connector will disable polling and only check if the DNS record changed when it is creating a new connection.

Support policy

Major version lifecycle

This project uses semantic versioning, and uses the following lifecycle regarding support for a major version:

Active - Active versions get all new features and security fixes (that wouldn’t otherwise introduce a breaking change). New major versions are guaranteed to be "active" for a minimum of 1 year.

Deprecated - Deprecated versions continue to receive security and critical bug fixes, but do not receive new features. Deprecated versions will be supported for 1 year.

Unsupported - Any major version that has been deprecated for >=1 year is considered unsupported.

Supported Node.js Versions

Our client libraries follow the Node.js release schedule. Libraries are compatible with all current active and maintenance versions of Node.js. If you are using an end-of-life version of Node.js, we recommend that you update as soon as possible to an actively supported LTS version.

Google's client libraries support legacy versions of Node.js runtimes on a best-efforts basis with the following warnings:

• Legacy versions are not tested in continuous integration.
• Some security patches and features cannot be backported.
• Dependencies cannot be kept up-to-date.

Release cadence

This project aims for a release on at least a monthly basis. If no new features or fixes have been added, a new PATCH version with the latest dependencies is released.

Contributing

We welcome outside contributions. Please see our Contributing Guide for details on how best to contribute.

License

Apache Version 2.0

See LICENSE