Open-source project
yandex/odyssey avatar
yandex/odyssey

Yandex Odyssey points four build directories at the same folder and calls itself Linux-only

Scalable PostgreSQL connection pooler

3,641 stars224 forksCBSD-3-Clause

At a glance

What is it?
Odyssey is a C implementation of a multi-threaded PostgreSQL connection pooler with transactional pooling, PAM and LDAP authentication and a bundled request router. The build glue is where it gets interesting: four targets share one directory, the platform note contradicts itself, and the compose file starts no database.
Who is it for?
Odyssey fits an operator who wants transaction pooling with real per-pool authentication control and who can build from source on x86 or x86_64 Linux, and it does not fit anyone expecting a packaged install or a turnkey compose stack. Verify three things before you plan around it.
Can I use it commercially?
Yes. BSD-3-Clause is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository received new commits within the last day.
What is it written in?
Mainly C, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • yandex/odyssey3,641 ★ · +13
Star history
Repository2026-09-242026-11-15
yandex/odyssey3.6k3.6k

13 Stars in the last 52 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

Four build directories are declared and all four are named build

The Makefile opens with four variables that look like they should point at four separate trees:

code
BUILD_TEST_DIR=build
BUILD_REL_DIR=build
BUILD_TEST_ASAN_DIR=build
BUILD_TEST_TSAN_DIR=build

They are the same path. The debug build, the release build, the AddressSanitizer build and the ThreadSanitizer build all write into one directory, and clean removes that one directory four times in a row. So a sanitiser run cannot sit alongside a normal build without replacing it, which is exactly the comparison those two targets exist to make. The rest of the file treats them as distinct: local_build runs cmake into $(BUILD_TEST_DIR) with -DCMAKE_BUILD_TYPE=Release, and the parallel job count is nproc on Linux, sysctl -n hw.logicalcpu on Darwin, and 1 everywhere else.

Two more version pins sit at the top. FMT_BIN is fixed to clang-format-18, and check-format does not use it directly: it builds docker/format/Dockerfile into an image tagged odyssey/clang-format-runner and runs that container over modules and sources. Only two targets are declared phony, clean and apply_fmt, and CMAKE_FLAGS starts life as an empty -DCC_FLAGS with BUILD_TYPE set to Release.

The page says Linux only, then gives Mac instructions and a Darwin branch in the Makefile

The build section opens with a flat statement: Odyssey runs only on Linux, supported platforms are x86/x86_64. Thirty lines later there is a Mac-OS section with its own clone, build and run commands, and the Makefile carries a real Darwin branch that resolves openssl@3, bison and flex through brew --prefix and sets the job count from sysctl. So the code and the build system support macOS and the prose does not. The clone command it prints is worth noting as written:

sh
git clone git://github.com/yandex/odyssey.git
cd odyssey
make local_build

That is the git protocol, not https, and the page offers no alternative URL. After local_build the page says to adapt odyssey-dev.conf, then gives make local_run, or make console_run, which runs the same binary with --console --log_to_stdout and a commented-out --verbose. The Darwin branch goes further than the prose does: it appends -DOPENSSL_ROOT_DIR and -DCMAKE_PREFIX_PATH from brew, resolves BISON_EXECUTABLE and FLEX_EXECUTABLE the same way, and picks a different stat command for reading directory ownership, stat -f on Darwin against stat -c everywhere else.

The flex and bison requirement is written for 1.5.3, a version with no release tag

The build dependency lists put flex and bison alongside cmake >= 3.12.4, gcc >= 4.6 and openssl for Ubuntu, and openssl-devel, flex and bison for Fedora. systemd notify support is the only optional item, through libsystemd-dev or systemd-devel. Then a note takes precedence over all of it:

> Note (since 1.5.3): the config parser is now generated from a Flex/Bison grammar at build time. `flex` and `bison` must be installed before running cmake.

Two things follow. The parser is generated during the build, so a machine without flex and bison fails at cmake rather than at configure time, which rules out the usual trick of building in one container and packaging elsewhere. And 1.5.3 is not among the releases: the newest tag is v1.5.2 dated 2026-09-13, preceded by v1.5.2-rc2 on 2026-08-24 and v1.5.2-rc1 on 2026-07-16. So the only documented build requirement is written for a version nobody can install from a tag.

The test and packaging side is parameterised the same way, through variables rather than files: ODYSSEY_TEST_CODENAME defaults to noble, ODYSSEY_TEST_DEBIAN_DISTRO to bookworm, ODYSSEY_TEST_TARGET_PLATFORM to linux/ with the output of uname -m, ODYSSEY_ORACLELINUX_VERSION to 8, ODYSSEY_CC to gcc and PROTO_TEST_TAG to all. A debian/ directory sits at the root for the packaging side, and CMakeLists.txt drives the build that local_build invokes through cmake.

The compose file starts a pooler and an LDAP server, and no PostgreSQL

docker-compose.yml declares three services. The odyssey service builds from ./docker/Dockerfile, publishes 6432, and mounts two paths: the repository's own odyssey.conf over /etc/odyssey.conf, and ..:/odyssey, which is the parent directory of the checkout. The dev service builds from ./docker/dev/Dockerfile with seccomp and apparmor both set to unconfined, which the file itself annotates as needed for gdb debugging, publishes 7776 for ssh and 7777, and mounts the working tree at /code. The third service is an LDAP server:

yaml
  openldapr:
     image: "osixia/openldap:1.5.0"
     ports:
       - "389:389"
       - "636:636"

There is no database service anywhere in the file. Odyssey proxies client connections to a PostgreSQL server, and a reader who brings this stack up gets a pooler listening on 6432, an LDAP directory on 389 and 636, and nothing to pool. The parent-directory mount compounds it: whatever sits next to the checkout is visible inside the container.

Two smaller things in the same file. The compose format version key at the top reads '3', which current Compose ignores in favour of the spec name, and the odyssey service takes its build type from the environment with Release as the default, so the container's compile flags depend on what the shell exports before the run.

Three config files are in play and the page names one of them

Which file Odyssey reads depends on how it was started, and the three paths do not match. The Makefile sets DEV_CONF to ./config-examples/odyssey-dev.conf and both run targets pass it as the single positional argument:

code
local_run: 
	$(BUILD_TEST_DIR)/sources/odyssey $(DEV_CONF)

console_run: 
	$(BUILD_TEST_DIR)/sources/odyssey $(DEV_CONF) --console --log_to_stdout # --verbose

The compose file takes a different route, mounting the repository's top-level odyssey.conf at /etc/odyssey.conf. The page's own instruction is to adapt odyssey-dev.conf, without a path, which matches the Makefile variable and not the compose mount. A config-examples/ directory sits in the tree next to debian/, docker/ and prometheus/, so the variants live together and the compose stack picks the one at the root. Anyone switching between a local run and the container needs to know which of the two they edited.

The binary also takes switches the page does not enumerate: --console and --log_to_stdout appear in the Makefile, and --verbose sits commented out on the same line.

Pools are keyed on a Database and User pair, and each one can carry its own limits

The routing model is two strings. A pool is defined as a pair of Database and User, and every pool carries its own authentication, pooling mode and limits, so two pools pointing at the same server can behave differently for different users. Blocking is per pool user as well, which means a deny is expressed inside a pool definition rather than as a global rule.

Authentication comes in four shapes. md5 and clear text work for both the client and the server side. PAM and LDAP operate like clear text but validate the user name and password pair through those subsystems, and PAM can additionally check the connected remote host name or IP address. All of it sits behind full SSL/TLS support. That combination is what makes the OpenLDAP service in the compose file make sense as a test dependency rather than a stray container, and it is also why authentication is treated as a per-pool setting instead of a server-wide one.

For observability, each client and server connection gets a uuid, and log events and client error responses carry it, with output going either to a log file or to the system logger.

Worker threads share global server pools, which is the whole point of the threading

Scaling is by worker thread. Each one handles authentication and proxies in both directions, and all of them share the global server connection pools rather than holding private ones, so adding threads multiplies client-side concurrency without multiplying server-side connections. The page singles out SSL/TLS performance as where the multi-threaded design earns its keep, which follows from TLS handshakes and symmetric crypto being per connection.

Transactional pooling is the second mechanism. Odyssey tracks the current transaction state, and when a client disappears unexpectedly it emits an automatic Cancel and does a Rollback of the abandoned transaction before the server connection goes back into the pool for reuse. It also remembers which client last owned a server connection, so it does not have to re-establish client options on every client-to-server assignment.

The third mechanism is routing rather than pooling: the project describes itself as a connection pooler and request router, and the tree carries benchmarks/ and prometheus/ directories, so measurement and metrics export are part of the repository rather than something a user wires up afterwards. The status section claims the pooler is production-ready and used in large production setups, and it carries a Coverity scan link whose anchor is empty, so the badge renders as nothing on the page.

Editorial conclusion

Odyssey fits an operator who wants transaction pooling with real per-pool authentication control and who can build from source on x86 or x86_64 Linux, and it does not fit anyone expecting a packaged install or a turnkey compose stack. Verify three things before you plan around it. First, that the release you want actually exists: the newest tag is v1.5.2 dated 2026-09-13 while the build note is written for 1.5.3. Second, that flex and bison are on the machine before cmake runs, since the config parser is generated at build time. Third, which config file you are editing, because the compose stack mounts odyssey.conf while local_run and console_run read config-examples/odyssey-dev.conf.

Frequently asked questions

Which platforms does Yandex Odyssey build on?

The README states that Odyssey runs only on Linux on x86 and x86_64, then gives a Mac-OS section with git clone, make local_build and make local_run, and the Makefile carries a Darwin branch that resolves openssl@3, bison and flex through brew.

What does the current Yandex Odyssey release look like?

The newest tag is v1.5.2 dated 2026-09-13, preceded by v1.5.2-rc2 on 2026-08-24 and v1.5.2-rc1 on 2026-07-16. The build note about flex and bison generating the config parser is written for 1.5.3, which has no release tag, and the last push to master is dated 2026-10-03.

How does Yandex Odyssey handle authentication?

Pools are defined as a Database and User pair, and each pool carries its own authentication, pooling mode and limits, so users can be blocked one pool at a time. Supported methods are md5 and clear text for both client and server sides, plus PAM and LDAP, where PAM can also check the connected remote host name or IP address. All sit behind SSL/TLS.

Does the Yandex Odyssey docker-compose file include a database?

No. It defines an odyssey service on port 6432, a dev service with seccomp and apparmor set to unconfined for gdb, and an OpenLDAP image on ports 389 and 636. No PostgreSQL service is declared, so the pooler has no server to connect to in that stack.

Which configuration file does Yandex Odyssey read?

local_run and console_run pass ./config-examples/odyssey-dev.conf to the binary, and the compose file mounts the repository's top-level odyssey.conf at /etc/odyssey.conf. The build section tells you to adapt odyssey-dev.conf without a path.

What happens to a server connection when a Yandex Odyssey client disconnects unexpectedly?

Odyssey tracks transaction state and emits an automatic Cancel, then does a Rollback of the abandoned transaction, before returning the server connection to the pool for reuse. It also remembers the last owner of a server connection so client options need not be set up again on each assignment.

Official sources

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

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/yandex-odyssey.svg)](https://hysenlabs.com/projects/yandex-odyssey)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/yandex-odyssey.svg)](https://hysenlabs.com/projects/yandex-odyssey)

Was this useful?