分布式 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”，是默认的再平衡策略。
默认策略适用于以下情况：
- 分片的大小大致相同
- 分片获得大致相同数量的流量
- Worker 节点大小/类型相同
- 分片尚未固定到特定 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， 但适用于所有节点并确保还原点在它们之间保持一致。此功能非常适合进行时间点恢复和集群分叉。