Skip to main content

Configure an external PostgreSQL database

Orbis Studio's default database is SQLite, but you can configure Orbis Studio to use PostgreSQL instead.

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

In this configuration, all structured application data from Orbis Studio, 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. Orbis Studio can more efficiently handle multiple users and larger workloads by using PostgreSQL as the database.

Prerequisites​

Connect Orbis Studio to a local PostgreSQL database​

  1. If Orbis Studio is running, stop Orbis Studio 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:

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

  3. Edit or create an Orbis Studio .env file:


    _10
    touch .env

    You can use the .env.example file in the Orbis Studio repository as a template for your own .env file.

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


    _10
    ORBISAGENTS_DATABASE_URL="postgresql://user:password@localhost:5432/dbname"

    Orbis Studio uses SQLAlchemy with the psycopg driver to pass SSL parameters directly to the PostgreSQL connection.

    PostgreSQL driver compatibility

    Orbis Studio requires psycopg2-binary or psycopg[binary] as the PostgreSQL driver. The asyncpg driver is not compatible with Orbis Studio's current database schema due to stricter timezone handling requirements.

    The following SSL modes are supported:

    • sslmode=require: Requires SSL connection but doesn't verify server certificate. This option is the least secure, but acceptable for most use cases.


      _10
      ORBISAGENTS_DATABASE_URL="postgresql://user:password@localhost:5432/dbname?sslmode=require"

    • sslmode=verify-ca: Requires SSL and verifies the server certificate against the Certificate Authority (CA). Add the certificate paths to your connection string:


      _10
      ORBISAGENTS_DATABASE_URL="postgresql://user@localhost:5432/dbname?sslmode=verify-ca&sslcert=/path/to/client.crt&sslkey=/path/to/client.key&sslrootcert=/path/to/ca.crt"

    • sslmode=verify-full: Requires SSL, verifies the server certificate, and checks the request hostname against the certificate hostname. The db.example.com hostname in this example must match the server certificate's CN. This option is the most secure.


      _10
      ORBISAGENTS_DATABASE_URL="postgresql://user@db.example.com:5432/dbname?sslmode=verify-full&sslcert=/path/to/client.crt&sslkey=/path/to/client.key&sslrootcert=/path/to/ca.crt"

      Do not use the Orbis Studio environment variables ORBISAGENTS_SSL_CERT_FILE and ORBISAGENTS_SSL_KEY_FILE for your PostgreSQL certificates: these variables are for enabling HTTPS on the Orbis Studio server, not for PostgreSQL database connections.

      For more on managing SSL certificates in PostgreSQL, see the PostgreSQL documentation.

  5. Save your changes, and then start Orbis Studio with your .env file:


    _10
    uv run langflow run --env-file .env

    For optional connection pooling and timeout settings, see Configure external memory.

  6. In Orbis Studio, 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 Orbis Studio and PostgreSQL containers with docker-compose.yml​

Launching Orbis Studio and PostgreSQL containers in the same Docker network ensures proper connectivity between services. For an example, see the docker-compose.yml file in the Orbis Studio repository.

The configuration in the example docker-compose.yml also sets up persistent volumes for both Orbis Studio 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 Orbis Studio container, and this prevents Orbis Studio from connecting to PostgreSQL using the service name.

To start the Orbis Studio and PostgreSQL services with the example Docker Compose file, navigate to the langflow/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 Orbis Studio instances with a shared PostgreSQL database​

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

This example populates the values in docker-compose.yml with values from your Orbis Studio .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:


    _10
    POSTGRES_USER=langflow
    _10
    POSTGRES_PASSWORD=your_secure_password
    _10
    POSTGRES_DB=langflow
    _10
    POSTGRES_HOST=postgres
    _10
    POSTGRES_PORT=5432
    _10
    ORBISAGENTS_CONFIG_DIR=app/langflow
    _10
    ORBISAGENTS_PORT_1=7860
    _10
    ORBISAGENTS_PORT_2=7861
    _10
    ORBISAGENTS_HOST=0.0.0.0

    For optional connection pooling and timeout settings, see Configure external memory.

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


    _44
    services:
    _44
    postgres:
    _44
    image: postgres:16
    _44
    environment:
    _44
    - POSTGRES_USER=${POSTGRES_USER}
    _44
    - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
    _44
    - POSTGRES_DB=${POSTGRES_DB}
    _44
    ports:
    _44
    - "${POSTGRES_PORT}:5432"
    _44
    volumes:
    _44
    - langflow-postgres:/var/lib/postgresql/data
    _44
    _44
    langflow-1:
    _44
    image: orbis-studio:latest
    _44
    ports:
    _44
    - "${ORBISAGENTS_PORT_1}:7860"
    _44
    depends_on:
    _44
    - postgres
    _44
    environment:
    _44
    - ORBISAGENTS_DATABASE_URL=postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@${POSTGRES_HOST}:${POSTGRES_PORT}/${POSTGRES_DB}
    _44
    - ORBISAGENTS_CONFIG_DIR=${ORBISAGENTS_CONFIG_DIR}
    _44
    - ORBISAGENTS_HOST=${ORBISAGENTS_HOST}
    _44
    - PORT=7860
    _44
    volumes:
    _44
    - langflow-data-1:/app/langflow
    _44
    _44
    langflow-2:
    _44
    image: orbis-studio:latest
    _44
    ports:
    _44
    - "${ORBISAGENTS_PORT_2}:7860"
    _44
    depends_on:
    _44
    - postgres
    _44
    environment:
    _44
    - ORBISAGENTS_DATABASE_URL=postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@${POSTGRES_HOST}:${POSTGRES_PORT}/${POSTGRES_DB}
    _44
    - ORBISAGENTS_CONFIG_DIR=${ORBISAGENTS_CONFIG_DIR}
    _44
    - ORBISAGENTS_HOST=${ORBISAGENTS_HOST}
    _44
    - PORT=7860
    _44
    volumes:
    _44
    - langflow-data-2:/app/langflow
    _44
    _44
    volumes:
    _44
    langflow-postgres:
    _44
    langflow-data-1:
    _44
    langflow-data-2:

  3. Deploy the file with docker-compose up. You can access the first Orbis Studio instance at http://localhost:7860, and the second Orbis Studio 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.


    _10
    docker exec -it docker-test-postgres-1 psql -U langflow -d langflow

  5. Query the database for active connections:


    _10
    langflow=# SELECT * FROM pg_stat_activity WHERE datname = 'langflow';

  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 Orbis Studio 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.

See also​