21.2. Подключение и работа с кластером Postgres Pro Shardman #

Кластер состоит из четырёх сегментов. Секции данных основной сегментированной таблицы распределяются по остальным сегментам таким образом:

Для ключа сегментирования ticket_no:

  • tickets_0 — сегмент-1 (узел кластера node1)

  • tickets_1 — сегмент-2 (узел кластера node2)

  • tickets_2 — сегмент-3 (узел кластера node3)

  • tickets_3 — сегмент-4 (узел кластера node4)

Для ключа сегментирования book_ref:

  • bookings_0 — сегмент-1 (узел кластера node1)

  • bookings_1 — сегмент-2 (узел кластера node2)

  • bookings_2 — сегмент-3 (узел кластера node3)

  • bookings_3 — сегмент-4 (узел кластера node4)

Ниже приведены примеры для ключа сегментирования book_ref, но указанный в подразделах код будет справедлив и для ключа сегментирования ticket_no.

Не стоит рассматривать данный код как оптимальный или пригодный для производственной среды. Он дан только как пример реализации создания пула соединений для работы с кластером Postgres Pro Shardman.

Общее для всех приведённых примеров — строка подключения к кластеру, которая должна содержать имена узлов, номера TCP-портов, имя и пароль пользователя, имя базы данных для подключения и набор параметров сеанса.

Такую строку можно получить с помощью утилиты shardmanctl. В простейшем случае строка будет выглядеть так:

   $ shardmanctl getconnstr

   dbname=postgres host=node1,node2,node3,node4 port=5432,5432,5432,5432
   

Её можно использовать для подключения к узлам кластера или для создания пула соединений в приложениях.

21.2.1. SQL #

В Postgres Pro Shardman реализовано несколько удобных функций и представлений для наблюдения за кластером:

  • Вывод списка реплицированных таблиц

  • Вывод списка сегментированная таблиц

  • Вывод списка управляемых последовательностей

  • Вычисление номера сегмента по ключу сегментирования

  • Выполнение ANALYZE для всех управляемых таблиц в кластере

21.2.1.1. Вывод списка реплицированных таблиц #

Для вывода всех реплицированных таблиц в кластере используйте представление shardman.global_tables:

   postgres=# select
      relname as table_name,
      nspname as schema
   from shardman.global_tables;

   table_name |  schema
   ------------+----------
   aircrafts  | bookings
   seats      | bookings
   airports   | bookings
   flights    | bookings
   (4 rows)
   

21.2.1.2. Отображение списка сегментированная таблиц #

Для получения сведений обо всех сегментированных таблицах в кластере выполните запрос к представлению shardman.sharded_tables как показано ниже:

   postgres=# select
    relname as table_name,
    nparts  as partitions,
    colocated_with::oid::regclass::text as colocated_with,
    nspname as schema
from shardman.sharded_tables;

   table_name    | partitions | colocated_with |  schema
-----------------+------------+----------------+----------
 bookings        |          4 |                | bookings
 ticket_flights  |          4 | bookings       | bookings
 tickets         |          4 | bookings       | bookings
 boarding_passes |          4 | bookings       | bookings
(4 rows)
   

21.2.1.3. Отображение списка управляемых последовательностей #

Для вывода всех управляемых последовательностей в кластере используйте представление shardman.sequence:

   postgres=# select
    seqns   as schema,
    seqname as sequence_name,
    seqmin  as min_value,
    seqmax  as max_value,
    seqblk  as bulk_size
from shardman.sequence;

  schema  |      sequence_name      | min_value |      max_value      | bulk_size
----------+-------------------------+-----------+---------------------+-----------
 bookings | flights_flight_id_seq   |    262145 | 9223372036854775807 |     65536
(1 rows)
   

21.2.1.4. Вычисление номера сегмента по ключу сегментирования #

Для вывода имени секции, содержащей данные и имя группы репликации вызовите функцию shardman.get_partition_for_value(). Например, пусть book_ref = 0369E5:

   postgres=# select * from shardman.get_partition_for_value(
               'bookings'::regclass,
               '0369E5'::character(6));

   local_nspname | local_relname | remote_nspname | remote_relname
   --------------+---------------+----------------+----------------
   bookings      | bookings_0    | bookings       | bookings_0
   

Этот вывод показывает, что данные в секции bookings_0 таблицы bookings расположены в том же узле, в котором выполнялся запрос.

Выполните запрос, показывающий имя сервера, где находится секция с данными. Если подключиться к серверу, содержащему искомую секцию, то в выводе имени сервера будет написано «current server» (текущий сервер). Если данные расположены на другом сервере, показывается имя узла мастера сегмента:

 SELECT coalesce(r.id, pg_catalog.current_setting('shardman.rgid')::int) as rgid,
         local_relname AS partition_name,
         CASE
            WHEN r.srvid IS NULL THEN 'current server'
            ELSE (SELECT (SELECT split_part(kv, '=', 2)
                           FROM (SELECT unnest(fs.srvoptions) as kv) x
                           WHERE split_part(kv, '=', 1) = 'host')
                  FROM shardman.repgroups rg
                           JOIN pg_catalog.pg_foreign_server AS fs ON fs.oid = rg.srvid
                  WHERE rg.srvid = p.serverid)
            END       AS server_name
   FROM shardman.get_partition_for_value('bookings'::regclass, '0369E5'::character(6)) p
         LEFT JOIN shardman.repgroups AS r ON
      r.srvid = p.serverid;

   rgid | partition_name |  server_name
   -----+----------------+----------------
      1 | bookings_0     | current server
   (1 row)
   

При выполнении запроса с другим ключом сегментирования — 0369E6 — результат будет таким:

   rgid | partition_name |  server_name
   -----+----------------+----------------
      4 | bookings_3_fdw | node4
   (1 row)
   

Видно, что секция находится на узле node4.

Также обратите внимание, что параметр shardman.rgid позволяет вам найти номер узла с сеансом подключения. Для этого выполните следующий запрос:

   SELECT pg_catalog.current_setting('shardman.rgid');
   

Это значение можно использовать для определения расположения секций в подобных запросах.

Функция shardman.get_partition_for_value() в основном предназначена для административных целей и лучшего понимания топологии данных.

Как правило, административные функции не следует использовать при написании SQL-кода для доступа к данным.

21.2.1.5. Расположение секций сегментированных таблиц по сегментам #

Список всех сегментированных таблиц в схеме bookings, количество их секций и распределение по серверам (сегментам) можно получить из метаданных Postgres Pro Shardman на любом узле кластера.

Рассмотрим следующий запрос:

   SELECT p.rel::regclass::text AS table_name,
      p.pnum,
      p.rgid,
      r.srvid,
      fs.srvname
FROM shardman.parts p
JOIN shardman.repgroups r
  ON p.rgid = r.id
LEFT OUTER JOIN pg_foreign_server fs
             ON r.srvid = fs.oid;
   

Чтобы выяснить как распределены данные, объедините этот запрос с подзапросом из Раздел 21.2.1.4:

   SELECT p.rel::regclass AS table_name,
      st.nparts AS total_parts,
      p.pnum AS num_part,
      CASE
         WHEN r.srvid IS NULL THEN 'connected server'
      ELSE
       (SELECT split_part(kv, '=', 2)
       FROM (SELECT unnest(fs.srvoptions) AS kv) x
       WHERE split_part(kv, '=', 1) = 'host')
       END AS server_name
FROM shardman.parts p
       JOIN shardman.repgroups r
         ON p.rgid = r.id
       LEFT JOIN shardman.sharded_tables st
              ON p.rel = st.rel
       LEFT JOIN pg_foreign_server fs
              ON r.srvid = fs.oid
WHERE st.nspname = 'bookings'
ORDER BY table_name, num_part, server_name;
   

Формат вывода результата: имя таблицы, количество секций в таблице, номер секции и имя сервера:

        table_name        | total_parts | num_part |   server_name
--------------------------+-------------+----------+------------------
 bookings.bookings        |           4 |        0 | connected server
 bookings.bookings        |           4 |        1 | node2
 bookings.bookings        |           4 |        2 | node3
 bookings.bookings        |           4 |        3 | node4
 bookings.ticket_flights  |           4 |        0 | connected server
 bookings.ticket_flights  |           4 |        1 | node2
 bookings.ticket_flights  |           4 |        2 | node3
 bookings.ticket_flights  |           4 |        3 | node4
 bookings.tickets         |           4 |        0 | connected server
 bookings.tickets         |           4 |        1 | node2
 bookings.tickets         |           4 |        2 | node3
 bookings.tickets         |           4 |        3 | node4
 bookings.boarding_passes |           4 |        0 | connected server
 bookings.boarding_passes |           4 |        1 | node2
 bookings.boarding_passes |           4 |        2 | node3
 bookings.boarding_passes |           4 |        3 | node4

21.2.1.6. Сбор статистики #

Для сбора статистики по сегментированным и реплицированным таблицам вызовите функцию shardman.global_analyze(). Сначала эта функция выполняет сбор статистики для всех локальных секций распределённых таблиц на каждом узле, а затем транслирует эту статистику на другие узлы. Для реплицированной таблицы будет выполнен сбор статистики на одном выбранном узле, после чего собранная статистика транслируется на все остальные узлы кластера.

21.2. Connecting and Working with a Postgres Pro Shardman Cluster #

The cluster considered consists of four shards. This is how the data partitions of the main sharded table are distributed across shards.

For the ticket_no sharding key:

  • tickets_0 — shard-1 (cluster node node1)

  • tickets_1 — shard-2 (cluster node node2)

  • tickets_2 — shard-3 (cluster node node3)

  • tickets_3 — shard-4 (cluster node node4)

For the book_ref sharding key:

  • bookings_0 — shard-1 (cluster node node1)

  • bookings_1 — shard-2 (cluster node node2)

  • bookings_2 — shard-3 (cluster node node3)

  • bookings_3 — shard-4 (cluster node node4)

The examples below are provided for the book_ref sharding key, but the code in the subsections is suitable for the ticket_no sharding key.

Do not treat this code as optimal or use it in a production environment. It only shows how to implement creation of a connection pull to work with a Postgres Pro Shardman cluster.

What is common for all the examples is the cluster connection string, which must contain node names, TCP port numbers, user name and password, database name for connection and a set of session parameters.

You can get this string using the shardmanctl utility. In the simplest case, the string looks like this:

   $ shardmanctl getconnstr

   dbname=postgres host=node1,node2,node3,node4 port=5432,5432,5432,5432
   

You can get this string to connect to cluster nodes or to create the connection pool in applications.

21.2.1. SQL #

A few convenient functions and views are implemented in Postgres Pro Shardman that add cluster observability by:

  • Listing replicated tables

  • Listing sharded tables

  • Listing managed sequences

  • Finding the shard number from the value of the sharding key

  • Perfroming ANALYZE for all the managed tables in the cluster

21.2.1.1. Listing replicated tables #

To display all replicated tables in the cluster, use the shardman.global_tables view:

   postgres=# select
      relname as table_name,
      nspname as schema
   from shardman.global_tables;

   table_name |  schema
   ------------+----------
   aircrafts  | bookings
   seats      | bookings
   airports   | bookings
   flights    | bookings
   (4 rows)
   

21.2.1.2. Listing Sharded Tables #

To display information on all the sharded tables in the cluster, query the shardman.sharded_tables view as follows:

   postgres=# select
      relname as table_name,
      nparts  as partitions,
      colocated_with::oid::regclass::text as colocated_with,
      nspname as schema
   from shardman.sharded_tables;

      table_name    | partitions | colocated_with |  schema
   -----------------+------------+----------------+----------
   bookings        |          4 |                | bookings
   ticket_flights  |          4 | bookings       | bookings
   tickets         |          4 | bookings       | bookings
   boarding_passes |          4 | bookings       | bookings
   (4 rows)
   

21.2.1.3. Listing Managed Sequences #

To display all the managed sequences in the cluster, use the shardman.sequence view:

   postgres=# select
      seqns   as schema,
      seqname as sequence_name,
      seqmin  as min_value,
      seqmax  as max_value,
      seqblk  as bulk_size
   from shardman.sequence;

   schema  |      sequence_name      | min_value |      max_value      | bulk_size
   ----------+-------------------------+-----------+---------------------+-----------
   bookings | flights_flight_id_seq   |    262145 | 9223372036854775807 |     65536
   (1 rows)
   

21.2.1.4. Finding the Shard Number from the Sharding Key Value #

To display the name of the partition that contains data and the replication group name, call the shardman.get_partition_for_value() function. For example, for book_ref = 0369E5:

   postgres=# select * from shardman.get_partition_for_value(
               'bookings'::regclass,
               '0369E5'::character(6));

   local_nspname | local_relname | remote_nspname | remote_relname
   --------------+---------------+----------------+----------------
   bookings      | bookings_0    | bookings       | bookings_0
   

This output shows that the data is in the bookings_0 partition of the bookings table and is located on the node where the query was executed.

Let's create a query to display the name of the server where the partition with data is located. If we connect to the server that contains the partition, the server name is displayed as “current server”. If the data is on a different server, the hostname of the shard master is displayed:

 SELECT coalesce(r.id, pg_catalog.current_setting('shardman.rgid')::int) as rgid,
         local_relname AS partition_name,
         CASE
            WHEN r.srvid IS NULL THEN 'current server'
            ELSE (SELECT (SELECT split_part(kv, '=', 2)
                           FROM (SELECT unnest(fs.srvoptions) as kv) x
                           WHERE split_part(kv, '=', 1) = 'host')
                  FROM shardman.repgroups rg
                           JOIN pg_catalog.pg_foreign_server AS fs ON fs.oid = rg.srvid
                  WHERE rg.srvid = p.serverid)
            END       AS server_name
   FROM shardman.get_partition_for_value('bookings'::regclass, '0369E5'::character(6)) p
         LEFT JOIN shardman.repgroups AS r ON
      r.srvid = p.serverid;

   rgid | partition_name |  server_name
   -----+----------------+----------------
      1 | bookings_0     | current server
   (1 row)
   

Execution of this query with another value of the sharding key, 0369E6, produces the output:

   rgid | partition_name |  server_name
   -----+----------------+----------------
      4 | bookings_3_fdw | node4
   (1 row)
   

It is clear that the partition is on the node4 node.

Also note that the shardman.rgid parameter allows you to find the number of the node with the connection session. To do this, execute the query:

   SELECT pg_catalog.current_setting('shardman.rgid');
   

You can use this value to determine the location of connection sessions for queries like discussed in this section.

The shardman.get_partition_for_value() is mainly designed for administration purposes, to better understand the data topology.

As a rule, do not use administration functions when writing SQL code for data access.

21.2.1.5. Understanding How Partitions of Sharded Tables Are Distributed Across Shards #

You can get the list of all sharded tables in the bookings schema, together with the number of partitions and their distribution across servers (shards) from Postgres Pro Shardman metadata on any cluster node.

Consider the following query:

   SELECT p.rel::regclass::text AS table_name,
         p.pnum,
         p.rgid,
         r.srvid,
         fs.srvname
   FROM shardman.parts p
   JOIN shardman.repgroups r
   ON p.rgid = r.id
   LEFT OUTER JOIN pg_foreign_server fs
               ON r.srvid = fs.oid;
   

To learn how the data is distributed, let's combine this query with a subquery from Section 21.2.1.4:

   SELECT p.rel::regclass AS table_name,
         st.nparts AS total_parts,
         p.pnum AS num_part,
         CASE
            WHEN r.srvid IS NULL THEN 'connected server'
         ELSE
         (SELECT split_part(kv, '=', 2)
         FROM (SELECT unnest(fs.srvoptions) AS kv) x
         WHERE split_part(kv, '=', 1) = 'host')
         END AS server_name
   FROM shardman.parts p
         JOIN shardman.repgroups r
            ON p.rgid = r.id
         LEFT JOIN shardman.sharded_tables st
               ON p.rel = st.rel
         LEFT JOIN pg_foreign_server fs
               ON r.srvid = fs.oid
   WHERE st.nspname = 'bookings'
   ORDER BY table_name, num_part, server_name;
   

The output format is the table name, number of table partitions, partition number and server name:

         table_name        | total_parts | num_part |   server_name
   --------------------------+-------------+----------+------------------
   bookings.bookings        |           4 |        0 | connected server
   bookings.bookings        |           4 |        1 | node2
   bookings.bookings        |           4 |        2 | node3
   bookings.bookings        |           4 |        3 | node4
   bookings.ticket_flights  |           4 |        0 | connected server
   bookings.ticket_flights  |           4 |        1 | node2
   bookings.ticket_flights  |           4 |        2 | node3
   bookings.ticket_flights  |           4 |        3 | node4
   bookings.tickets         |           4 |        0 | connected server
   bookings.tickets         |           4 |        1 | node2
   bookings.tickets         |           4 |        2 | node3
   bookings.tickets         |           4 |        3 | node4
   bookings.boarding_passes |           4 |        0 | connected server
   bookings.boarding_passes |           4 |        1 | node2
   bookings.boarding_passes |           4 |        2 | node3
   bookings.boarding_passes |           4 |        3 | node4
   

21.2.1.6. Collecting Statistics #

To collect statistics for sharded and replicated tables, call the shardman.global_analyze() function. This function first collects statistics for all local partitions of sharded tables on each node and then broadcasts this statistics to other nodes. For a replicated table, the function first collects statistics on a certain node and then the statistics is broadcast to all the other nodes.

FAQ