How to connect to MongoDB

Learn how to access your API node’s MongoDB instance.

Note

This is an advanced feature

The REST Gateway offers a broad range of endpoints so that you don’t have to connect to an API node’s internal database directly.

However, if you are developing new plugins for Symbol, or analyzing extensive blockchain data, you might need to connect directly to MongoDB for debugging purposes.

By the end of this guide, you will be connected to your API node database instance and doing some basic queries.

Prerequisites

Open the database port

In the Running a Symbol node guide you have used symbol-bootstrap to instantiate and run the necessary node services (catapult-client, API endpoints, databases, etc). For security reasons, all these services run inside Docker containers and, except the public endpoints, they are isolated from the exterior.

This means that the MongoDB database that API nodes use to cache the state of the blockchain is inaccessible by default. To forward its internal port to the host you need to give symbol-bootstrap a custom preset file containing the following lines:

 databases:
  - openPort: true

And then use this file when configuring symbol-bootstrap, for example:

 symbol-bootstrap start -p testnet -a dual -c custom_parameters.yml

This will make the database’s TCP port 27017 accessible from the host so be careful, and only use this feature for development purposes.

Install Robo 3T

For this tutorial, we are going to use Robo 3T (formerly RoboMongo), a cross-platform MongoDB management tool, to interact with the database.

  1. Download Robo 3T here.
  2. Open the installer and follow the installation instructions.

In case of doubt, follow the official installation docs.

Create a new connection

  1. Launch Robo 3T and click on the “Create” link to add a new connection.
../../_images/robo3t-open.png
  1. Enter the following details under the “Connection” tab:
../../_images/robo3t-connection.png
  • Type: Direct Connection
  • Name: my-node
  • Address: localhost
  • Port: 27017
  1. If the node is running locally, click “Connect” and move to the next section Querying MongoDB.
  2. Otherwise, if you are running the node in a virtual private server (VPS), create a tunnel first between your computer and the server.

Go to the SSH tab and add the server’s details:

../../_images/robo3t-tunnel.png

Replace the SSH Address, username, and authentication method.

  1. After you click “Connect”, you should see the MongoDB collections under the database named “catapult”.
 

Querying MongoDB

Note

Only use this method to read from the database. Do not alter any document directly on MongoDB.

  1. On the left sidebar, open the collection you want to query.
../../_images/robo3t-collection.png

2. In most cases, you may want to filter a set of entries by one of its attributes. To filter, for example, a given transaction type, write a query with the following format on Robo 3T shell:

 db.getCollection('transactions').find( { "transaction.type": 16724})

For other advanced queries, check the Robo3T docs.

  1. Click on the “Play” button to execute the query.
../../_images/robo3t-query.png
Did you find what you were looking for? Give us your feedback.