2018-03-15 11:34:54 +00:00
|
|
|
<p align="center">
|
2018-03-26 14:50:15 +00:00
|
|
|
<img src="documentation/odyssey.png" width="35%" height="35%" /><br>
|
2018-03-15 11:34:54 +00:00
|
|
|
</p>
|
|
|
|
|
<br>
|
2018-03-15 11:40:12 +00:00
|
|
|
|
2018-03-12 14:03:15 +00:00
|
|
|
## Odyssey
|
2016-11-08 11:01:55 +00:00
|
|
|
|
2017-07-14 12:05:09 +00:00
|
|
|
Advanced multi-threaded PostgreSQL connection pooler and request router.
|
2017-01-18 12:07:41 +00:00
|
|
|
|
2017-07-14 12:05:09 +00:00
|
|
|
### Design goals and main features
|
|
|
|
|
|
2018-03-16 10:25:20 +00:00
|
|
|
#### Multi-threaded processing
|
2017-07-14 12:06:51 +00:00
|
|
|
|
2018-03-13 13:41:20 +00:00
|
|
|
Odyssey can significantly scale processing performance by
|
2017-07-14 12:05:09 +00:00
|
|
|
specifying a number of additional worker threads. Each worker thread is
|
|
|
|
|
responsible for authentication and proxying client-to-server and server-to-client
|
|
|
|
|
requests. All worker threads are sharing global server connection pools.
|
2017-07-14 12:23:08 +00:00
|
|
|
Multi-threaded design plays important role in `SSL/TLS` performance.
|
2017-07-14 12:05:09 +00:00
|
|
|
|
2017-07-18 14:06:53 +00:00
|
|
|
#### Advanced transactional pooling
|
2017-07-14 12:06:51 +00:00
|
|
|
|
2018-03-13 13:41:20 +00:00
|
|
|
Odyssey tracks current transaction state and in case of unexpected client
|
2017-07-14 12:05:09 +00:00
|
|
|
disconnection can emit automatic `Cancel` connection and do `Rollback` of
|
|
|
|
|
abandoned transaction, before putting server connection back to
|
|
|
|
|
the server pool for reuse. Additionally, last server connection owner client
|
2018-03-16 10:25:20 +00:00
|
|
|
is remembered to reduce a need for setting up client options on each
|
|
|
|
|
client-to-server assignment.
|
2017-07-14 12:05:09 +00:00
|
|
|
|
2017-07-18 14:06:53 +00:00
|
|
|
#### Better pooling control
|
2017-07-14 12:06:51 +00:00
|
|
|
|
2018-03-13 13:41:20 +00:00
|
|
|
Odyssey allows to define connection pools as a pair of `Database` and `User`.
|
2017-07-18 10:11:59 +00:00
|
|
|
Each defined pool can have separate authentication, pooling mode and limits settings.
|
2017-07-14 12:05:09 +00:00
|
|
|
|
2017-07-18 14:06:53 +00:00
|
|
|
#### Authentication
|
2017-07-14 12:06:51 +00:00
|
|
|
|
2018-03-13 13:41:20 +00:00
|
|
|
Odyssey has full-featured `SSL/TLS` support and common authentication methods
|
2017-07-14 12:05:09 +00:00
|
|
|
like: `md5` and `clear text` both for client and server authentication.
|
|
|
|
|
Additionally it allows to block each pool user separately.
|
|
|
|
|
|
2017-07-18 14:06:53 +00:00
|
|
|
#### Logging
|
2017-07-14 13:12:46 +00:00
|
|
|
|
2018-03-13 13:41:20 +00:00
|
|
|
Odyssey generates universally unique identifiers `uuid` for client and server connections.
|
2017-07-14 13:12:46 +00:00
|
|
|
Any log events and client error responces include the id, which then can be used to
|
2018-03-13 13:41:20 +00:00
|
|
|
uniquely identify client and track actions. Odyssey can save log events into log file and
|
2017-07-14 13:17:03 +00:00
|
|
|
using system logger.
|
2017-07-14 13:12:46 +00:00
|
|
|
|
2018-03-13 13:33:17 +00:00
|
|
|
#### Architecture and internals
|
2017-07-14 12:06:51 +00:00
|
|
|
|
2018-03-16 10:25:20 +00:00
|
|
|
Odyssey has sophisticated asynchronous multi-threaded architecture which
|
2018-03-29 11:44:04 +00:00
|
|
|
is driven by custom made coroutine engine: [machinarium](https://github.yandex-team.ru/pmwkaa/odyssey/tree/master/third_party/machinarium).
|
2017-07-14 12:18:23 +00:00
|
|
|
Main idea behind coroutine design is to make event-driven asynchronous applications to look and feel
|
2017-07-14 12:23:08 +00:00
|
|
|
like being written in synchronous-procedural manner instead of using traditional
|
2017-07-17 12:26:45 +00:00
|
|
|
callback approach.
|
|
|
|
|
|
|
|
|
|
One of the main goal was to make code base understandable for new developers and
|
2017-07-17 12:23:05 +00:00
|
|
|
to make an architecture easily extensible for future development.
|
2017-07-14 12:05:09 +00:00
|
|
|
|
2018-03-21 15:11:57 +00:00
|
|
|
More information: [Architecture and internals](documentation/internals.md).
|
2017-07-14 12:05:09 +00:00
|
|
|
|
2018-03-29 12:24:41 +00:00
|
|
|
#### Build instructions
|
2017-01-18 12:07:41 +00:00
|
|
|
|
|
|
|
|
```sh
|
2018-03-29 11:44:04 +00:00
|
|
|
git clone git://github.yandex-team.ru/pmwkaa/odyssey.git
|
2018-03-12 14:03:15 +00:00
|
|
|
cd odyssey
|
2017-01-18 12:07:41 +00:00
|
|
|
mkdir build
|
|
|
|
|
cd build
|
2017-02-07 15:58:26 +00:00
|
|
|
cmake -DCMAKE_BUILD_TYPE=Release ..
|
2017-01-18 12:07:41 +00:00
|
|
|
make
|
|
|
|
|
```
|
2018-03-29 12:24:41 +00:00
|
|
|
|
|
|
|
|
#### Documentation
|
|
|
|
|
|
|
|
|
|
### Configuration
|
|
|
|
|
|
|
|
|
|
**Service**
|
|
|
|
|
|
|
|
|
|
* [include](https://github.yandex-team.ru/pmwkaa/odyssey/blob/master/documentation/configuration.md#include-string)
|
|
|
|
|
* [daemonize](https://github.yandex-team.ru/pmwkaa/odyssey/blob/master/documentation/configuration.md#daemonize-yesno)
|
|
|
|
|
* [pid\_file](https://github.yandex-team.ru/pmwkaa/odyssey/blob/master/documentation/configuration.md#pid_file-string)
|
|
|
|
|
|
|
|
|
|
**Logging**
|
|
|
|
|
|
|
|
|
|
* [log\_file](https://github.yandex-team.ru/pmwkaa/odyssey/blob/master/documentation/configuration.md#log_file-string)
|
|
|
|
|
* [log\_format](https://github.yandex-team.ru/pmwkaa/odyssey/blob/master/documentation/configuration.md#log_format-string)
|
|
|
|
|
* [log\_to\_stdout](https://github.yandex-team.ru/pmwkaa/odyssey/blob/master/documentation/configuration.md#log_to_stdout-yesno)
|
|
|
|
|
* [log\_syslog](https://github.yandex-team.ru/pmwkaa/odyssey/blob/master/documentation/configuration.md#log_syslog-yesno)
|
|
|
|
|
* [log\_syslog\_ident](https://github.yandex-team.ru/pmwkaa/odyssey/blob/master/documentation/configuration.md#log_syslog_ident-string)
|
|
|
|
|
* [log\_syslog\_facility](https://github.yandex-team.ru/pmwkaa/odyssey/blob/master/documentation/configuration.md#log_syslog_facility-string)
|
|
|
|
|
* [log\_debug](https://github.yandex-team.ru/pmwkaa/odyssey/blob/master/documentation/configuration.md#log_debug-yesno)
|
|
|
|
|
* [log\_config](https://github.yandex-team.ru/pmwkaa/odyssey/blob/master/documentation/configuration.md#log_config-yesno)
|
|
|
|
|
* [log\_session](https://github.yandex-team.ru/pmwkaa/odyssey/blob/master/documentation/configuration.md#log_session-yesno)
|
|
|
|
|
* [log\_query](https://github.yandex-team.ru/pmwkaa/odyssey/blob/master/documentation/configuration.md#log_query-yesno)
|
|
|
|
|
* [log\_stats](https://github.yandex-team.ru/pmwkaa/odyssey/blob/master/documentation/configuration.md#log_stats-yesno)
|
|
|
|
|
* [stats\_interval](https://github.yandex-team.ru/pmwkaa/odyssey/blob/master/documentation/configuration.md#stats_interval-integer)
|
|
|
|
|
|
|
|
|
|
**Performance**
|
|
|
|
|
|
|
|
|
|
* [workers](https://github.yandex-team.ru/pmwkaa/odyssey/blob/master/documentation/configuration.md#workers-integer)
|
|
|
|
|
* [resolvers](https://github.yandex-team.ru/pmwkaa/odyssey/blob/master/documentation/configuration.md#resolvers-integer)
|
|
|
|
|
* [readahead](https://github.yandex-team.ru/pmwkaa/odyssey/blob/master/documentation/configuration.md#readahead-integer)
|
|
|
|
|
* [pipeline](https://github.yandex-team.ru/pmwkaa/odyssey/blob/master/documentation/configuration.md#pipeline-integer)
|
|
|
|
|
* [cache](https://github.yandex-team.ru/pmwkaa/odyssey/blob/master/documentation/configuration.md#cache-integer)
|
|
|
|
|
* [cache\_chunk](https://github.yandex-team.ru/pmwkaa/odyssey/blob/master/documentation/configuration.md#cache_chunk-integer)
|
|
|
|
|
* [cache\_coroutine](https://github.yandex-team.ru/pmwkaa/odyssey/blob/master/documentation/configuration.md#cache_coroutine-integer)
|
|
|
|
|
* [nodelay](https://github.yandex-team.ru/pmwkaa/odyssey/blob/master/documentation/configuration.md#nodelay-yesno)
|
|
|
|
|
* [keepalive](https://github.yandex-team.ru/pmwkaa/odyssey/blob/master/documentation/configuration.md#keepalive-integer)
|
|
|
|
|
|
|
|
|
|
**Global limits**
|
|
|
|
|
|
|
|
|
|
* [client\_max](https://github.yandex-team.ru/pmwkaa/odyssey/blob/master/documentation/configuration.md#client_max-integer)
|
|
|
|
|
|
|
|
|
|
**Listen**
|
|
|
|
|
|
|
|
|
|
* [host](https://github.yandex-team.ru/pmwkaa/odyssey/blob/master/documentation/configuration.md#host-string)
|
|
|
|
|
* [port](https://github.yandex-team.ru/pmwkaa/odyssey/blob/master/documentation/configuration.md#port-integer)
|
|
|
|
|
* [backlog](https://github.yandex-team.ru/pmwkaa/odyssey/blob/master/documentation/configuration.md#backlog-integer)
|
|
|
|
|
* [tls](https://github.yandex-team.ru/pmwkaa/odyssey/blob/master/documentation/configuration.md#tls-string)
|
|
|
|
|
|
|
|
|
|
**Routing rules**
|
|
|
|
|
|
|
|
|
|
* [overview](https://github.yandex-team.ru/pmwkaa/odyssey/blob/master/documentation/configuration.md#routing-rules)
|
|
|
|
|
|
|
|
|
|
**Console**
|
|
|
|
|
|
|
|
|
|
* [example](https://github.yandex-team.ru/pmwkaa/odyssey/blob/master/documentation/configuration.md#admin-console)
|
