Configure an external PostgreSQL database

Robility flow’s default database is SQLite, but you can configure Robility flow to use PostgreSQL instead.

This guide walks you through setting up an external database for Robility flow by replacing the default SQLite connection string sqlite:///./Robility flow.db with PostgreSQL, both in local and containerized environments.

In this configuration, all structured application data from Robility flow, including flows, message history, and logs, is instead managed by PostgreSQL. PostgreSQL is better suited for production environments due to its robust support for concurrent users, advanced data integrity features, and scalability. Robility flow can more efficiently handle multiple users and larger workloads by using PostgreSQL as the database.

Prerequisites

A PostgreSQL database

Connect Robility flow to a local PostgreSQL database

1. If Robility flow is running, stop Robility flow with Ctrl+C.
2. Find your PostgreSQL database’s connection string in the format postgresql://user:password@host:port/dbname.

The hostname in your connection string depends on how you’re running PostgreSQL:

a. If you’re running PostgreSQL directly on your machine, use localhost.
b. If you’re running PostgreSQL in Docker Compose, use the service name, such as postgres.
c. If you’re running PostgreSQL in a separate Docker container with docker run, use the container’s IP address or network alias.
d. If you’re running a cloud-hosted PostgreSQL, your provider will share your connection string, which includes a username and password.

3. Create a Robility flow .env file:

touch .env

4. In your .env file, set ROBILITY FLOW_DATABASE_URL to your PostgreSQL connection string:

ROBILITY FLOW_DATABASE_URL=”postgresql://user:password@localhost:5432/dbname”

5. Save your changes and then start Robility flow with your .env file:

uv run Robility flow run –env-file .env

6. In Robility flow, run any flow to create traffic.

7. Inspect your PostgreSQL database’s tables and activity to verify that new tables and traffic were created after you ran a flow.

Deploy Robility flow and PostgreSQL containers with docker-compose.yml

Launching Robility flow and PostgreSQL containers in the same Docker network ensures proper connectivity between services.

The configuration in the example docker-compose.yml also sets up persistent volumes for both Robility flow and PostgreSQL data. Persistent volumes map directories inside of containers to storage on the host machine, so data persists through container restarts.

Docker Compose creates an isolated network for all services defined in docker-compose.yml. This ensures that the services can communicate with each other using their service names as hostnames, such as postgres in the database URL. In contrast, if you run PostgreSQL separately with docker run, it launches in a different network than the Robility flow container, and this prevents Robility flow from connecting to PostgreSQL using the service name.

To start the Robility flow and PostgreSQL services with the example Docker Compose file, navigate to the Robility flow/docker_example directory, and then run docker-compose up. If you’re using a different docker-compose.yml file, run the docker-compose up command from the same directory as your docker-compose.yml file.

Deploy multiple Robility flow instances with a shared PostgreSQL database

To configure multiple Robility flow instances that share the same PostgreSQL database, modify your docker-compose.yml file to include multiple Robility flow services.

This example populates the values in docker-compose.yml with values from your Robility flow .env file. This approach means you only have to manage deployment variables in one file, instead of copying values across multiple files.

1. Update your .env file with values for your PostgreSQL database:

POSTGRES_USER=Robility flow

POSTGRES_PASSWORD=your_secure_password

POSTGRES_DB=Robility flow

POSTGRES_HOST=postgres

POSTGRES_PORT=5432

ROBILITY FLOW_CONFIG_DIR=app/Robility flow

ROBILITY FLOW_PORT_1=7860

ROBILITY FLOW_PORT_2=7861

ROBILITY FLOW_HOST=0.0.0.0

2. Reference these variables in your docker-compose.yml. For example:

services:

  postgres:

    image: postgres:16

    environment:

      – POSTGRES_USER=${POSTGRES_USER}

      – POSTGRES_PASSWORD=${POSTGRES_PASSWORD}

      – POSTGRES_DB=${POSTGRES_DB}

    ports:

      – “${POSTGRES_PORT}:5432”

    volumes:

      – Robility flow-postgres:/var/lib/postgresql/data

  Robility flow-1:

    image: Robility flowai/Robility flow:latest

    pull_policy: always

    ports:

      – “${ROBILITY FLOW_PORT_1}:7860”

    depends_on:

      – postgres

    environment:

      – ROBILITY FLOW_DATABASE_URL
=postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}
@${POSTGRES_HOST}:${POSTGRES_PORT}/${POSTGRES_DB}

      – ROBILITY FLOW_CONFIG_DIR=${ROBILITY FLOW_CONFIG_DIR}

      – ROBILITY FLOW_HOST=${ROBILITY FLOW_HOST}

      – PORT=7860

    volumes:

      – Robility flow-data-1:/app/Robility flow

  Robility flow-2:

    image: Robility flowai/Robility flow:latest

    pull_policy: always

    ports:

      – “${ROBILITY FLOW_PORT_2}:7860”

    depends_on:

      – postgres

    environment:

      – ROBILITY FLOW_DATABASE_URL=postgresql://${POSTGRES_USER}
:${POSTGRES_PASSWORD}@${POSTGRES_HOST}:${POSTGRES_PORT}
/${POSTGRES_DB}

      – ROBILITY FLOW_CONFIG_DIR=${ROBILITY FLOW_CONFIG_DIR}

      – ROBILITY FLOW_HOST=${ROBILITY FLOW_HOST}

      – PORT=7860

    volumes:

      – Robility flow-data-2:/app/Robility flow

volumes:

  Robility flow-postgres:

  Robility flow-data-1:

  Robility flow-data-2:

3. Deploy the file with docker-compose up. You can access the first Robility flow instance at http://localhost:7860, and the second Robility flow instance at http://localhost:7861.
4. To confirm both instances are using the same database, run the docker exec command to start psql in your PostgreSQL container. Your container name may vary.

docker exec -it docker-test-postgres-1 psql -U Robility flow -d Robility flow

5. Query the database for active connections:

Robility flow=# SELECT * FROM pg_stat_activity WHERE datname = ‘Robility flow’;

6. Examine the query results for multiple connections with different client_addr values, for example 172.21.0.3 and 172.21.0.4. Since each Robility flow instance runs in its own container on the Docker network, using different incoming IP addresses confirms that both instances are actively connected to the PostgreSQL database.

7. To quit psql, type quit.