Build a Node.js App with CockroachDB and the Node.js pg Driver

This tutorial shows you how build a simple Node.js application with CockroachDB and the Node.js pg driver.

We have tested the Node.js pg driver enough to claim beta-level support. If you encounter problems, please open an issue with details to help us make progress toward full support.

Step 1. Start CockroachDB

Choose whether to run a temporary local cluster or a free CockroachDB cluster on CockroachCloud. The instructions below will adjust accordingly.

Create a free cluster

  1. If you haven't already, sign up for a CockroachCloud account.
  2. Log in to your CockroachCloud account.
  3. On the Clusters page, click Create Cluster.
  4. On the Create your cluster page, select the Free Plan.

    Note:

    This cluster will be free forever.

  5. (Optional) Select a cloud provider (GCP or AWS) in the Additional configuration section.

  6. Click Create your free cluster.

Your cluster will be created in approximately 20-30 seconds.

Set up your cluster connection

Once your cluster is created, the Connect to cluster-name dialog displays. Use the information provided in the dialog to set up your cluster connection for the SQL user that was created by default:

  1. In your terminal, run the second command from the dialog to create a new certs directory on your local machine and download the CA certificate to that directory:

    icon/buttons/copy

    curl --create-dirs -o ~/.postgresql/root.crt -O https://cockroachlabs.cloud/clusters/<cluster-id>/cert
    

    Your cert file will be downloaded to ~/.postgres/root.crt.

    icon/buttons/copy
    curl --create-dirs -o ~/.postgresql/root.crt -O https://cockroachlabs.cloud/clusters/<cluster-id>/cert
    

    Your cert file will be downloaded to ~/.postgres/root.crt.

    icon/buttons/copy
    mkdir -p $env:appdata\.postgresql\; Invoke-WebRequest -Uri https://cockroachlabs.cloud/clusters/<cluster-id>/cert -OutFile $env:appdata\.postgresql\root.crt
    

    Your cert file will be downloaded to %APPDATA%/.postgres/root.crt.

  2. Copy the connection string provided, which will be used in the next steps (and to connect to your cluster in the future).

    Warning:

    This connection string contains your password, which will be provided only once. If you forget your password, you can reset it by going to the SQL Users page.

  1. If you haven't already, download the CockroachDB binary.
  2. Run the cockroach demo command:

    icon/buttons/copy
    $ cockroach demo \
    --no-example-database
    

    This starts a temporary, in-memory cluster and opens an interactive SQL shell to the cluster. Any changes to the database will not persist after the cluster is stopped.

    Note:

    If cockroach demo fails due to SSL authentication, make sure you have cleared any previously downloaded CA certificates from the directory ~/.postgresql.

  3. Take note of the (sql) connection string in the SQL shell welcome text:

    # Connection parameters:
    #   (webui)    http://127.0.0.1:8080/demologin?password=demo76950&username=demo
    #   (sql)      postgres://demo:demo76950@127.0.0.1:26257?sslmode=require
    #   (sql/unix) postgres://demo:demo76950@?host=%2Fvar%2Ffolders%2Fc8%2Fb_q93vjj0ybfz0fz0z8vy9zc0000gp%2FT%2Fdemo070856957&port=26257
    

Step 2. Create a database

  1. In the SQL shell, create the bank database that your application will use:

    icon/buttons/copy
    > CREATE DATABASE bank;
    
  2. Create a SQL user for your app:

    icon/buttons/copy
    > CREATE USER <username> WITH PASSWORD <password>;
    

    Take note of the username and password. You will use it in your application code later.

  3. Give the user the necessary permissions:

    icon/buttons/copy
    > GRANT ALL ON DATABASE bank TO <username>;
    
  1. If you haven't already, download the CockroachDB binary.
  2. Start the built-in SQL shell using the connection string you got from the CockroachCloud Console earlier:

    icon/buttons/copy
    $ cockroach sql \
    --url='postgres://<username>:<password>@<global host>:26257/<cluster_name>.defaultdb?sslmode=verify-full&sslrootcert=<certs_dir>/cc-ca.crt'
    

    In the connection string copied from the CockroachCloud Console, your username, password and cluster name are pre-populated. Replace the <certs_dir> placeholder with the path to the certs directory that you created earlier.

  3. In the SQL shell, create the bank database that your application will use:

    icon/buttons/copy
    > CREATE DATABASE bank;
    

Step 3. Install client driver

To let your application communicate with CockroachDB, install the Node.js pg driver:

icon/buttons/copy
$ npm install pg

Step 4. Get the code

Download the sample code directly, or clone the code's GitHub repository.

Step 5. Update the connection parameters

Open the app.js file, and edit the connection configuration parameters:

  • Replace the value for user with the user you created earlier.
  • Replace the value for password with the password you created for your user.
  • Replace the value for port with the port to your cluster.
  • At the top of the file, uncomment the const fs = require('fs'); line.

    This line imports the fs Node module, which enables you to read in the CA cert that you downloaded from the CockroachCloud Console.

  • Replace the value for user with the user you created earlier.

  • Replace the value for password with the password you created for your user.

  • Replace the value for host with the name of the CockroachCloud Free host (e.g., host: 'free-tier.gcp-us-central1.cockroachlabs.cloud').

  • Replace the value for port with the port to your cluster.

  • Replace the value for database with the database that you created earlier, suffixed with the name of the cluster (e.g., database: '{cluster_name}.bank').

  • Remove the existing ssl object and its contents.

  • Uncomment the ssl object with the ca key-value pair, and edit the fs.readFileSync('/certs/ca.crt').toString() call to use the path to the cc-ca.crt file that you downloaded from the CockroachCloud Console.

Step 6. Run the code

The sample code creates a table, inserts some rows, and then reads and updates values as an atomic transaction.

Here are the contents of app.js:

icon/buttons/copy
//For secure connection:
// const fs = require('fs');
const { Pool } = require("pg");

// Configure the database connection.

const config = {
  user: "max",
  password: "roach",
  host: "localhost",
  database: "bank",
  port: 26257,
  ssl: {
    rejectUnauthorized: false,
  },
  //For secure connection:
  /*ssl: {
        ca: fs.readFileSync('/certs/ca.crt')
            .toString()
    }*/
};

// Create a connection pool

const pool = new Pool(config);

// Wrapper for a transaction.  This automatically re-calls the operation with
// the client as an argument as long as the database server asks for
// the transaction to be retried.

async function retryTxn(n, max, client, operation, callback) {
  await client.query("BEGIN;");
  while (true) {
    n++;
    if (n === max) {
      throw new Error("Max retry count reached.");
    }
    try {
      await operation(client, callback);
      await client.query("COMMIT;");
      return;
    } catch (err) {
      if (err.code !== "40001") {
        return callback(err);
      } else {
        console.log("Transaction failed. Retrying transaction.");
        console.log(err.message);
        await client.query("ROLLBACK;", () => {
          console.log("Rolling back transaction.");
        });
        await new Promise((r) => setTimeout(r, 2 ** n * 1000));
      }
    }
  }
}

// This function is called within the first transaction. It creates a table and inserts some initial values.

async function initTable(client, callback) {
  await client.query(
    "CREATE TABLE IF NOT EXISTS accounts (id INT PRIMARY KEY, balance INT);",
    callback
  );
  await client.query(
    "INSERT INTO accounts (id, balance) VALUES (1, 1000), (2, 250);",
    callback
  );
  await client.query("SELECT id, balance FROM accounts;", callback);
}

async function transferFunds(client, callback) {
  const from = 1;
  const to = 2;
  const amount = 100;
  const selectFromBalanceStatement = "SELECT balance FROM accounts WHERE id = $1 ;";
  const selectFromValues = [from];
  await client.query(selectFromBalanceStatement, selectFromValues, (err, res) => {
    if (err) {
      return callback(err);
    } else if (res.rows.length === 0) {
      console.log("account not found in table");
      return callback(err);
    }
    var acctBal = res.rows[0].balance;
    if (acctBal < amount) {
      return callback(new Error("insufficient funds"));
    }
  });

  const updateFromBalanceStatement = "UPDATE accounts SET balance = balance - $1 WHERE id = $2 ;";
  const updateFromValues = [amount, from];
  await client.query(updateFromBalanceStatement, updateFromValues, callback);

  const updateToBalanceStatement = "UPDATE accounts SET balance = balance + $1 WHERE id = $2 ;";
  const updateToValues = [amount, to];
  await client.query(updateToBalanceStatement, updateToValues, callback);

  const selectBalanceStatement = "SELECT id, balance FROM accounts;";
  await client.query(selectBalanceStatement, callback);
}

// Run the transactions in the connection pool

(async () => {
  // Connect to database
  const client = await pool.connect();

  // Callback
  function cb(err, res) {
    if (err) throw err;

    if (res.rows.length > 0) {
      console.log("New account balances:");
      res.rows.forEach((row) => {
        console.log(row);
      });
    }
  }

  // Initialize table in transaction retry wrapper
  console.log("Initializing table...");
  await retryTxn(0, 15, client, initTable, cb);

  // Transfer funds in transaction retry wrapper
  console.log("Transferring funds...");
  await retryTxn(0, 15, client, transferFunds, cb);

  // Exit program
  process.exit();
})().catch((err) => console.log(err.stack));

Note that all of the database operations are wrapped in the retryTxn function. This function attempts to commit statements in the context of an explicit transaction. If a retry error is thrown, the wrapper will retry committing the transaction, with exponential backoff, until the maximum number of retries is reached (by default, 15).

To run the code:

icon/buttons/copy
$ node app.js

The output should be:

Initializing table...
New account balances:
{ id: '1', balance: '1000' }
{ id: '2', balance: '250' }
Transferring funds...
New account balances:
{ id: '1', balance: '900' }
{ id: '2', balance: '350' }

What's next?

Read more about using the Node.js pg driver.

You might also be interested in the following pages:

YesYes NoNo