flow/docs/versioned_docs/version-1.9.0/Develop/configuration-custom-database.mdx

---
title: Configure an external PostgreSQL database
slug: /configuration-custom-database
---

Hanzo Flow's default database is [SQLite](https://www.sqlite.org/docs.html), but you can configure Hanzo Flow to use PostgreSQL instead.

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

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

## Prerequisites

- A [PostgreSQL](https://www.pgadmin.org/download/) database version 15 or later

## Connect Hanzo Flow to a local PostgreSQL database

1. If Hanzo Flow is running, stop Hanzo Flow with <kbd>Ctrl+C</kbd>.

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 a Hanzo Flow `.env` file:

    ```
    touch .env
    ```

    You can use the [`.env.example`](https://github.com/hanzoai/flow/blob/main/.env.example) file in the Hanzo Flow repository as a template for your own `.env` file.

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

    ```text
    FLOW_DATABASE_URL="postgresql://user:password@localhost:5432/dbname"
    ```

    Hanzo Flow uses [SQLAlchemy](https://www.sqlalchemy.org/) with the [psycopg](https://www.psycopg.org/) driver to pass SSL parameters directly to the PostgreSQL connection.

    :::warning PostgreSQL driver compatibility
    Hanzo Flow requires `psycopg2-binary` or `psycopg[binary]` as the PostgreSQL driver. The `asyncpg` driver is not compatible with Hanzo Flow'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.
        ```bash
        FLOW_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:
        ```bash
        FLOW_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.
        ```bash
        FLOW_DATABASE_URL="postgresql://[email protected]:5432/dbname?sslmode=verify-full&sslcert=/path/to/client.crt&sslkey=/path/to/client.key&sslrootcert=/path/to/ca.crt"
        ```

        Do not use the Hanzo Flow environment variables [`FLOW_SSL_CERT_FILE`](/environment-variables#server) and [`FLOW_SSL_KEY_FILE`](/environment-variables#server) for your PostgreSQL certificates: these variables are for enabling HTTPS on the Hanzo Flow server, not for PostgreSQL database connections.

        For more on managing SSL certificates in PostgreSQL, see the [PostgreSQL documentation](https://www.postgresql.org/docs/9.1/ssl-tcp.html).

5. Save your changes, and then start Hanzo Flow with your `.env` file:

    ```bash
    uv run flow run --env-file .env
    ```

    For optional connection pooling and timeout settings, see [Configure external memory](/memory#configure-external-memory).

6. In Hanzo 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 Hanzo Flow and PostgreSQL containers with docker-compose.yml

Launching Hanzo Flow and PostgreSQL containers in the same Docker network ensures proper connectivity between services.
For an example, see the [`docker-compose.yml`](https://github.com/hanzoai/flow/blob/main/docker_example/docker-compose.yml) file in the Hanzo Flow repository.

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

To start the Hanzo Flow and PostgreSQL services with the example Docker Compose file, navigate to the `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 Hanzo Flow instances with a shared PostgreSQL database

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

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

    ```text
    POSTGRES_USER=flow
    POSTGRES_PASSWORD=your_secure_password
    POSTGRES_DB=flow
    POSTGRES_HOST=postgres
    POSTGRES_PORT=5432
    FLOW_CONFIG_DIR=app/flow
    FLOW_PORT_1=7860
    FLOW_PORT_2=7861
    FLOW_HOST=0.0.0.0
    ```

    For optional connection pooling and timeout settings, see [Configure external memory](/memory#configure-external-memory).

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

    ```yaml
    services:
      postgres:
        image: postgres:16
        environment:
          - POSTGRES_USER=${POSTGRES_USER}
          - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
          - POSTGRES_DB=${POSTGRES_DB}
        ports:
          - "${POSTGRES_PORT}:5432"
        volumes:
          - flow-postgres:/var/lib/postgresql/data

      flow-1:
        image: flowai/flow:latest
        pull_policy: always
        ports:
          - "${FLOW_PORT_1}:7860"
        depends_on:
          - postgres
        environment:
          - FLOW_DATABASE_URL=postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@${POSTGRES_HOST}:${POSTGRES_PORT}/${POSTGRES_DB}
          - FLOW_CONFIG_DIR=${FLOW_CONFIG_DIR}
          - FLOW_HOST=${FLOW_HOST}
          - PORT=7860
        volumes:
          - flow-data-1:/app/flow

      flow-2:
        image: flowai/flow:latest
        pull_policy: always
        ports:
          - "${FLOW_PORT_2}:7860"
        depends_on:
          - postgres
        environment:
          - FLOW_DATABASE_URL=postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@${POSTGRES_HOST}:${POSTGRES_PORT}/${POSTGRES_DB}
          - FLOW_CONFIG_DIR=${FLOW_CONFIG_DIR}
          - FLOW_HOST=${FLOW_HOST}
          - PORT=7860
        volumes:
          - flow-data-2:/app/flow

    volumes:
      flow-postgres:
      flow-data-1:
      flow-data-2:
    ```

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

    ```bash
    docker exec -it docker-test-postgres-1 psql -U flow -d flow
    ```

5. Query the database for active connections:

    ```sql
    flow=# SELECT * FROM pg_stat_activity WHERE datname = '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 Hanzo 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`.

## See also

* [Hanzo Flow database guide for enterprise DBAs](/enterprise-database-guide)
* [Memory management options](/memory)
* [Logs](/logging)