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:

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

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.

Using with PostgreSQL

Here is how to start a new pg connection pool.

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

const connector = new Connector();
const clientOpts = await connector.getOptions({
  instanceConnectionName: 'my-project:region:my-instance',
  ipType: 'PUBLIC', 
});
const pool = new Pool({
  ...clientOpts,
  user: 'my-user',
  password: 'my-password',
  database: 'db-name',
  max: 5
});
const {rows} = await pool.query('SELECT NOW()');
console.table(rows); // prints returned time value from server

await pool.end();
connector.close();

Using with MySQL

Here is how to start a new mysql2 connection pool.

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

const connector = new Connector();
const clientOpts = await connector.getOptions({
  instanceConnectionName: 'my-project:region:my-instance',
  ipType: 'PUBLIC',
});
const pool = await mysql.createPool({
  ...clientOpts,
  user: 'my-user',
  password: 'my-password',
  database: 'db-name',
});
const conn = await pool.getConnection();
const [result] = await conn.query( `SELECT NOW();`);
console.table(result); // prints returned time value from server

await pool.end();
connector.close();

Using with SQL Server

Here is how to start a new tedious connection.

const {Connection, Request} = require('tedious');
const {Connector} = require('@google-cloud/cloud-sql-connector');

const connector = new Connector();
const clientOpts = await connector.getTediousOptions({
  instanceConnectionName: process.env.SQLSERVER_CONNECTION_NAME,
  ipType: 'PUBLIC'
});
const connection = new Connection({
  // Please note that the `server` property here is not used and is only defined
  // due to a bug in the tedious driver (ref: https://github.com/tediousjs/tedious/issues/1541)
  // With that in mind, do not try to change this value since it will have no
  // impact in how the connector works, this README will be updated to remove
  // this property declaration as soon as the tedious driver bug is fixed
  server: '0.0.0.0',
  authentication: {
    type: 'default',
    options: {
      userName: 'my-user',
      password: 'my-password',
    },
  },
  options: {
    ...clientOpts,
    // Please note that the `port` property here is not used and is only defined
    // due to a bug in the tedious driver (ref: https://github.com/tediousjs/tedious/issues/1541)
    // With that in mind, do not try to change this value since it will have no
    // impact in how the connector works, this README will be updated to remove
    // this property declaration as soon as the tedious driver bug is fixed
    port: 9999,
    database: 'my-database',
  },
})

connection.connect(err => {
  if (err) { throw err; }
  let result;
  const req = new Request('SELECT GETUTCDATE()', (err) => {
    if (err) { throw err; }
  })
  req.on('error', (err) => { throw err; });
  req.on('row', (columns) => { result = columns; });
  req.on('requestCompleted', () => {
    console.table(result);
  });
  connection.execSql(req);
})

connection.close();
connector.close();

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

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

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

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

Example on how to use `IpAddressTypes` in TypeScript

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

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.

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

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

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

const connector = new Connector();
const clientOpts = await connector.getOptions({
  instanceConnectionName: 'my-project:region:my-instance',
  authType: 'IAM'
});
const pool = new Pool({
  ...clientOpts,
  user: 'test-sa@test-project.iam',
  database: 'db-name',
  max: 5
});
const {rows} = await pool.query('SELECT NOW()');
console.table(rows); // prints returned time value from server

await pool.end();
connector.close();

MySQL Automatic IAM Authentication Example

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

const connector = new Connector();
const clientOpts = await connector.getOptions({
  instanceConnectionName: 'my-project:region:my-instance',
  authType: 'IAM'
});
const pool = await mysql.createPool({
  ...clientOpts,
  user: 'test-sa',
  database: 'db-name',
});
const conn = await pool.getConnection();
const [result] = await conn.query( `SELECT NOW();`);
console.table(result); // prints returned time value from server

await pool.end();
connector.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.

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

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.

Versioning

This library follows Semantic Versioning.

This library is considered to be at preview, ready for testing by customers.

More Information: Google Cloud Platform Launch Stages

Contributing

Contributions welcome! See the Contributing Guide.

License

Apache Version 2.0

See LICENSE

edosrecki/cloud-sql-nodejs-connector