Connecting Node.JS web application to RavenDB

What you will learn

• How to connect your web application made with node.js to a RavenDB database
• How to confirm your connection is established

Introduction

Connecting your Node.js web application to RavenDB is a simple process. By the end of this tutorial, we will connect your Node.js app to the RavenDB database and be ready to integrate it into your projects. Whether you’re new to using RavenDB or simply looking for a straightforward setup, this tutorial will smoothly guide you through.

Prerequisites

What you will need:

• Node.js installed on your machine. This article uses 22.10.0.
• RavenDB Cloud Instance & Certificate for secure connection
• Database in RavenDB Cloud

Let’s ensure that we have all the prerequisites to connect your application to the RavenDB. In this tutorial we will use a RavenDB Cloud instance to start the development in no time.

You can also use your local RavenDB server. You can check how to run server locally in this guide https://ravendb.net/docs/article-page/6.2/nodejs/start/getting-started

Let’s setup our development environment. First, you need to download and install Node.js. This tutorial uses Node.js in version 22.10.0. To check if your Node.js installation was successful, and check your version. open terminal and run the following command.

node -v

If you see the Node.js version in your output, it means the installation was successful. If this command doesn’t output your version, download Node.js from the link above.

With your Node.js set up, let’s turn our attention to the RavenDB Cloud. We’ll need a RavenDB Cloud instance and a certificate necessary to encrypt the connection between the database and your application. RavenDB Cloud generates the certificate automatically for your instance. If you’re new to RavenDB Cloud, don’t worry – in this guide, we will also cover how to get started with RavenDB Cloud and how to claim your free instance.

To create your account, start by clicking ‘Get Started Free’(1). If you’d like a free account, simply click ‘Start’(2) without making any changes. Next, select ‘Register Here’. Enter your email address(3) to proceed to the domain name registration step(4). Then, enter the domain name you want, and complete the billing. Review the summary to finish setting up your account. Then you get an activation link on your email address.

We’ve successfully created a RavenDB Cloud account. Now, let’s create a free instance. Instance is like your personal database server. RavenDB Cloud handles setup, maintenance, and other time-consuming tasks to let you focus on the code. To create an instance, click ‘Add Product’ on the right of the ‘Products’ page or just click ‘Add new product to start’ at the center of the page.

If you would like a free instance, don’t change anything – just scroll down and click ‘Next’(1). Enter your account information(2) and then go through billing. Next, you have a ‘Customize’ step(3), where you need to put in the display name of your instance. You also need to set the instance as open to the world (Leave 0.0.0.0/0 if you want it to be open to the world) or delete IP 0.0.0.0/0 and click ‘Add my IP’, to make this only accessible with your IP. You can also change it later so don’t be afraid to delete 0.0.0.0/0. If you want to learn more about CIDR notation, you can read more here. Then, just hit ‘Next’, review the summary and if all looks good, click ‘Create’. For more details on adding a new product, click here.

After configuring your product you will need to wait for the instance to complete the provisioning process before you can access your studio. You will also need a certificate installed.

For a secure connection with RavenDB Studio, let’s get a TLS certificate for your instance. We’ll also use it in our app later. You can download it by going to the ‘Products’ tab on the left bar. Then you select the green button ‘Download Certificate’ on your chosen instance and follow the instructions you get in the pop-up. This pop-up includes a certificate download button and instructions for installing certificates for both Windows and Linux. If you clicked too quickly and got an authentication error, please reload your browser and try again.

Remember to restart your browser after installing the certificate to ensure it recognizes the new certificate.

In order to access RavenDB Studio you require a working certificate. While using RavenDB Cloud, the RavenDB Studio is secured by default – you’ll need a certificate to access the server UI. You’ll also need it to connect to your database within the application code, so this step cannot be skipped. Use your certificate to authorize against RavenDB Studio. Just choose your certificate from the popup window that your browser will display. Once doing so, you should be able to see the UI. Now, let’s create a new database for your application. Select the ‘Databases’ tab and press ‘New database’ to create a new one.

For the purpose of testing, you can also create Sample Data by clicking your database and selecting ‘Tasks’ on the left bar where you can find the option to create it. This data will come in handy later if you want to test the connection between your application and the database.

Setup

We’ve prepared everything you need: a functional Node.js environment for building your app and a RavenDB database running on RavenDB Cloud to manage your application’s data. Let’s try to connect a test web application to our instance. First, we will create a new directory for your application files. Use the terminal in your new directory, and execute this command:

npm init -y

Next, we’ll need the RavenDB Client package to communicate with our database within the code. You have to add it to your project by executing the following command:

npm install --save ravendb

After you added RavenDB, you will need the Express framework. It is a web framework we will use to create a small local web server. To inject it into our project use:

npm install --save express

Now let’s create the main file for your Node.js application, named app.js. Let’s take a look inside. First thing you need to do is importing your Express framework, RavenDB library and fs module. You can do this using this code:

const express = require('express');
const fs = require('fs');
const { DocumentStore } = require('ravendb');

const app = express();

The next step is to use the certificate and route for the Express framework. You can do it using the following code:

app.get('/', (req, res) => {
    const authOptions = {
    certificate: fs.readFileSync("C:\\path_to_your_pfx_file\\cert.pfx"),
    type: "pfx", // or "pem"
};

authOptions lets you specify which database you want to access. You are also using a certificate you get from RavenDB Cloud. If you want to learn more about the security certificate you can check it in the documentation.

Those two allow us to use DocumentStore and x509Certificate. DocumentStore is the base for all RavenDB actions. It communicates with your cluster and can handle multiple databases. It’s important to have a single instance of DocumentStore in place, to maintain a single connection definition to your database. You can learn more about DocumentStore here or here. Spin up your DocumentStore by calling documentStore.initialize() at the bottom to finish off the code.

const store = new DocumentStore("https://your_RavenDB_server_URL" , "your_database_name", authOptions);
store.initialize();

This code below opens a session for you and loads information about the document with ID employees/1-A and fetches it into our routing map endpoint. Let’s check the connection by loading a document from your database in the RavenDB Cloud. We will use DocumentSession to interact with the document. Session is a basic mechanism that is used to modify, load, create, and keep track of documents. If you wish to learn more about Sessions you can read more in the documentation. In the RavenDB Studio choose one of the documents you want to use. For this example, let’s load a single Employee document and write its details in the console. Add the following code at the end of your current one:

const session = store.openSession('your_database_name');
session.load('employees/1-A')
          .then(employee => {
              if (employee) {
                  res.send(`Employee Last Name: ${employee.LastName}`);
              } else {
                  res.status(404).send('Employee not found');
              }
              return session.saveChanges();
          })

          .then(() => {
              store.dispose();
          })
});

app.listen(3000, () => console.log('Server is running on http://localhost:3000'));

After finishing all of the above steps, your application should look like this:

const express = require('express');
const fs = require('fs');
const { DocumentStore } = require('ravendb');
const app = express();

app.get('/', (req, res) => {
      const authOptions = {
      certificate: fs.readFileSync("C:\\path_to_your_pfx_file\\cert.pfx"),
      type: "pfx", // or "pem"
      };

      const store = new DocumentStore("https://your_RavenDB_server_URL", "your_database_name", authOptions);
      store.initialize();

      const session = store.openSession('your_database_name');
      session.load('employees/1-A')
          .then(employee => {
              if (employee) {
                  res.send(`Employee Last Name: ${employee.LastName}`);
              } else {
                  res.status(404).send('Employee not found');
              }
              return session.saveChanges();
          })

          .then(() => {
              store.dispose();
          })
});

app.listen(3000, () => console.log('Server is running on http://localhost:3000'));

Now using the terminal type node app.js and wait a few seconds. This will give you your address you put in app.listen. Copy it into your url browser bar. Once it loads, you should see the output displayed in the top left corner.

As an ending tip, I would like to remind you that if everything is working properly you should delete sample data from your database so it is clean and ready for your data, or just create a new one, dedicated for your app.

Summary

In this tutorial, we explained how to connect your Node.js web applications to the RavenDB database hosted in the RavenDB Cloud. We used Node.js with the RavenDB Client package to connect to our database. We also tested the basic connection using sample data.