Use Odyssey

Eugenia Kuzina

Odyssey is a connection pooler. ADP implements this functionality using PgBouncer, and for most workloads, pgBouncer is the optimal choice, but if you need to handle thousands of concurrent connections with high CPU load, consider using Odyssey. To do this, disable PgBouncer as described in Configure PgBouncer and install Odyssey using the instructions from this article.

To use Odyssey, follow the steps below:

  1. Install Odyssey. The package for installing Odyssey is located in the ADP repository, so you can install it with the apt install command:

    $ sudo apt install -y adpg16-odyssey

    The related systemd unit file is located at the path /usr/lib/systemd/system/adpg16-odyssey.service:

    $ cat /usr/lib/systemd/system/adpg16-odyssey.service
    [Unit]
Description=Advanced multi-threaded PostgreSQL connection pooler and request router
After=network.target

[Service]
User=odyssey
Group=odyssey
Type=simple
ExecStart=/usr/bin/odyssey /etc/adpg16-odyssey/odyssey.conf
LimitNOFILE=100000
LimitNPROC=100000

[Install]
WantedBy=multi-user.target

  2. Edit the Odyssey configuration file according to your requirements. You can find it at the following path: /etc/adpg16-odyssey/odyssey.conf. Refer to the Odyssey documentation for information on configuration parameters. In particular, for Odyssey, which is installed with ADP on a single host with 8 CPUs, in the transaction pool mode, you can use the following configuration:

    unix_socket_dir "/tmp"
unix_socket_mode "0666"

log_format "%p %t %l [%i %s] (%c) %m\n"
log_to_stdout yes
log_session yes
log_query no
client_max 20000
coroutine_stack_size 24
resolvers 8
workers 8
cache_coroutine 12000

daemonize no

locks_dir "/tmp/odyssey"

listen {
        host "127.0.0.1"
        port 25432
        backlog 10000
}

storage "local" {
        type "local"
}

storage "postgres_server" {
        type "remote"
        host "127.0.0.1"
        port 5432
}

database default {
        user default {
                authentication "none"
                storage "postgres_server"
                pool "transaction"
                client_fwd_error yes
                pool_ttl 3600
                pool_size 100
                min_pool_size 100
                client_max 60000
                # Pool settings
                pool_discard no
                pool_smart_discard no
                log_debug no
        }
}

database "console" {
        user default {
                authentication "none"
                pool "session"
                storage "local"
        }
}
    IMPORTANT

    • In ADP, the 6432 port, which Odyssey listens on by default, is reserved for the Balancer service. It is recommended to use the 25432 port for Odyssey.

    • It is necessary to add the port, which Odyssey is listening on, in the firewall’s list of exception ports if it is used in the system.

  3. Start Odyssey:

    $ sudo systemctl start adpg16-odyssey.service

    You can also create a symbolic link to the service’s unit file to start the service automatically at the system boot:

    $ sudo systemctl enable adpg16-odyssey.service
    Created symlink /etc/systemd/system/multi-user.target.wants/adpg16-odyssey.service → /lib/systemd/system/adpg16-odyssey.service.

  4. Check the state of the Odyssey service:

    $ sudo systemctl status adpg16-odyssey.service
     adpg16-odyssey.service - Advanced multi-threaded PostgreSQL connection pooler and request router
     Loaded: loaded (/lib/systemd/system/adpg16-odyssey.service; enabled; vendor preset: enabled)
     Active: active (running) since Tue 2026-02-10 07:07:02 UTC; 10s ago
   Main PID: 7922 (odyssey)
      Tasks: 20 (limit: 19050)
     Memory: 3.2M
        CPU: 14ms
     CGroup: /system.slice/adpg16-odyssey.service
             └─7922 "odyssey: version 217 listening and accepting new connections "

Feb 10 07:07:10 eek-cl4-host-1 odyssey[7922]: 7922 2026-02-10T07:07:10Z info [none none] (stats) worker[0]: msg (2 allocated, 0 cached, 2 freed, 0 cache_size), coroutines (1 active, 0 cached), clients_processed: 0
Feb 10 07:07:10 eek-cl4-host-1 odyssey[7922]: 7922 2026-02-10T07:07:10Z info [none none] (stats) worker[1]: msg (2 allocated, 0 cached, 2 freed, 0 cache_size), coroutines (1 active, 0 cached), clients_processed: 0
Feb 10 07:07:10 eek-cl4-host-1 odyssey[7922]: 7922 2026-02-10T07:07:10Z info [none none] (stats) worker[2]: msg (2 allocated, 0 cached, 2 freed, 0 cache_size), coroutines (1 active, 0 cached), clients_processed: 0
Feb 10 07:07:10 eek-cl4-host-1 odyssey[7922]: 7922 2026-02-10T07:07:10Z info [none none] (stats) clients 0
Feb 10 07:07:10 eek-cl4-host-1 odyssey[7922]: 7922 2026-02-10T07:07:10Z info [none none] (stats) worker[5]: msg (2 allocated, 0 cached, 2 freed, 0 cache_size), coroutines (1 active, 0 cached), clients_processed: 0
Feb 10 07:07:10 eek-cl4-host-1 odyssey[7922]: 7922 2026-02-10T07:07:10Z info [none none] (stats) logger: msg (2 allocated, 0 cached, 29 freed, 0 cache_size), coroutines (1 active, 0 cached)
Feb 10 07:07:10 eek-cl4-host-1 odyssey[7922]: 7922 2026-02-10T07:07:10Z info [none none] (stats) worker[7]: msg (2 allocated, 0 cached, 2 freed, 0 cache_size), coroutines (1 active, 0 cached), clients_processed: 0
Feb 10 07:07:10 eek-cl4-host-1 odyssey[7922]: 7922 2026-02-10T07:07:10Z info [none none] (stats) worker[3]: msg (2 allocated, 0 cached, 2 freed, 0 cache_size), coroutines (1 active, 0 cached), clients_processed: 0
Feb 10 07:07:10 eek-cl4-host-1 odyssey[7922]: 7922 2026-02-10T07:07:10Z info [none none] (stats) worker[6]: msg (2 allocated, 0 cached, 2 freed, 0 cache_size), coroutines (1 active, 0 cached), clients_processed: 0
Feb 10 07:07:10 eek-cl4-host-1 odyssey[7922]: 7922 2026-02-10T07:07:10Z info [none none] (stats) worker[4]: msg (2 allocated, 0 cached, 2 freed, 0 cache_size), coroutines (1 active, 0 cached), clients_processed: 0

  5. To test the connection to ADP, run psql. The port should match the port value from the listen section of the Odyssey configuration:

    $ psql -U postgres -d postgres -h localhost -p 25432

    Run an arbitrary query:

    SELECT relname, relfilenode FROM pg_class LIMIT 5;
           relname       | relfilenode
---------------------+-------------
 pg_statistic        |        2619
 pg_type             |           0
 pg_toast_1255       |           0
 pg_toast_1255_index |           0
 pg_toast_1247       |           0

The query to the postgres database via Odyssey was successfully executed.

Found a mistake? Seleсt text and press Ctrl+Enter to report it