Running SubQuery Locally

SubQuery TeamAbout 6 min

Running SubQuery Locally

This guide works through how to run a local SubQuery node on your infrastructure, which includes both the indexer and query service. Don't want to worry about running your own SubQuery infrastructure? SubQuery provides a Managed Serviceopen in new window to the community for free. Follow our publishing guide to see how you can upload your project to SubQuery Managed Serviceopen in new window.

There are two ways to run a project locally, using Docker or running the individual components using NodeJS (indexer node service and query service).

Using Docker

An alternative solution is to run a Docker Container, defined by the docker-compose.yml file. For a new project that has been just initialised you won't need to change anything here.

Under the project directory run the following command:

docker-compose pull && docker-compose up


It may take some time to download the required packages (@subql/nodeopen in new window, @subql/queryopen in new window, and Postgres) for the first time but soon you'll see a running SubQuery node.

Running an Indexer (subql/node)


A SubQuery node is an implementation that extracts Substrate/Polkadot-based blockchain data per the SubQuery project and saves it into a Postgres database.

If you are running your project locally using subql-node or subql-node-<network>, make sure you enable the pg_extension btree_gist

You can run the following SQL query:




Please note that we DO NOT encourage the use of yarn global due to its poor dependency management which may lead to an errors down the line.

Once installed, you can start a node with the following command:

Key Commands

The following commands will assist you to complete the configuration of a SubQuery node and begin indexing. To find out more, you can always run --help.

Point to local project path

Connect to database

export DB_USER=postgres
export DB_PASS=postgres
export DB_DATABASE=postgres
export DB_HOST=localhost
export DB_PORT=5432
subql-node -f your-project-path

Depending on the configuration of your Postgres database (e.g. a different database password), please ensure also that both the indexer (subql/node) and the query service (subql/query) can establish a connection to it.

If your database is using SSL, you can use the following command to add the server certificate to it:

subql-node -f your-project-path --pg-ca /path/to/ca.pem

If your database is using SSL and requires a client certificate, you can use the following command to connect to it:

subql-node -f your-project-path --pg-ca /path/to/ca.pem --pg-cert /path/to/client-cert.pem --pg-key /path/to/client-key.key

#### Specify a configuration file

::: code-tabs
@tab Substrate/Polkadot

subql-node -c your-project-config.yml