Skip to main content

Configure an external PostgreSQL database

SkillFlaw requires PostgreSQL as its application database.

This guide walks you through setting up PostgreSQL for SkillFlaw in local or managed deployment environments.

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

Prerequisites​

Connect SkillFlaw to a local PostgreSQL database​

  1. If SkillFlaw is running, stop SkillFlaw 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 a managed platform or internal network, use the service hostname or DNS name that your platform provides.
    • 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 SkillFlaw .env file:


    _10
    touch .env

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

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


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

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

    PostgreSQL driver compatibility

    SkillFlaw requires psycopg2-binary or psycopg[binary] as the PostgreSQL driver. The asyncpg driver is not compatible with SkillFlaw'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
      SKILLFLAW_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
      SKILLFLAW_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
      SKILLFLAW_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 SkillFlaw environment variables SKILLFLAW_SSL_CERT_FILE and SKILLFLAW_SSL_KEY_FILE for your PostgreSQL certificates: these variables are for enabling HTTPS on the SkillFlaw 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 SkillFlaw with your .env file:


    _10
    uv run skillflaw run --env-file .env

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

  6. In SkillFlaw, 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.

Use one PostgreSQL database for multiple SkillFlaw instances​

You can point multiple SkillFlaw instances at the same PostgreSQL database by giving each instance the same SKILLFLAW_DATABASE_URL.

For example, if you run two SkillFlaw processes on different ports, both can reuse the same database connection string:


_10
SKILLFLAW_DATABASE_URL="postgresql://user:password@db.example.com:5432/skillflaw"

Each instance should still use its own runtime port and, if needed, its own SKILLFLAW_CONFIG_DIR for local files and logs.

After startup, you can verify that both instances are connected by querying PostgreSQL metadata such as pg_stat_activity.

See also​