How to get, use, and close a DB connection using promises

How to get, use, and close a DB connection using promises

By June 29, 2017 Uncategorized

The first two patterns we looked at in this series were Node.js callbacks and the Async module. While effective, those patterns are not the only ways of writing asynchronous code. Patterns built around concepts such as “deferreds” and “promises” were first introduced to the JavaScript community via third party libraries like Q and Bluebird. Over time a native implementation of promises was added to ECMAScript, then implemented in V8, and later integrated into Node.js.

Promises are important to learn because many modules use them in their APIs. Also, they are integral to async functions, which I’ll cover in the next part of the series. This post will cover the basics of promises and demonstrate how they can be used to construct asynchronous applications.

Contents:

Promise overview

Native support for promises was added to JavaScript via the Promise object. The Promise object is a constructor function that’s used to create new promise instances. Promise instances have two important properties: state and value. Let’s take a look at how we can manipulate those values and respond to state changes.

resolve and reject

When a new promise is created, the constructor function accepts a “resolver” function that should have two formal parameters: resolve and reject. When the resolver function is executed, which happens immediately when creating new instances, these parameters will be functions that can transition the state of the promise and provide a value. Promises are typically resolved when the resolver completes successfully and rejected if an error occurs.

Here’s an example that shows several promise instances with different states and values:

If you run the above script in either a browser or Node.js, you should see console output similar to the comments. For now, ignore any errors related to uncaught or unhandled promise rejections (more on that later).

Note that this demo script is completely synchronous. Promises usually start out in a pending state and are resolved or rejected asynchronously. Once a promise has been resolved or rejected, its state and value become immutable.

then and catch

To specify what should happen when the state of an instance changes, promises have two methods: then and catch. Both methods accept callback functions that may be invoked asynchronously at some point in the future.

The then method is typically used to specify what should happen when the promise is resolved, though it can accept a second function to handle rejections too. The catch method is explicitly used to handle rejections.

The callback functions passed to then and catch will receive the value passed through the when the resolve or reject functions are invoked in the resolver. The value passed through rejections should always be an instance of Error, though that’s not enforced.

Here’s an example that uses resolve and reject asynchronously. The then and catch methods are used to define what should happen when the promise’s state changes.

Here’s what’s going on in the script:

  • Lines 1-14: A function named getRandomNumber is defined. getRandomNumber returns a new promise instance. The resolver function uses setTimeout to simulate an async call which returns a random number. To demonstrate how error handling works, some random numbers will throw exceptions.
  • Line: 16: The getRandomNumber is invoked and immediately returns a promise in the pending state.
  • Lines 17-19: The then method of the promise is passed a callback that logs a success message with the resolved value.
  • Lines 20-22: The catch method of the promise is passed a callback that logs an error message with the rejected value (Error instance).

If you run the script above several times, you should see success messages and the occasional error message. Did you notice how the catch call flows off the then call? That technique is called promise chaining.

Promise chaining

Calls to then and catch return new promise instances. Of course, these instances also have then and catch methods which allows calls to be chained together as needed. Because these promises are not created with the constructor function, they are not resolved or rejected with a resolver function. Instead, if the function passed into then or catch completes without error, then the promise will be resolved. If the function returns a value, then it will set the promise’s value and be passed to the next then handler in the chain. If an error is thrown and goes unhandled, then the promise will be rejected and the error will be passed to the next error handler in the chain.

If you run the above script with Node.js or in a browser, you should see output like the following (I used Node.js):

As you can see, errors thrown and values returned are routed to the next appropriate handler in the chain. This fact allows us to simulate a try…catch…finally block.

Things get more interesting when the value returned is a promise. When this happens, the next handler in the chain will not be invoked until that promise is resolved or rejected.

Here’s an example:

With a little luck, when you run the script you should see three random values printed to the console every two seconds. If an “error” occurs at any point in the chain, the remaining then functions will be skipped and the error will be passed to the next error handler in the chain. As you can see, promise chaining is a great way to run async operations in series without running into callback hell. But what about more complex flows?

For running operations in parallel, the Promise constructor function has all and race methods. These methods return promises that are resolved or rejected a little differently: all waits for all the promises passed in to be resolved or rejected while race only waits for the first.

Asynchronous iteration of collections, something that’s quite trivial with Async, is not so easy with promises. I’m not showing the technique here because there’s a much simpler way to do this now with async functions – just use a loop!

Error handling

We’ve already covered some of the basics regarding error handling in the section on promise chaining. In this section, I want to explain something that often trips up folks that are new to promises.

Have a look at this example:

Running the script above should give you output like the following:

Note that unhandled errors thrown in functions passed to then and catch are swallowed up and treated like rejections. This means the error will be passed to the next error handler in the chain. But what happens if there are no more error handlers?

The demo script above throws two errors on the main thread. The first error is handled properly by the subsequent catch handler. However, there are no error handlers after the second error is thrown. This resulted in an unhandled rejection and the warnings in the console.

Typically in Node.js, when code throws errors on the main thread outside of a try/catch block, the process is killed. In the case of an unhandled rejection in a promise chain, Node.js emits an unhandledRejection event on the process object. If there’s no handler for that event, then you’ll get the UnhandledPromiseRejectionWarning seen above. According to the DeprecationWarning, unhandled promise rejections will kill the process in the future.

The solution is simple enough: be sure to handle those rejections! 🙂 Check out this excellent post by Valeri Karpov to learn more about unhandled rejections.

Promise demo app

The promise demo app is comprised of the following four files. The files are also available via this Gist.

This is a very basic package.json file. The only external dependency is oracledb.

All of the async methods in node-oracledb are overloaded to work with callback functions or promises. If a callback function is not passed in as the last parameter, then a promise will be returned. This version of the index.js leverages the driver’s promise APIs to create a connection pool and start a promise chain. Although the pool is passed to the then handler for createPool, it’s not referenced here as the built-in pool cache will be used in employees.js.

The db-config.js file is used in index.js to provide the connection info for the database. This configuration should work with the DB App Dev VM, but it will need to be adjusted for other environments.

In this version of the employees module, the getEmployee function was written as a promise-based API – it immediately returns a new promise instance which is asynchronously resolved or rejected. Internally, the function uses the driver’s promise based APIs to get a connection to the database, use it to execute a query, and then close a connection.

The promise chain is written in a way that simulates a try…catch…finally block. The final catch is there just in case there’s an error closing the connection (which would be rare). One could use the unhandledRejection event as an alternative.

I hope this post has helped you to understand how promises work in Node.js. Remember that understanding promises is essential to understanding async functions, which I’ll cover in the next and final part of this series.

6 Comments

  • Thank you for this brilliant series. I detoured from this piece to do a lot of research on promises and when I came back I realized that your explanations are among the best I’ve read.

    I’m an old dog trying to learn new tricks and am totally frustrated. Every JS database example I’ve seen, including yours, show a connection being opened, queried, and closed in a single function. Traditionally, I open a single connection once when my applications are launched, pass that connection object to all my CRUD calls, then close it only when my application is closing. My applications (and the REST API I’m building) do a gazillion CRUD calls so I can’t understand why I would want to create and break down the connection for each and every one (even if pooling makes it efficient).

    Am I crazy? I’m trying to refactor your code to create a connection once and only once, then pass it as a parameter to my queries. I’m getting tied in knots trying to do it the async way. Please forgive me if this sounds more like a rant than a reasonable question. (Perhaps you could just answer the “Am I crazy” part.)

    P.S. I’ve peeked ahead at the async/await article and I still have the same frustration/confusion. I guess I’m looking for a pep talk… 🙂

    • danmcghan says:

      Hi David,

      Thanks!

      > Traditionally, I open a single connection once when my applications are launched, pass that connection object to all my CRUD calls, then close it only when my application is closing.

      I would avoid this, even if just for transaction boundaries. But the pools can do some work for you too, like pinging.

      > My applications (and the REST API I’m building) do a gazillion CRUD calls so I can’t understand why I would want to create and break down the connection for each and every one (even if pooling makes it efficient).

      You shouldn’t do this – it’s redundant for anything except transactional work (and even then you could ship over a short PL/SQL block in one shot). The workaround is to create a wrapper function and call that instead. Here’s an example of one that I use in a certain project:

  • Thanks for the reply, Dan. Sorry I’m unclear what you’re referring to when you say “you shouldn’t do this.”

    But this snippet is pretty close to what I was planning for my next step — create a function that lets me pass in pure SQL and handles the connect/disconnect plumbing. As I said in my original post, I tend to leave my connection open for the duration when it’s only a single object and it services a dedicated user or process. But you make it clear in your comment at the top of your snippet that that’s not the way to go so I’m going to change my thinking.

    Really appreciate the feedback and encouragement.

    • danmcghan says:

      > Sorry I’m unclear what you’re referring to when you say “you shouldn’t do this.”

      Sorry, I was just agreeing with you, albeit unclearly. It’s a lot of work that should be avoided.

  • Teeny-tiny typo, I think: Should the “e” near the end of the employees.js sample (“console.log(‘Error closing connection’, e);”) be “err”instead?

    (I’m still battling Promises but making great progress. Next project is to rewrite your result-set2.js sample in “An Overview of Result Sets in the Node.js Driver” with promises instead of callbacks. After that, an async/await version.)

    Thanks again.

Leave a Reply to David Hoffman Cancel Reply