Connect to Local Datasource

This page describes how to connect a database or API that is hosted locally on the same machine as your Appsmith instance.

• Datasource on localhost: There are two methods:

  • ngrok(Recommended): To connect to a local datasource on a self-hosted or an Appsmith cloud instance, expose the datasource via ngrok. For directions, see ngrok.
  • host.docker.internal: This method is only for self-hosted users for connecting from the Docker container to a datasource on localhost. This is for development purposes and does not work in a production environment outside of Docker Desktop. For directions, see host.docker.internal.

• Datasource in Docker container: This guide is only for self-hosted users for connecting to a datasource in a Docker container. For directions, see Datasource in Docker

Datasource on localhost

ngrok(Recommended)

With ngrok, you can expose your local datasource to the internet and connect from the cloud:

Connect to localhost using ngrok

Set up ngrok: first, you'll need to sign up for an account with ngrok if you don't have one already. Then, follow the setup instructions to install and configure ngrok for the first time. Run ngrok help to make sure it's ready to work.

Once you are ready to work with ngrok, follow these steps to connect Appsmith to your database:

1. Expose your database or API with the ngrok command:

ngrok <protocol> <port>

2. When the command completes, ngrok returns you a set of session details including the Forwarding address.

3. Back in your Appsmith app, create a datasource for the appropriate type of database or API.

4. Enter the URL or Host Address & Port that you just got from ngrok, then configure your remaining datasource details as normal. If you used the http protocol, no port is necessary.

5. Click Test to verify that the connection is valid.

Your localhost application should now be connected and query-able from within your Appsmith app.

Connecting from Appsmith to local PostgreSQL database using ngrok

host.docker.internal

This guide describes how to connect your self-hosted Appsmith instance to your localhost datasource. These steps won't work if you're connecting from the Appsmith Cloud platform.

Connecting from Appsmith in Docker to local datasource

To connect to your database on localhost:

1. Ensure that all of the relevant Docker containers are running. If you are running on Linux, see the note below before starting.

2. In your Appsmith app, create a datasource for the appropriate type of database or API.

3. In the Host Address or URL field where you'd normally provide the URL for your datasource, instead enter host.docker.internal.

4. Click Test to verify that the connection is valid.

Your localhost application should now be connected and query-able from within your Appsmith app.

note

Linux: If your containers are running on a Linux machine, start your Appsmith container with the following command line argument to docker run. This is only supported for Docker 20.10.0 and later.

--add-host=host.docker.internal:host-gateway

Or, for docker-compose, update your docker-compose.yaml file to include the following extra_hosts option:

services: ...
  postgres: ...
    environment: ...
    extra_hosts:
      - "host.docker.internal:host-gateway"

Connecting from Appsmith in Docker container to PostgreSQL database running on localhost

Datasource in Docker container

This guide describes how to connect your APIs and databases to your Appsmith instance when they are each in separate Docker containers.

Set up services

In this guide, you'll use networked Docker containers to spin up a Postgres instance alongside Appsmith and connect to the database from an Appsmith app. These steps won't work if you're connecting from the Appsmith Cloud platform.

1. From the command line, create a Docker network with the following:

   docker network create appsmithnetwork

2. Create two folders, Appsmith and Datasource.

3. Within the Appsmith folder, create a docker-compose.yml file for Appsmith. Assign it to the network from the first step, such as in the bottom of this example file:

   version: "3"
   services:
       appsmith:
           # appsmith-ce for community edition, appsmith-ee for business.
           image: index.docker.io/appsmith/appsmith-ce
           container_name: appsmith
           ports:
               - "80:80"
               - "443:443"
           volumes:
               - ./stacks:/appsmith-stacks
           restart: unless-stopped
           networks:
               - appsmithnetwork
   networks:
   appsmithnetwork:
       external: true

4. Start the Appsmith container with:

   docker-compose up -d

5. Inside the DataSource folder, create docker-compose.yml file and assign it to the same network from before.

6. Start the Datasource container with:

   docker-compose up -d

Connect to the database from Appsmith

Now, you are ready to open your app and connect to your Postgres instance.

1. In Appsmith, create a Postgres datasource.

2. For the Host Address field, enter the name of the Docker container that's running your Postgres instance. For example, this might look something like postgres_postgres_1.

   tip

   If you need to see the names of the containers running on your network, you can use the command:

   docker network inspect <network_name>

3. Fill in the remaining fields for your database and try the Test button. Your database should now be connected.