yandex/odyssey: a multi-threaded PostgreSQL connection pooler

The problem Odyssey solves for PostgreSQL deployments

PostgreSQL forks a backend process per client connection. A few hundred application workers connecting directly can exhaust memory and file descriptors before the database does any useful work. Odyssey sits between clients and PostgreSQL, holding a smaller set of server connections and handing them to clients as needed. Its README describes it as a multi-threaded connection pooler and request router, and the project states it is production-ready and used in large production setups.

The audience is narrow and specific. You need to run PostgreSQL on Linux, you want to define pools as a pair of Database and User, and you want separate authentication, pooling mode and limits per pool. If your deployment is a single application with a handful of connections, a pooler adds a network hop and a configuration file you have to maintain. Odyssey earns its place when many applications or tenants share one database cluster and each needs its own credential and connection budget.

Multi-threaded workers and shared server pools

The architecture is built around worker threads. The README states that each worker thread is responsible for authentication and for proxying client-to-server and server-to-client requests, and that all worker threads share global server connection pools. That last part matters: adding workers does not multiply the number of server connections, it multiplies the capacity to move bytes. The README also notes that the multi-threaded design plays an important role in SSL/TLS performance, which is where a single-threaded proxy tends to become the bottleneck.

On top of that sits transactional pooling. Odyssey tracks the current transaction state. If a client disconnects unexpectedly, the pooler can emit an automatic Cancel connection and roll back the abandoned transaction before returning the server connection to the pool. The README adds that the last server connection owner client is remembered, which reduces the need to set up client options on every client-to-server assignment.

Authentication is handled per pool. The README lists md5 and clear text for both client and server authentication, plus PAM and LDAP, which operate similarly to clear text except that PAM or LDAP validates the user name and password pair. PAM can optionally check the connected remote host name or IP address. Each pool user can also be blocked individually. For log correlation, Odyssey generates UUIDs for client and server connections, and log events and client error responses carry that id. Logs can go to a file or to the system logger.

Installing Odyssey and running a first pool

The README states that Odyssey currently runs only on Linux, with x86 and x86_64 as the supported platforms. On Ubuntu distributions you need cmake >= 3.12.4, gcc >= 4.6, openssl, flex and bison. libsystemd-dev is optional, for systemd notify support. On Fedora-based distributions the packages are openssl-devel, flex, bison, and systemd-devel as the optional one. The README carries a note for 1.5.3 and later: the config parser is generated from a Flex/Bison grammar at build time, so flex and bison must be installed before running cmake. That is a build-time dependency you cannot skip.

The Makefile in the repository defines a local_build target that cleans, configures CMake into a build directory with the Release build type, and compiles with as many jobs as the machine has cores:

make local_build

After the build, the Makefile runs the binary against the development configuration. The DEV_CONF variable points at ./config-examples/odyssey-dev.conf:

make local_run

For a console session with logging to stdout, the Makefile offers a third target:

make console_run

For a container-based start, the repository ships a docker-compose.yml. The odyssey service builds from ./docker/Dockerfile, maps port 6432 to 6432, and mounts ./odyssey.conf into /etc/odyssey.conf:

services:
  odyssey:
    build:
      dockerfile: ./docker/Dockerfile
      context: .
    ports:
      - "6432:6432"
    volumes:
      - ./odyssey.conf:/etc/odyssey.conf

That same compose file also defines a dev service and an openldapr service running osixia/openldap:1.5.0 on ports 389 and 636, which suggests the LDAP authentication path is meant to be exercised locally. The repository top level contains config-examples/, docs/, prometheus/, modules/, sources/ and test/, so the configuration grammar and the metrics surface are both in-tree rather than in a separate repository.

Where Odyssey is the wrong tool

Platform support is the first hard boundary. The README says Odyssey runs only on Linux, x86 and x86_64. There is a Mac-OS build path documented through make local_build, but the stated supported platforms are Linux on those two architectures. If your production fleet is ARM or you need a pooler on Windows, this is not the project.

The second boundary is build complexity. Because the config parser is generated from a Flex/Bison grammar at build time, a machine without flex and bison cannot build Odyssey at all. That is fine in CI images you control, and annoying everywhere else. It also means the configuration language is defined by a grammar rather than by a hand-written parser, so the set of accepted keys is whatever the grammar accepts.

The third is scope. Odyssey is a pooler and a request router. The README does not describe automatic failover, cluster orchestration, or query routing decisions beyond the connection-level routing implied by pool definitions. If what you actually need is failover management across replicas, a pooler alone will not give it to you. And the README does not document rollback behaviour for any failure other than an unexpected client disconnection during a transaction.

How Odyssey differs from PgBouncer

PgBouncer is the obvious comparison, and the difference is architectural rather than cosmetic. PgBouncer is a single-process pooler; Odyssey is multi-threaded, with each worker thread handling authentication and proxying while sharing the global server connection pools. The README explicitly ties that design to SSL/TLS performance, which is where a single-process model tends to concentrate cost.

Pool definition differs too. Odyssey defines pools as a pair of Database and User, with separate authentication, pooling mode and limits per pool, and it allows blocking each pool user separately. Authentication coverage in the README includes md5, clear text, PAM and LDAP, with PAM optionally checking the remote host name or IP. Transaction handling is the other split: Odyssey tracks transaction state and, on unexpected client disconnection, emits an automatic Cancel and rolls back the abandoned transaction before the server connection returns to the pool. It also remembers the last owner client of a server connection to reduce per-assignment setup.

One practical difference is packaging. Odyssey is C with a CMake build and a Flex/Bison-generated config parser, and the repository ships a Dockerfile and a docker-compose.yml alongside debian/ packaging files. PgBouncer's configuration is a plain ini-style file. If you want to change pooler settings without a build toolchain in the loop, that difference matters more than benchmark numbers.

Maintenance, releases and licence cost

The repository is not archived, and the last push was on 2026-09-23. The most recent release is v1.5.2, published on 2026-09-13, preceded by v1.5.2-rc2 on 2026-08-24 and v1.5.2-rc1 on 2026-07-16. That release cadence, with two release candidates before a patch release, is worth knowing when you plan upgrades: you can track the rc tags if you want early exposure, or wait for the final tag.

Upgrade cost is dominated by the configuration file and the build. The docker-compose.yml mounts ./odyssey.conf into /etc/odyssey.conf, so a container upgrade means re-checking that file against the new build. Since the config parser is generated from a Flex/Bison grammar, a grammar change between versions can alter what the parser accepts, and the README does not describe a compatibility guarantee for configuration across releases. Test your odyssey.conf against the new binary before rolling it out.

Odyssey is BSD-3-Clause. That is a permissive licence, and the practical implication is that redistributing the binary or embedding it in a product carries attribution and disclaimer obligations rather than copyleft ones. This is a description of the licence identifier, not legal advice; read the LICENSE file at the repository root for the actual terms.

Editorial conclusion

Adopt Odyssey if you run PostgreSQL on Linux x86 or x86_64 and need per-database, per-user pools with separate authentication and limits, plus transactional pooling that rolls back abandoned transactions. Do not adopt it if you need macOS or Windows in production, or if you want a pooler with no build-time code generation. Before committing, verify three things: that flex and bison are present on your build hosts, that your odyssey.conf pool definitions match your database and user pairs, and that the BSD-3-Clause terms fit how you redistribute the binary.

Frequently asked questions

Official sources

1. License: BSD-3-Clause
2. Project website
3. README
4. Releases
5. yandex/odyssey on GitHub