Repository files navigation

TheCloud SQL Node.js Connector is a Cloud SQL connector designed for usewith the Node.js runtime. Using a Cloud SQL connector provides a nativealternative to theCloud SQL Auth Proxywhile providing the following benefits:

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

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

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

You can install the library usingnpm install:

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

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

• IAM principal (user, service account, etc.) with theCloud SQL Client role. This IAM principal will be used forcredentials.
• TheCloud SQL Admin API to be enabled within your Google CloudProject. By default, the API will be called in the project associated withthe IAM principal.

This library uses theApplication Default Credentials (ADC) strategy forresolving credentials. Please seethese instructions for how to set your ADC(Google Cloud Application vs Local Development, IAM user vs service account credentials),or consult theNode.js google-auth-library.

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

For even more examples, check theexamples/ folder.

Here is how to start a newpg connection pool.

importpgfrom'pg';import{Connector}from'@google-cloud/cloud-sql-connector';const{Pool}=pg;constconnector=newConnector();constclientOpts=awaitconnector.getOptions({instanceConnectionName:'my-project:region:my-instance',ipType:'PUBLIC',});constpool=newPool({  ...clientOpts,user:'my-user',password:'my-password',database:'db-name',max:5,});const{rows}=awaitpool.query('SELECT NOW()');console.table(rows);// prints returned time value from serverawaitpool.end();connector.close();

Here is how to start a newmysql2 connection pool.

importmysqlfrom'mysql2/promise';import{Connector}from'@google-cloud/cloud-sql-connector';constconnector=newConnector();constclientOpts=awaitconnector.getOptions({instanceConnectionName:'my-project:region:my-instance',ipType:'PUBLIC',});constpool=awaitmysql.createPool({  ...clientOpts,user:'my-user',password:'my-password',database:'db-name',});constconn=awaitpool.getConnection();const[result]=awaitconn.query(`SELECT NOW();`);console.table(result);// prints returned time value from serverawaitpool.end();connector.close();

Here is how to start a newtedious connection.

const{Connection, Request}=require('tedious');const{Connector}=require('@google-cloud/cloud-sql-connector');constconnector=newConnector();constclientOpts=awaitconnector.getTediousOptions({instanceConnectionName:process.env.SQLSERVER_CONNECTION_NAME,ipType:'PUBLIC',});constconnection=newConnection({// 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 fixedserver:'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 fixedport:9999,database:'my-database',},});connection.connect(err=>{if(err){throwerr;}letresult;constreq=newRequest('SELECT GETUTCDATE()',err=>{if(err){throwerr;}});req.on('error',err=>{throwerr;});req.on('row',columns=>{result=columns;});req.on('requestCompleted',()=>{console.table(result);});connection.execSql(req);});connection.close();connector.close();

Another possible way to use the Cloud SQL Node.js Connector is by creating alocal proxy server that tunnels to the secured connection establishedusing theConnector.startLocalProxy() method instead ofConnector.getOptions().

This alternative approach enables usage of the Connector library withunsupported drivers such asPrisma. Here is anexample on how to use it with its PostgreSQL driver:

import{Connector}from'@google-cloud/cloud-sql-connector';import{PrismaClient}from'@prisma/client';constconnector=newConnector();awaitconnector.startLocalProxy({instanceConnectionName:'my-project:us-east1:my-instance',listenOptions:{path:'.s.PGSQL.5432'},});consthostPath=process.cwd();constdatasourceUrl=`postgresql://my-user:password@localhost/dbName?host=${hostPath}`;constprisma=newPrismaClient({ datasourceUrl});connector.close();awaitprisma.$disconnect();

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

The Cloud SQL Connector for Node.js can be used to connect to Cloud SQLinstances using both public and private IP addresses, as well asPrivate Service Connect(PSC). Specifying which IP address type to connect to can be configured withingetOptions through theipType argument.

By default, connections will be configured to'PUBLIC' and connect overpublic IP, to configure connections to use an instance's private IP,use'PRIVATE' foripType as follows:

Note: If specifying Private IP or Private Service Connect, your applicationmust be attached to the proper VPC network to connect to your Cloud SQLinstance. For most applications this will require the use of aVPC Connector.

constclientOpts=awaitconnector.getOptions({instanceConnectionName:'my-project:region:my-instance',ipType:'PRIVATE',});

constclientOpts=awaitconnector.getOptions({instanceConnectionName:'my-project:region:my-instance',ipType:'PSC',});

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

Connections usingAutomatic IAM database authentication are supported whenusing Postgres or MySQL drivers.

Make sure toconfigure your Cloud SQL Instance to allow IAM authenticationandadd an IAM database user.

AConnector can be configured to connect to a Cloud SQL instance usingautomatic IAM database authentication withgetOptions through theauthType argument.

constclientOpts=awaitconnector.getOptions({instanceConnectionName:'my-project:region:my-instance',authType:'IAM',});

When configuring a connection for IAM authentication, thepassword argumentcan be omitted and theuser 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, withoutthe@ or domain name. For example, fortest-user@gmail.com, set theuser field totest-user. For a service account, this is the serviceaccount's email address without the@project-id.iam.gserviceaccount.comsuffix.

Examples using thetest-sa@test-project.iam.gserviceaccount.comservice account to connect can be found below.

importpgfrom'pg';import{Connector}from'@google-cloud/cloud-sql-connector';const{Pool}=pg;constconnector=newConnector();constclientOpts=awaitconnector.getOptions({instanceConnectionName:'my-project:region:my-instance',authType:'IAM',});constpool=newPool({  ...clientOpts,user:'test-sa@test-project.iam',database:'db-name',max:5,});const{rows}=awaitpool.query('SELECT NOW()');console.table(rows);// prints returned time value from serverawaitpool.end();connector.close();

importmysqlfrom'mysql2/promise';import{Connector}from'@google-cloud/cloud-sql-connector';constconnector=newConnector();constclientOpts=awaitconnector.getOptions({instanceConnectionName:'my-project:region:my-instance',authType:'IAM',});constpool=awaitmysql.createPool({  ...clientOpts,user:'test-sa',database:'db-name',});constconn=awaitpool.getConnection();const[result]=awaitconn.query(`SELECT NOW();`);console.table(result);// prints returned time value from serverawaitpool.end();connector.close();

For TypeScript users, theAuthTypes type can be imported and used directlyfor automatic IAM database authentication.

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

One can usegoogle-auth-library credentialswith this library by providing anAuthClient orGoogleAuth instance to theConnector.

npm install google-auth-library

import{GoogleAuth}from'google-auth-library';import{Connector}from'@google-cloud/cloud-sql-connector';constconnector=newConnector({auth:newGoogleAuth({scopes:['https://www.googleapis.com/auth/sqlservice.admin']}),});

This can be useful when configuring credentials that differ fromApplication Default Credentials. See thedocumentationon thegoogle-auth-library for more information.

The customGoogle Auth Libraryauth property can also be used to setauth-specific properties such as a custom quota project. Following up from theprevious example, here's how you can set a custom quota project using a customauth credential:

import{GoogleAuth}from'google-auth-library';import{Connector}from'@google-cloud/cloud-sql-connector';constconnector=newConnector({auth:newGoogleAuth({clientOptions:{quotaProjectId:'<custom quota project>',},}),});

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

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

The connector can be configured to use DNS to look up an instance.Use a DNS name managed by Cloud SQLAdvanced Disaster Recovery,or a domain name that you manage.

Advanced Disaster Recoverycreates geographically distributed replicas of your Cloud SQL database instance. When you performswitchover or failover on the database instance, the connector will gracefully disconnect from theold primary instance and reconnect to the new primary instance.

Follow the instructions inConnect using Write Endpointto get the write endpoint DNS name for your primary instance. Then, use this write endpoint DNSname to configure the connector.

The connector may be configured to use DNS that you define as well.

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

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

For example: suppose you wanted to use the domain nameprod-db.mycompany.example.com to connect to your database instancemy-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 as described above, replacing the connector ID withthe DNS name.

Adapting the MySQL + database/sql example above:

importmysqlfrom'mysql2/promise';import{Connector}from'@google-cloud/cloud-sql-connector';constconnector=newConnector();constclientOpts=awaitconnector.getOptions({domainName:'prod-db.mycompany.example.com',ipType:'PUBLIC',});constpool=awaitmysql.createPool({  ...clientOpts,user:'my-user',password:'my-password',database:'db-name',});constconn=awaitpool.getConnection();const[result]=awaitconn.query(`SELECT NOW();`);console.table(result);// prints returned time value from serverawaitpool.end();connector.close();

For example: suppose application is configured to connect using thedomain nameprod-db.mycompany.example.com. Initially the private DNSzone has a TXT record with the valuemy-project:region:my-instance. Theapplication establishes connections to themy-project:region:my-instanceCloud SQL instance. Configure the connector using thedomainName option:

Then, to reconfigure the application to use a different databaseinstance, change the value of theprod-db.mycompany.example.com DNS recordfrommy-project:region:my-instance tomy-project:other-region:my-instance-2

The connector inside the application detects the change to thisDNS record. Now, when the application connects to its database using thedomain nameprod-db.mycompany.example.com, it will connect to themy-project:other-region:my-instance-2 Cloud SQL instance.

The connector will automatically close all existing connections tomy-project:region:my-instance. This will force the connection pools toestablish new connections. Also, it may cause database queries in progressto 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'sfailoverPeriod option. When this is set to 0, the connector will disablepolling and only check if the DNS record changed when it is creating a newconnection.

This project usessemantic versioning, and uses thefollowing lifecycle regarding support for a major version:

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

Deprecated - Deprecated versions continue to receive security and criticalbug fixes, but do not receive new features. Deprecated versions will besupported for 1 year.

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

Our client libraries follow theNode.js release schedule.Libraries are compatible with all currentactive andmaintenance versionsof Node.js.If you are using an end-of-life version of Node.js, we recommend that youupdate as soon as possible to an actively supported LTS version.

Google's client libraries support legacy versions of Node.js runtimes on abest-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.

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

We welcome outside contributions. Please see ourContributing Guide for details on how best tocontribute.

Apache Version 2.0

SeeLICENSE