From ff9b7f257c5aac937b1ab52a4f5c46858d48a2ba Mon Sep 17 00:00:00 2001 From: Nicola Coretti Date: Mon, 9 Sep 2024 12:56:09 +0200 Subject: [PATCH] Add Design Doc (#153) Co-authored-by: Christoph Pirkl <4711730+kaklakariada@users.noreply.github.com> --- docs/DESIGN.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) create mode 100644 docs/DESIGN.md diff --git a/docs/DESIGN.md b/docs/DESIGN.md new file mode 100644 index 0000000..74ee496 --- /dev/null +++ b/docs/DESIGN.md @@ -0,0 +1,13 @@ +# Design + +This document contains background information on various design decisions, which will help current and future maintainers and developers better assess and evaluate potential changes and adjustments to these decisions. + +## Automatic Resolution and Randomization of Connection Addresses + +By default pyexasol resolves host names to IP addresses, randomly shuffles the IP addresses and tries to connect until connection succeeds. This has the following reasons: + +* This will ensure that if at least one hostname is unavailable, an exception will be raised. Otherwise, an exception will occur only when "random" selects a broken hostname, leading to unpredictable errors in production. + +* When you have a very large cluster with a growing number of nodes, it makes sense to put all nodes under one hostname, like `myexasol.mlan`, instead of having separate hostnames like `myexasol1..64.mlan`, especially when the number constantly changes. In this case, redundancy will not work properly if the hostname is not resolved beforehand, as we do not know if it points to a single address or multiple addresses. + +* For redundancy, we do not want to try the same IP address twice. To our knowledge, this cannot be guaranteed if we do not connect by IP.