Security News
Research
Data Theft Repackaged: A Case Study in Malicious Wrapper Packages on npm
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
@google-cloud/cloud-sql-connector
Advanced tools
A JavaScript library for connecting securely to your Cloud SQL instances
@google-cloud/cloud-sql-connector is an npm package that simplifies the process of connecting to Google Cloud SQL instances from Node.js applications. It provides secure and efficient connection management, handling the complexities of authentication and connection pooling.
Connecting to a Cloud SQL instance
This feature allows you to connect to a Google Cloud SQL instance using the Cloud SQL Connector. It handles the authentication and connection details, providing a seamless way to connect to your database.
const { CloudSQLConnector } = require('@google-cloud/cloud-sql-connector');
const mysql = require('mysql2/promise');
async function connectToCloudSQL() {
const connector = new CloudSQLConnector();
const clientOpts = await connector.getOptions({
instanceConnectionName: 'project:region:instance',
user: 'my-user',
password: 'my-password',
database: 'my-database'
});
const connection = await mysql.createConnection(clientOpts);
console.log('Connected to Cloud SQL');
return connection;
}
connectToCloudSQL().catch(console.error);
Connection Pooling
This feature demonstrates how to create a connection pool using the Cloud SQL Connector. Connection pooling helps manage multiple database connections efficiently, improving performance and resource utilization.
const { CloudSQLConnector } = require('@google-cloud/cloud-sql-connector');
const mysql = require('mysql2/promise');
const { createPool } = require('mysql2/promise');
async function createConnectionPool() {
const connector = new CloudSQLConnector();
const clientOpts = await connector.getOptions({
instanceConnectionName: 'project:region:instance',
user: 'my-user',
password: 'my-password',
database: 'my-database'
});
const pool = createPool({
...clientOpts,
connectionLimit: 10
});
console.log('Connection pool created');
return pool;
}
createConnectionPool().catch(console.error);
mysql2 is a popular MySQL client for Node.js that supports both callbacks and promises. While it provides robust functionality for connecting to MySQL databases, it does not offer built-in support for Google Cloud SQL's specific authentication and connection management features like @google-cloud/cloud-sql-connector.
pg is a PostgreSQL client for Node.js. It offers a wide range of features for connecting to and interacting with PostgreSQL databases. Similar to mysql2, it does not include specific support for Google Cloud SQL's authentication and connection management, which @google-cloud/cloud-sql-connector provides.
knex is a SQL query builder for Node.js that supports multiple database types, including MySQL and PostgreSQL. It provides a flexible and powerful way to build and execute SQL queries. However, it lacks the specialized connection management and authentication features for Google Cloud SQL that @google-cloud/cloud-sql-connector offers.
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:
The Cloud SQL Node.js Connector is a package to be used alongside a database driver. Currently supported drivers are:
You can install the library using npm install
:
npm install @google-cloud/cloud-sql-connector
This library requires the following to successfully make Cloud SQL Connections:
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.
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.
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();
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();
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();
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:
import {Connector} from '@google-cloud/cloud-sql-connector';
import {PrismaClient} from '@prisma/client';
const connector = new Connector();
await connector.startLocalProxy({
instanceConnectionName: 'my-project:us-east1:my-instance',
listenOptions: { path: '.s.PGSQL.5432' },
});
const hostPath = process.cwd();
const datasourceUrl =
`postgresql://my-user:password@localhost/dbName?host=${hostPath}`;
const prisma = new PrismaClient({ datasourceUrl });
connector.close();
await prisma.$disconnect();
For examples on each of the supported Cloud SQL databases consult our Prisma samples.
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.
const clientOpts = await connector.getOptions({
instanceConnectionName: 'my-project:region:my-instance',
ipType: 'PRIVATE',
});
const clientOpts = await connector.getOptions({
instanceConnectionName: 'my-project:region:my-instance',
ipType: 'PSC',
});
IpAddressTypes
in TypeScriptimport {Connector, IpAddressTypes} from '@google-cloud/cloud-sql-connector';
const clientOpts = await connector.getOptions({
instanceConnectionName: 'my-project:region:my-instance',
ipType: IpAddressTypes.PSC,
});
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, fortest-user@gmail.com
, set theuser
field totest-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.
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();
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();
AuthTypes
in TypeScriptFor 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,
});
Google Auth Library: Node.js Client
CredentialsOne can use google-auth-library
credentials
with this library by providing an AuthClient
or GoogleAuth
instance to the Connector
.
npm install google-auth-library
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']
}),
});
This can be useful when configuring credentials that differ from
Application Default Credentials. See the documentation
on the google-auth-library
for more information.
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:
import {GoogleAuth} from 'google-auth-library';
import {Connector} from '@google-cloud/cloud-sql-connector';
const connector = new Connector({
auth: new GoogleAuth({
clientOptions: {
quotaProjectId: '<custom quota project>',
},
}),
});
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.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.
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:
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.
We welcome outside contributions. Please see our Contributing Guide for details on how best to contribute.
Apache Version 2.0
See LICENSE
FAQs
A JavaScript library for connecting securely to your Cloud SQL instances
The npm package @google-cloud/cloud-sql-connector receives a total of 230,183 weekly downloads. As such, @google-cloud/cloud-sql-connector popularity was classified as popular.
We found that @google-cloud/cloud-sql-connector demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.
Security News
The Ultralytics' PyPI Package was compromised four times in one weekend through GitHub Actions cache poisoning and failure to rotate previously compromised API tokens.