Search 1.9 billion lines of Odoo code on GitHub
bus_alt_connection
<h1 class="title">Bus Alt Connection</h1>
<p><a class="reference external" href="https://odoo-community.org/page/development-status"><img alt="Beta" src="https://img.shields.io/badge/maturity-Beta-yellow.png" /></a> <a class="reference external" href="http://www.gnu.org/licenses/agpl-3.0-standalone.html"><img alt="License: AGPL-3" src="https://img.shields.io/badge/licence-AGPL--3-blue.png" /></a> <a class="reference external" href="https://github.com/OCA/server-tools/tree/14.0/bus_alt_connection"><img alt="OCA/server-tools" src="https://img.shields.io/badge/github-OCA%2Fserver--tools-lightgray.png?logo=github" /></a> <a class="reference external" href="https://translation.odoo-community.org/projects/server-tools-14-0/server-tools-14-0-bus_alt_connection"><img alt="Translate me on Weblate" src="https://img.shields.io/badge/weblate-Translate%20me-F47D42.png" /></a> <a class="reference external" href="https://runbot.odoo-community.org/runbot/149/14.0"><img alt="Try me on Runbot" src="https://img.shields.io/badge/runbot-Try%20me-875A7B.png" /></a></p>
<p>This module makes it possible to use <a class="reference external" href="https://pgbouncer.github.io/">PgBouncer</a> as a connection pooler
for odoo.</p>
<a name="why-isn-t-odoo-s-connection-pooling-good-enough"></a>
<h2>Why isn't odoo's connection pooling good enough?</h2>
<p>Odoo's builtin connection pooling works at process level: each Odoo process
has its own <a class="reference external" href="https://github.com/odoo/odoo/blob/12.0/odoo/sql_db.py#L525">ConnectionPool</a>, limited to <code>db_maxconn</code>.</p>
<p>It does the job of re-using open connections available in the pool.
But it never closes these connections, <a class="reference external" href="https://github.com/odoo/odoo/blob/12.0/odoo/sql_db.py#L593">unless reaching db_maxconn</a>.</p>
<p>In practice, we observe that each odoo worker will end up
with up to 3 open connection in its pool.
With 10 http workers, that's up to 30 connection continuously open just
for one single instance.</p>
<a name="here-comes-pgbouncer"></a>
<h2>Here comes PgBouncer</h2>
<p>PgBouncer will help to limit this number of open connections,
by sharing a pool of connections at the instance level, between
all workers. Odoo workers will still have up to 3 open connections,
but these will be connections to PgBouncer, that on its side will
close unnecessary connections to pg.</p>
<p>This has proven to help performances on Odoo deployments with
multiple instances.</p>
<p>It allows you to define how resources should be shared,
according to your priorities, e.g. :</p>
<ul class="simple">
<li>key odoo instance on host A can open up to 30 connections</li>
<li>while odoo instance on host B, dedicated to reports,
can open up to 10 connections only</li>
</ul>
<p>And most importantly, it helps you to ensure that
<code>max_connections</code> will never be reached on pg server side.</p>
<a name="why-is-this-module-needed"></a>
<h2>Why is this module needed?</h2>
<p>When configuring PgBouncer, you can choose between 2 transaction pooling modes:</p>
<ul class="simple">
<li><cite>pool_mode = session</cite></li>
<li><cite>pool_mode = transaction</cite></li>
</ul>
<p>If we choose <cite>pool_mode = session</cite>, then one server connection will be tied
to a given odoo process until its death, which is exactly what we're trying
to change. Thus, to release the server connection once the transaction is
complete, we use <cite>pool_mode = transaction</cite>.</p>
<p>This works fine, except for Odoo's longpolling features that relies
on the <a class="reference external" href="https://www.postgresql.org/docs/9.6/static/sql-notify.html">LISTEN/NOTIFY</a> mechanism from pg, which is <a class="reference external" href="https://wiki.postgresql.org/wiki/PgBouncer">not compatible</a> with that
mode.</p>
<p>To be more precise, <cite>NOTIFY</cite> statements are properly transfered by PgBouncer
in that mode; only the <cite>LISTEN</cite> statement isn't (because it needs to keep the
server connection open).</p>
<p>So for the unique "listening" connection per instance that requires this
statement (<a class="reference external" href="https://github.com/odoo/odoo/blob/12.0/addons/bus/models/bus.py#L166">here</a>), we need odoo to connect directly to the pg server, bypassing
PgBouncer.</p>
<p>That's what this module implements, by overriding the relevant method
of the <a class="reference external" href="https://github.com/odoo/odoo/blob/12.0/addons/bus/models/bus.py#L105">Dispatcher</a>.</p>
<p><strong>Table of contents</strong></p>
<a name="installation"></a>
<h2>Installation</h2>
<p>You don't need to install this module in the database(s) to enable it.</p>
<p>But you need to load it server-wide:</p>
<ul class="simple">
<li>By starting Odoo with <code>--load=web,bus_alt_connection</code></li>
<li>Or by updating its configuration file:</li>
</ul>
<pre>
<code lang="ini">[options]
(...)
server_wide_modules = web,bus_alt_connection</code>
</pre>
<a name="configuration"></a>
<h2>Configuration</h2>
<p>You need to define how to connect directly to the database:</p>
<ul>
<li><p class="first">Either by defining environment variables:</p>
<blockquote>
<ul class="simple">
<li><code>IMDISPATCHER_DB_HOST=db-01</code></li>
<li><code>IMDISPATCHER_DB_PORT=5432</code></li>
</ul>
</blockquote>
</li>
<li><p class="first">Or in Odoo's configuration file:</p>
</li>
</ul>
<pre>
<code lang="ini">[options]
(...)
imdispatcher_db_host = db-01
imdispatcher_db_port = 5432</code>
</pre>
<a name="bug-tracker"></a>
<h2>Bug Tracker</h2>
<p>Bugs are tracked on <a class="reference external" href="https://github.com/OCA/server-tools/issues">GitHub Issues</a>.
In case of trouble, please check there if your issue has already been reported.
If you spotted it first, help us smashing it by providing a detailed and welcomed
<a class="reference external" href="https://github.com/OCA/server-tools/issues/new?body=module:%20bus_alt_connection%0Aversion:%2014.0%0A%0A**Steps%20to%20reproduce**%0A-%20...%0A%0A**Current%20behavior**%0A%0A**Expected%20behavior**">feedback</a>.</p>
<p>Do not contact contributors directly about support or help with technical issues.</p>
<a name="credits"></a>
<h2>Credits</h2>
<a name="authors"></a>
<h3>Authors</h3>
<ul class="simple">
<li>Trobz</li>
</ul>
<a name="contributors"></a>
<h3>Contributors</h3>
<ul class="simple">
<li>Nils Hamerlinck <<a class="reference external" href="mailto:nils@trobz.com">nils@trobz.com</a>></li>
</ul>
<a name="maintainers"></a>
<h3>Maintainers</h3>
<p>This module is maintained by the OCA.</p>
<a class="reference external image-reference" href="https://odoo-community.org"><img alt="Odoo Community Association" src="https://odoo-community.org/logo.png" /></a>
<p>OCA, or the Odoo Community Association, is a nonprofit organization whose
mission is to support the collaborative development of Odoo features and
promote its widespread use.</p>
<p>This module is part of the <a class="reference external" href="https://github.com/OCA/server-tools/tree/14.0/bus_alt_connection">OCA/server-tools</a> project on GitHub.</p>
<p>You are welcome to contribute. To learn how please visit <a class="reference external" href="https://odoo-community.org/page/Contribute">https://odoo-community.org/page/Contribute</a>.</p>