Author: |
Trobz,Odoo Community Association (OCA) |
License: |
AGPL-3 |
Branch: |
13.0-session_db-sbi |
Repository: |
acsone/server-tools |
Dependencies: |
bus |
Languages: |
HTML (408, 65.9%),
Python (64, 10.3%),
and
reStructuredText (147, 23.7%) |
Other branches: |
12.0,
13.0,
13.0-bp-jsonifier-ape,
13.0-fix-cache-base_jsonify-ape,
13.0-fix-precommit-ape,
13.0-update-dotfiles-sbi,
14.0,
14.0-mass_mailing_mail_server-mle,
and
14.0-session_db-sbi |
Other repositories: |
AITIC/server-tools,
Callino/server-tools,
Change2improve/server-tools,
Comunitea/server-tools,
Digital5-Odoo/server-tools,
ERPLibre/server-tools,
ForgeFlow/server-tools,
Ingeos/server-tools,
Jarsa/server-tools,
LevelPrime/server-tools,
NL66278/server-tools,
OCA/server-tools,
Rad0van/server-tools,
StefanRijnhart/server-tools,
TRESCLOUD/server-tools,
Tecnativa/server-tools,
VanMoof/server-tools,
Vauxoo/server-tools,
YannickB/server-tools,
aaltinisik/server-tools,
adhoc-dev/server-tools,
akretion/server-tools,
anhvu-sg/server-tools,
aurestic/server-tools,
avoinsystems/server-tools,
blooparksystems/server-tools,
brain-tec/server-tools,
camptocamp/server-tools,
coopiteasy/server-tools,
eLBati/server-tools,
ecosoft-odoo/server-tools,
focusate/oca-server-tools,
grindtildeath/server-tools,
gurneyalex/server-tools,
hbrunn/server-tools,
hibou-io/oca-server-tools,
initOS/server-tools,
invitu/server-tools,
janverb/server-tools,
kmee/server-tools,
legalsylvain/server-tools,
modoolar/server-tools,
multidadosti-erp/server-tools,
nilshamerlinck/server-tools,
ntsirintanis/server-tools,
petrus-v/server-tools,
praxigento/oca-server-tools,
sergiocorato/server-tools,
sodexis/server-tools,
steingabelgaard/server-tools,
sunflowerit/server-tools,
tafaRU/server-tools,
tegin/server-tools,
tirma-sa/server-tools,
trevi-software/server-tools,
unitek-solusi/OCA-server-tools,
ursais/server-tools,
versada/server-tools,
xcgd/server-tools,
ypapouin/server-tools,
zarumaru/server-tools,
and
zhaohuaw/server-tools |
<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/13.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-13-0/server-tools-13-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/13.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:%2013.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/13.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>