分布式 PostgreSQL，Citus(11.x) 效用函数

目录

• 表和分片 DDL
• create_distributed_table
• truncate_local_data_after_distributing_table
• undistribute_table
• alter_distributed_table
• alter_table_set_access_method
• remove_local_tables_from_metadata
• create_reference_table
• mark_tables_colocated
• update_distributed_table_colocation
• create_distributed_function
• alter_columnar_table_set
• create_time_partitions
• drop_old_time_partitions
• alter_old_partitions_set_access_method
• 元数据/配置信息
• citus_add_node
• citus_update_node
• citus_set_node_property
• citus_add_inactive_node
• citus_activate_node
• citus_disable_node
• citus_add_secondary_node
• citus_remove_node
• citus_get_active_worker_nodes
• citus_backend_gpid
• citus_check_cluster_node_health (beta)
• citus_set_coordinator_host
• master_get_table_metadata
• get_shard_id_for_distribution_column
• column_to_column_name
• citus_relation_size
• citus_table_size
• citus_total_relation_size
• citus_stat_statements_reset
• 集群管理与修复函数
• citus_move_shard_placement
• rebalance_table_shards
• get_rebalance_table_shards_plan
• get_rebalance_progress
• citus_add_rebalance_strategy
• citus_set_default_rebalance_strategy
• citus_remote_connection_stats
• citus_drain_node
• isolate_tenant_to_new_shard
• citus_create_restore_point
• 更多

本文包含 Citus 提供的用户定义函数的参考信息。这些函数有助于为 Citus 提供除标准 SQL 命令之外的其他分布式功能。

表和分片 DDL

create_distributed_table

create_distributed_table() 函数用于定义分布式表，并且如果它是哈希分布式表，还用于创建它的分片。此函数采用表名称、分布列和可选的分发方法，并插入适当的元数据以将表标记为分布式。如果未指定分布方法，则函数默认为“哈希”分布。如果表是哈希分布式，则该函数还基于分片计数和分片复制因子配置值创建 worker 分片。如果表包含任何行，会将这些行自动分布到 worker 节点。

truncate_local_data_after_distributing_table

在分发表后截断所有本地行，并防止因本地记录过时而导致约束失败。截断操作将级联到对指定表具有外键的表中。如果引用表本身不是分布式的，则在这些表是分布式的表之前禁止截断，以保护引用完整性：

ERROR:  cannot truncate a table referenced in a foreign key constraint by a local table

截断本地协调器(coordinator)节点表数据对于分布式表是安全的，因为它们的行（如果有）将在分发过程中复制到 worker 节点。

undistribute_table

undistribute_table() 函数撤消 create_distributed_table 或 create_reference_table 的操作。取消分发会将所有数据从分片移回 coordinator 节点上的本地表（假设数据可以容纳），然后删除分片。

Citus 不会取消分发具有外键或被外键引用的表，除非 cascade_via_foreign_keys 参数设置为 true。如果此参数为 false（或省略），则必须在取消分发之前手动删除有问题的外键约束。

alter_distributed_table

alter_distributed_table() 函数可用于更改分布式表的“分布列”、“分片计数”或“并置”属性。

alter_table_set_access_method

alter_table_set_access_method() 函数更改表的访问方法（例如 heap 或 columnar）。

remove_local_tables_from_metadata

remove_local_tables_from_metadata() 函数从 Citus 的元数据中删除不再需要的本地表。

通常如果本地表在 Citus 的元数据中，是有原因的，例如表和引用表之间存在外键。但是，如果 enable_local_reference_foreign_keys 被禁用，Citus 在这种情况下将不再管理元数据， 并且不必要的元数据可能会持续存在，直到手动清理。

create_reference_table

create_reference_table() 函数用于定义小型引用表或维度表。此函数采用表名称，创建一个只包含一个分片的分布式表，并将其复制到每个 worker 节点。

mark_tables_colocated

mark_tables_colocated() 函数采用分布式表（源）和其他列表（目标），并将目标放入与源相同的共置组中。如果源尚未在组中，则此函数创建一个，并将源和目标分配给它。

通常应该在表分发时通过 create_distributed_table 的 colocate_with 参数来完成表的共置。但是如果需要， mark_tables_colocated 可以处理它。

如果要中断表的共置，可以使用 update_distributed_table_colocation。

update_distributed_table_colocation

update_distributed_table_colocation() 函数用于更新分布式表的并置。此函数也可用于中断分布式表的并置。如果分布列为同一类型，则 Citus 将隐式并置两个表，如果这些表是相关的并且将执行一些联接，则这会很有用。如果并置了表 A 和 B，且表 A 获得重新平衡，则表 B 也将进行重新平衡。如果表 B 没有副本标识，则重新平衡将会失败。因此，在这种情况下，此函数可用于中断隐式并置。

此函数不会在物理上移动任何数据。

create_distributed_function

将函数从 coordinator 节点传播到 worker，并将其标记为分布式执行。在 coordinator 上调用分布式函数时，Citus 使用“分布参数”的值选取 worker 节点来运行该函数。在 worker 上执行函数会增加并行度，并可以使代码更接近分片中的数据，以降低延迟。

在分布式函数执行期间，Postgres 搜索路径不会从 coordinator 传播到 worker， 因此分布式函数代码应完全限定数据库对象的名称。函数发出的通知也不会显示给用户。

alter_columnar_table_set

alter_columnar_table_set() 函数用于更改 columnar table 的设置，对非纵栏(non-columnar)表调用此函数会发生错误。表名以外的所有参数都是可选项。

若要查看所有纵栏(columnar)表的当前选项，请参阅下表：

SELECT * FROM columnar.options;

对于新创建的表，其纵栏设置默认值可通过下列 GUC 来替代：

• columnar.compression
• columnar.compression_level
• columnar.stripe_row_count
• columnar.chunk_row_count

create_time_partitions

create_time_partitions() 函数创建给定间隔的分区以涵盖给定的时间范围。

drop_old_time_partitions

drop_old_time_partitions() 函数删除其间隔在给定时间戳之前的所有分区。除了使用此函数之外，你还可以考虑使用 alter_old_partitions_set_access_method 通过纵栏存储来压缩旧分区。

alter_old_partitions_set_access_method

在 时间序列数据 用例中，表通常按时间分区，旧分区被压缩为只读纵栏存储。

元数据/配置信息

citus_add_node

此函数需要数据库 superuser 访问权限才能运行。

citus_add_node() 函数在 Citus 元数据表 pg_dist_node 中注册集群中的新节点添加。它还将引用表复制到新节点。

如果在单节点集群上运行 citus_add_node，请务必先运行 citus_set_coordinator_host。

citus_update_node

此函数需要数据库 superuser 访问权限才能运行。

citus_update_node() 函数更改在 Citus 元数据表 pg_dist_node 中注册的节点的主机名和端口。

citus_set_node_property

citus_set_node_property() 函数更改 Citus 元数据表 pg_dist_node 中的属性。目前它只能更改 shouldhaveshards 属性。

citus_add_inactive_node

此函数需要数据库 superuser 访问权限才能运行。

citus_add_inactive_node 函数，类似于 citus_add_node， 在 pg_dist_node 中注册一个新节点。但是，它将新节点标记为非活动节点，这意味着不会将分片放置在那里。它也 不 会将引用表复制到新节点。

citus_activate_node

此函数需要数据库 superuser 访问权限才能运行。

citus_activate_node 函数在 Citus 元数据表 pg_dist_node 中将节点标记为活动的，并将引用表复制到该节点。对于通过 citus_add_inactive_node 添加的节点很有用。

citus_disable_node

此函数需要数据库 superuser 访问权限才能运行。

citus_disable_node 函数与 citus_activate_node 相反。它在 Citus 元数据表 pg_dist_node 中将节点标记为非活动节点，暂时将其从集群中删除。该函数还从禁用节点中删除所有引用表放置。要重新激活节点，只需再次运行 citus_activate_node。

citus_add_secondary_node

此函数需要数据库 superuser 访问权限才能运行。

citus_add_secondary_node() 函数在集群中为现有的主节点注册一个新的辅助节点。它更新 Citus 元数据表 pg_dist_node。

citus_remove_node

此函数需要数据库 superuser 访问权限才能运行。

citus_remove_node() 函数从 pg_dist_node 元数据表中删除指定的节点。如果此节点上有现有的分片放置，此函数将出错。因此，在使用此功能之前，需要将分片移出该节点。

citus_get_active_worker_nodes

citus_get_active_worker_nodes() 函数返回活动的 worker 主机名称和端口号的列表。

citus_backend_gpid

citus_backend_gpid() 函数返回为当前会话提供服务的 PostgreSQL 后端的全局进程标识符 (GPID)。GPID 对 Citus 集群中的一个节点以及该节点上 PostgreSQL 的操作系统进程 ID 进行编码。

Citus 扩展了 PostgreSQL 服务器信号函数 pg_cancel_backend() 和 pg_terminate_backend() 以便它们接受 GPID。在 Citus 中，在一个节点上调用这些函数会影响在另一个节点上运行的后端。

citus_check_cluster_node_health (beta)

这个函数是 Citus 11-beta 的一部分。

检查所有节点之间的连接。如果有 N 个节点，则该函数检查它们之间的所有 N2 个连接。

citus_set_coordinator_host

将 worker 节点添加到最初创建为 single-node cluster 的 Citus 集群时需要此功能。当 coordinator 注册一个新的 worker 时，它会从 citus.local_hostname (text) 的值中添加一个 coordinator 主机名， 默认情况下是 localhost。worker 会尝试连接到 localhost 以与 coordinator 通讯，这显然是错误的。

因此，在单节点集群中，系统管理员应该在调用 citus_add_node 之前调用 citus_set_coordinator_host。

master_get_table_metadata

master_get_table_metadata() 函数可用于返回分布式表的分布相关元数据。此元数据包括关系 id、存储类型、分配方法、分配列、复制计数（不推荐）、最大分片大小和该表的分片放置策略。在幕后，此函数查询 Citus 元数据表以获取所需信息并将其连接成一个元组，然后再将其返回给用户。

get_shard_id_for_distribution_column

Citus 根据行的分布列的值和表的分布方法，将分布式表的每一行分布给分片。在大多数情况下，精确映射是数据库管理员可忽略的低级别详细信息。然而，无论是对于手动数据库维护任务，还是仅仅为了满足好奇心，确定行的分片会很有用。get_shard_id_for_distribution_column 函数为哈希分布表和引用表提供此信息。

column_to_column_name

将 pg_dist_partition 的 partkey 列转换为文本列名称。该转换可用于确定分布式表的分布列。

有关更详细的讨论，请参阅 finding_dist_col。

citus_relation_size

获取指定的分布式表的所有分片所使用的磁盘空间。磁盘空间包括“主分支”的大小，但不包括分片的可见性映射和可用空间映射。

citus_table_size

获取指定的分布式表的所有分片所使用的磁盘空间，不包括索引（但包括 TOAST、可用空间映射和可见性映射）。

citus_total_relation_size

获取指定的分布式表的所有分片使用的总磁盘空间，包括所有索引和 TOAST 数据。

citus_stat_statements_reset

从 citus_stat_statements 中移除所有行。此函数独立于 pg_stat_statements_reset() 使用。如果要重置所有统计信息，请调用这两个函数。

集群管理与修复函数

citus_move_shard_placement

此函数将给定的分片（以及与其并置的分片）从一个节点移动到另一个节点。它通常在分片重新平衡期间间接使用，而不是由数据库管理员直接调用。

移动数据有两种方式：阻塞或非阻塞。阻塞方法意味着在移动过程中对分片的所有修改都被暂停。第二种避免阻塞分片写入的方法依赖于 Postgres 10 逻辑复制。

成功移动操作后，源节点中的分片将被删除。如果移动在任何时候失败，此函数将引发错误并保持源节点和目标节点不变。

rebalance_table_shards

rebalance_table_shards() 函数将移动给定表的分片，以在 worker 之间平均分配这些分片。函数首先计算需要执行移动的列表，以确保服务器组在给定的阈值内平衡。然后，它将分片放置逐个从源节点移动到目标节点，并更新相应的分片元数据以反映移动情况。

在确定分片是否“均匀分布”时，系统会向每个分片分配成本。默认情况下，每个分片的成本都相同（数值为 1），因此 worker 之间的成本均等化分布就表示分片数量也是均等化分布。固定成本策略称为 “by_shard_count”，是默认的再平衡策略。

默认策略适用于以下情况：

1. 分片的大小大致相同
2. 分片获得大致相同数量的流量
3. Worker 节点大小/类型相同
4. 分片尚未固定到特定 worker

如果其中任何一个假设不成立，则默认再平衡可能会导致计划不佳。在这种情况下，可以使用 rebalance_strategy 参数自定义策略。

建议在运行 rebalance_table_shards 之前调用 get_rebalance_table_shards_plan，以查看和验证要执行的操作。

get_rebalance_table_shards_plan

输出 rebalance_table_shards 的计划分片移动，而不执行该移动。虽然不太可能，但使用相同参数的 rebalance_table_shards 调用会输出一个计划，get_rebalance_table_shards_plan 输出的计划与以上这个计划稍有不同。它们不会同时执行，因此服务器组（例如，磁盘空间）可能会因调用而异。

get_rebalance_progress

分片再平衡开始后，该 get_rebalance_progress() 函数将列出所涉及的每个分片的进度。它将监视由 rebalance_table_shards() 计划和执行的移动。

citus_add_rebalance_strategy

向 pg_dist_rebalance_strategy 追加行。

citus_set_default_rebalance_strategy

更新 Rebalancer strategy table 表，将其参数命名的策略更改为在再平衡分片时选择的默认策略。

citus_remote_connection_stats

citus_remote_connection_stats() 函数显示每个远程节点的活动连接数。

citus_drain_node

citus_drain_node() 函数将分片从指定节点移到其他节点上，这些节点在 Worker node table 中将 shouldhaveshards 设置为 true。此函数旨在在从集群中删除节点之前调用，即关闭节点的物理服务器。

isolate_tenant_to_new_shard

此函数将创建新的分片，用于保存分布列中具有特定单个值的行。这对于多租户 (Citus) 用例特别有用，其中，大型租户可单独放置在其自己的分片上，并最终位于其自身的物理节点上。

citus_create_restore_point

临时阻止对集群的写入，并在所有节点上创建命名还原点。此函数类似于 pg_create_restore_point， 但适用于所有节点并确保还原点在它们之间保持一致。此功能非常适合进行时间点恢复和集群分叉。