Fonctions Azure Cosmos DB for PostgreSQL

Article
11/14/2023

S’APPLIQUE À : Azure Cosmos DB for PostgreSQL (avec l’extension de base de données Citus pour PostgreSQL)

Cette section contient des informations de référence pour les fonctions définies par Azure Cosmos DB for PostgreSQL. Ces fonctions aident à fournir des fonctionnalités distribuées à Azure Cosmos DB for PostgreSQL.

Remarque

Il se pourrait que des clusters exécutant des versions antérieures du Citus Engine ne proposent pas toutes les fonctions répertoriées sur cette page.

Table et DDL de partition

citus_schema_distribute

Convertit les schémas standard existants en schémas distribués. Les schémas distribués sont automatiquement associés avec des groupes de colocalisation individuels. Les tables créées dans ces schémas sont converties en tables distribuées colocalisées sans clé de partition. Le processus de distribution du schéma attribue et transfère automatiquement le schéma vers un nœud existant dans le cluster.

Arguments

schemaname : nom du schéma, qui doit être distribué.

Valeur retournée

N/A

Exemple

SELECT citus_schema_distribute('tenant_a');
SELECT citus_schema_distribute('tenant_b');
SELECT citus_schema_distribute('tenant_c');

Pour plus d’exemples, consultez la procédure de conception pour les microservices.

citus_schema_undistribute

Convertit un schéma distribué existant en schéma standard. Le processus entraîne le transfert des tables et des données du nœud actuel vers le nœud coordinateur du cluster.

Arguments

schemaname : nom du schéma, qui doit être distribué.

Valeur retournée

N/A

Exemple

SELECT citus_schema_undistribute('tenant_a');
SELECT citus_schema_undistribute('tenant_b');
SELECT citus_schema_undistribute('tenant_c');

Pour plus d’exemples, consultez la procédure de conception pour les microservices.

create_distributed_table

La fonction create_distributed_table() permet de définir une table distribuée et de créer ses partitions s’il s’agit d’une table distribuée par hachage. Cette fonction accepte un nom de table, la colonne de distribution et une méthode de distribution facultative, et insère les métadonnées appropriées pour marquer la table comme distribuée. La fonction prend par défaut la valeur de distribution « hash » si aucune méthode de distribution n’est spécifiée. Si la table est distribuée par hachage, la fonction crée également des partitions de travail en fonction des valeurs de configuration du nombre de partitions et du facteur de réplication de partition. Si la table contient des lignes, elles sont automatiquement distribuées aux nœuds Worker.

Cette fonction remplace l’utilisation de master_create_distributed_table(), suivie de master_create_worker_shards().

Arguments

table_name : Nom de la table qui doit être distribuée.

distribution_column : Colonne sur laquelle la table doit être distribuée.

distribution_type : (Facultatif) Méthode selon laquelle la table doit être distribuée. Les valeurs autorisées sont append ou hash, avec « hash » comme valeur par défaut.

colocate_with : (Facultatif) Inclure la table actuelle dans le groupe de colocation d’une autre table. Par défaut, les tables sont colocalisées lorsqu’elles sont distribuées par colonnes du même type, ont le même nombre de partitions et ont le même facteur de réplication. Les valeurs possibles pour colocate_with sont default, none pour démarrer un nouveau groupe de colocation, ou le nom d’une autre table à mettre en colocation avec cette table. (See colocation de table.)

Gardez à l’esprit que la valeur par défaut de colocate_with effectue une colocation implicite. La colocation peut être une bonne chose lorsque les tables sont liées ou jointes. Toutefois, lorsque deux tables ne sont pas liées, mais qu’elles utilisent le même type de données pour leurs colonnes de distribution, les mettre en colocation par inadvertance peut réduire les performances lors du rééquilibrage de partition. Les partitions de table sont déplacées ensemble inutilement en « cascade ».

Si une nouvelle table distribuée n’est pas associée à d’autres tables, il est préférable de spécifier colocate_with => 'none'.

shard_count : (Facultatif) nombre de partitions à créer pour la nouvelle table distribuée. Lorsque vous spécifiez shard_count, vous ne pouvez pas spécifier une valeur de colocate_with autre que « aucune ». Pour modifier le nombre de partitions d’une table ou d’un groupe de colocalisation existant, utilisez la fonction alter_distributed_table.

Les valeurs possibles sont comprisesshard_count entre 1 et 64000. Pour obtenir des conseils sur le choix de la valeur optimale, consultez Nombre de partitions.

Valeur retournée

N/A

Exemple

Cet exemple indique à la base de données que la table github_events doit être distribuée par hachage sur la colonne repo_id.

SELECT create_distributed_table('github_events', 'repo_id');

-- alternatively, to be more explicit:
SELECT create_distributed_table('github_events', 'repo_id',
                                colocate_with => 'github_repo');

create_distributed_table_concurrently

Cette fonction a la même interface et le même objectif que create_distributed_function, mais ne bloque pas les écritures pendant la distribution de table.

Toutefois, create_distributed_table_concurrently présente quelques limitations :

Vous ne pouvez pas utiliser la fonction dans un bloc de transactions, ce qui signifie que vous ne pouvez distribuer qu’une seule table à la fois. (Vous pouvez toutefois utiliser la fonction sur des tables partitionnée dans le temps.)
Vous ne pouvez pas utiliser create_distributed_table_concurrently lorsque la table est référencée par une clé étrangère ou fait référence à une autre table locale. Toutefois, les clés étrangères pour référencer des tables fonctionnent, et vous pouvez créer des clés étrangères pour d’autres tables distribuées une fois la distribution de table terminée.
Si vous n’avez pas de clé primaire ou d’identité de réplica sur votre table, les commandes de mise à jour et de suppression échouent pendant la distribution de la table en raison de limitations sur la réplication logique.

truncate_local_data_after_distributing_table

Tronque toutes les lignes locales après la distribution d’une table et empêche les contraintes d’échouer en raison d’enregistrements locaux obsolètes. La troncation se répercute sur les tables ayant une clé étrangère vers la table désignée. Si les tables de référence ne sont pas elles-mêmes distribuées, la troncation est interdite tant qu’elles ne le sont pas afin de protéger l’intégrité référentielle :

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

La troncation des données de la table du nœud coordinateur local est sans danger pour les tables distribuées, car leurs lignes, le cas échéant, sont copiées sur les nœuds Worker durant la distribution.

Arguments

table_name : nom de la table distribuée dont l’équivalent local sur le nœud coordinateur doit être tronqué.

Valeur retournée

N/A

Exemple

-- requires that argument is a distributed table
SELECT truncate_local_data_after_distributing_table('public.github_events');

create_reference_table

La fonction create_reference_table() est utilisée pour définir une petite référence ou une table de dimension. Cette fonction accepte un nom de table et crée une table distribuée avec une seule partition, répliquée sur chaque nœud Worker.

Arguments

table_name : Nom de la petite dimension ou de la table de référence qui doit être distribuée.

Valeur retournée

N/A

Exemple

Cet exemple indique à la base de données que la table nation doit être définie comme table de référence.

SELECT create_reference_table('nation');

citus_add_local_table_to_metadata

Ajoute une table Postgres locale dans les métadonnées Citus. Un cas d’usage majeur pour cette fonction consiste à rendre les tables locales sur le nœud coordinateur accessibles à partir de n’importe quel nœud du cluster. Les données associées à la table locale restent sur le nœud coordinateur : seuls son schéma et ses métadonnées sont envoyés aux Workers.

L’ajout de tables locales aux métadonnées coûte légèrement cher. Lorsque vous ajoutez la table, Citus doit le suivre dans la table de partition. Les tables locales ajoutées aux métadonnées héritent des mêmes limitations que les tables de référence.

Lorsque vous ne distribuez pas la table, Citus supprime les tables locales résultantes des métadonnées, ce qui élimine ces limitations sur ces tables.

Arguments

table_name : nom de la table sur le nœud coordinateur à ajouter aux métadonnées Citus.

cascade_via_foreign_keys : (facultatif) lorsque cet argument est défini sur « true », citus_add_local_table_to_metadata ajoute automatiquement dans les métadonnées d’autres tables qui se trouvent dans une relation de clé étrangère avec une table donnée. Soyez prudent avec ce paramètre, car il peut affecter de nombreuses tables.

Valeur retournée

N/A

Exemple

Cet exemple informe la base de données que la table nation doit être définie comme une table coordinatrice locale, accessible à partir de n’importe quel nœud :

SELECT citus_add_local_table_to_metadata('nation');

alter_distributed_table

La fonction alter_distributed_table() peut être utilisée pour modifier la colonne de distribution, le nombre de partitions ou les propriétés de colocalisation d’une table distribuée.

Arguments

table_name : nom de la table qui sera modifiée.

distribution_column (facultatif) : nom de la nouvelle colonne de distribution.

shard_count (facultatif) : nombre de nouvelles partitions.

colocate_with (facultatif) : table avec laquelle la table distribuée actuelle sera colocalisée. Les valeurs possibles sont default, none pour démarrer un nouveau groupe de colocalisation, ou le nom d’une autre table avec laquelle établir une colocalisation. (See colocation de table.)

cascade_to_colocated (facultatif) : si cet argument a la valeur « true », les modifications apportées à shard_count et colocate_with sont également appliquées à toutes les tables précédemment colocalisées avec la table, et la colocalisation est conservée. S’il a la valeur « false », la colocalisation actuelle de cette table est rompue.

Valeur retournée

N/A

Exemple

-- change distribution column
SELECT alter_distributed_table('github_events', distribution_column:='event_id');

-- change shard count of all tables in colocation group
SELECT alter_distributed_table('github_events', shard_count:=6, cascade_to_colocated:=true);

-- change colocation
SELECT alter_distributed_table('github_events', colocate_with:='another_table');

update_distributed_table_colocation

La fonction update_distributed_table_colocation() permet de mettre à jour la colocalisation d’une table distribuée. Cette fonction peut également être utilisée pour rompre la colocalisation d’une table distribuée. Azure Cosmos DB for PostgreSQL colocalise implicitement deux tables si la colonne de distribution est du même type, ce qui peut être utile si les tables sont liées et feront des jointures. Si les tables A et B sont colocalisées et que la table A est rééquilibrée, la table B est également rééquilibrée. Si la table B n’a pas d’identité de réplica, le rééquilibrage échoue. Cette fonction peut donc être utile pour rompre la colocalisation implicite dans ce cas.

Cette fonction ne déplace aucune donnée physiquement.

Arguments

table_name : nom de la colocalisation de table à mettre à jour.

colocate_with : table avec laquelle la table doit être colocalisée.

Si vous souhaitez rompre la colocalisation d’une table, vous devez spécifier colocate_with => 'none'.

Valeur retournée

N/A

Exemple

Cet exemple montre que la colocalisation de la table A est mise à jour en tant que colocalisation de la table B.

SELECT update_distributed_table_colocation('A', colocate_with => 'B');

Supposons que les tables A et B soient colocalisées (éventuellement implicitement), si vous souhaitez rompre la colocalisation :

SELECT update_distributed_table_colocation('A', colocate_with => 'none');

Supposons à présent que les tables A, B, C et D soient colocalisées et que vous souhaitiez colocaliser la table A et la table B, et la table C et la table D :

SELECT update_distributed_table_colocation('C', colocate_with => 'none');
SELECT update_distributed_table_colocation('D', colocate_with => 'C');

Si vous avez une table distribuée par hachage nommée none et que vous souhaitez mettre à jour sa colocalisation, vous pouvez effectuer les opérations suivantes :

SELECT update_distributed_table_colocation('"none"', colocate_with => 'some_other_hash_distributed_table');

undistribute_table

La fonction undistribute_table() annule l’action de create_distributed_table ou de create_reference_table. La dédistribution déplace toutes les données des partitions vers une table locale sur le nœud coordinateur (s’il y a assez de place pour les données), puis supprime les partitions.

Azure Cosmos DB for PostgreSQL ne dédistribue pas les tables qui ont des clés étrangères ou qui sont référencées par de telles clés, sauf si l’argument cascade_via_foreign_keys est true. Si cet argument est false (ou s’il est omis), vous devez supprimer manuellement les contraintes de clé étrangère incriminées avant de dédistribuer.

Arguments

table_name : nom de la table distribuée ou de référence à dédistribuer.

cascade_via_foreign_keys (facultatif) : quand cet argument est « true », undistribute_table dédistribue également toutes les tables liées à table_name avec des clés étrangères. Soyez prudent avec ce paramètre, car il peut affecter de nombreuses tables.

Valeur retournée

N/A

Exemple

Cet exemple distribue une table github_events, puis la dédistribue.

-- first distribute the table
SELECT create_distributed_table('github_events', 'repo_id');

-- undo that and make it local again
SELECT undistribute_table('github_events');

create_distributed_function

Propage une fonction du nœud coordinateur aux Workers et la marque pour une exécution distribuée. Lorsqu’une fonction distribuée est appelée sur le coordinateur, Azure Cosmos DB for PostgreSQL utilise la valeur de l’argument de distribution pour choisir un nœud Worker afin d’exécuter la fonction. L’exécution de la fonction sur les Workers augmente le parallélisme et peut rendre le code plus proche des données dans les partitions pour une latence plus faible.

Le chemin de recherche Postgres n’étant pas propagé du coordinateur aux threads de travail pendant l’exécution des fonctions distribuées, le code de la fonction distribuée doit qualifier entièrement les noms des objets de base de données. En outre, les notifications émises par les fonctions ne sont pas affichées à l’utilisateur.

Arguments

function_name : Nom de la fonction à distribuer. Le nom doit inclure les types de paramètres de la fonction entre parenthèses, car plusieurs fonctions peuvent avoir le même nom dans PostgreSQL. Par exemple, 'foo(int)' est différent de 'foo(int, text)'.

distribution_arg_name : (Facultatif) Nom de l’argument par lequel distribuer. Pour des raisons pratiques (ou si les arguments de fonction n’ont pas de nom), un espace réservé positionnel est autorisé, tel que '$1'. Si ce paramètre n’est pas spécifié, la fonction nommée par function_name est simplement créée sur les workers. Si les nœuds Worker sont ajoutés à l’avenir, la fonction sera automatiquement créée.

colocate_with : (Facultatif) Quand la fonction distribuée lit ou écrit dans une table distribuée (ou, plus généralement, un groupe de colocation), veillez à nommer cette table à l’aide du paramètre colocate_with. Ensuite, chaque appel de la fonction s’exécute sur le nœud Worker contenant les partitions pertinentes.

Valeur retournée

N/A

Exemple

-- an example function which updates a hypothetical
-- event_responses table which itself is distributed by event_id
CREATE OR REPLACE FUNCTION
  register_for_event(p_event_id int, p_user_id int)
RETURNS void LANGUAGE plpgsql AS $fn$
BEGIN
  INSERT INTO event_responses VALUES ($1, $2, 'yes')
  ON CONFLICT (event_id, user_id)
  DO UPDATE SET response = EXCLUDED.response;
END;
$fn$;

-- distribute the function to workers, using the p_event_id argument
-- to determine which shard each invocation affects, and explicitly
-- colocating with event_responses which the function updates
SELECT create_distributed_function(
  'register_for_event(int, int)', 'p_event_id',
  colocate_with := 'event_responses'
);

alter_columnar_table_set

La fonction alter_columnar_table_set () modifie les paramètres d’une table en colonnes. L’appel de cette fonction sur une table qui n’est pas en colonnes génère une erreur. Tous les arguments, à l’exception du nom de la table, sont facultatifs.

Pour afficher les options actuelles de toutes les tables en colonnes, consultez le tableau suivant :

SELECT * FROM columnar.options;

Les valeurs par défaut des paramètres de colonnes pour les tables récemment créées peuvent être remplacées par ces GUC :

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

Arguments

table_name : nom de la table en colonnes.

chunk_row_count : (facultatif) nombre maximal de lignes par bloc pour les nouvelles données insérées. Les blocs de données existants ne sont pas modifiés et pourraient avoir plus de lignes que cette valeur maximale. La valeur par défaut est 10 000.

stripe_row_count : (facultatif) nombre maximal de lignes par frange pour les nouvelles données insérées. Les franges de données existantes ne sont pas modifiées et pourraient avoir plus de lignes que cette valeur maximale. La valeur par défaut est 150000.

compression : (facultatif) [none|pglz|zstd|lz4|lz4hc] type de compression pour les données récemment insérées. Les données existantes ne seront pas recompressées ou décompressées. La valeur par défaut et suggérée est zstd (si le support a été compilé).

compression_level : (facultatif) Les paramètres valides sont compris entre 1 et 19. Si la méthode de compression ne prend pas en charge le niveau choisi, le niveau le plus proche est sélectionné à la place.

Valeur retournée

N/A

Exemple

SELECT alter_columnar_table_set(
  'my_columnar_table',
  compression => 'none',
  stripe_row_count => 10000);

alter_table_set_access_method

La fonction alter_table_set_access_method() modifie la méthode d’accès d’une table (par exemple, heap ou columnar).

Arguments

table_name : nom de la table dont la méthode d’accès sera modifiée.

access_method : nom de la nouvelle méthode d’accès.

Valeur retournée

N/A

Exemple

SELECT alter_table_set_access_method('github_events', 'columnar');

create_time_partitions

La fonction create_time_partitions() crée des partitions d’un intervalle donné pour couvrir une plage de temps donnée.

Arguments

table_name (regclass) : table pour laquelle créer des partitions. La table doit être partitionnée sur une colonne, de type date, timestamp ou timestamptz.

partition_interval : intervalle de temps, tel que '2 hours' ou '1 month' à utiliser lors de la définition de plages sur de nouvelles partitions.

end_at (timestamptz) : permet de créer des partitions jusqu’à cet instant. La dernière partition contient le point end_at et aucune partition ultérieure ne sera créée.

start_from (timestamptz, facultatif) : sélectionnez la première partition de telle sorte qu’elle contienne le point start_from. La valeur par défaut est now().

Valeur retournée

True s’il est nécessaire de créer des partitions, false si elles existent déjà.

Exemple

-- create a year's worth of monthly partitions
-- in table foo, starting from the current time

SELECT create_time_partitions(
  table_name         := 'foo',
  partition_interval := '1 month',
  end_at             := now() + '12 months'
);

drop_old_time_partitions

La fonction drop_old_time_partitions() supprime toutes les partitions dont les intervalles sont antérieurs à un timestamp donné. Outre cette fonction, vous pouvez envisager d’utiliser alter_old_partitions_set_access_method pour compresser les anciennes partitions avec un stockage en colonnes.

Arguments

table_name (regclass) : table pour laquelle supprimer des partitions. La table doit être partitionnée sur une colonne, de type date, timestamp ou timestamptz.

older_than (timestamptz) : supprime les partitions dont la plage supérieure est inférieure ou égale à older_than.

Valeur retournée

N/A

Exemple

-- drop partitions that are over a year old

CALL drop_old_time_partitions('foo', now() - interval '12 months');

alter_old_partitions_set_access_method

Dans un cas d’usage de série chronologique, les tables sont souvent partitionnées selon l’heure, et les anciennes partitions sont compressées dans un stockage en colonnes en lecture seule.

Arguments

parent_table_name (regclass) : table pour laquelle modifier des partitions. La table doit être partitionnée sur une colonne, de type date, timestamp ou timestamptz.

older_than (timestamptz) : modifie les partitions dont la plage supérieure est inférieure ou égale à older_than.

new_access_method : (nom) « heap » pour le stockage basé sur des lignes ou « columnar » pour le stockage en colonnes.

Valeur retournée

N/A

Exemple

CALL alter_old_partitions_set_access_method(
  'foo', now() - interval '6 months',
  'columnar'
);

Métadonnées/Informations de configuration

get_shard_id_for_distribution_column

Azure Cosmos DB for PostgreSQL attribue chaque ligne d’une table distribuée à une partition en fonction de la valeur de la colonne de distribution de la ligne et de la méthode de distribution de la table. Dans la plupart des cas, le mappage précis est un détail de bas niveau que l’administrateur de base de données peut ignorer. Toutefois, il peut être utile de déterminer la partition d’une ligne, que ce soit pour des tâches de maintenance de base de données manuelles ou simplement par curiosite. La fonction get_shard_id_for_distribution_column fournit ces informations pour les tables de référence, distribuées par hachage et par plage. Elle ne fonctionne pas pour la distribution append.

Arguments

table_name : Table distribuée.

distribution_value : Valeur de la colonne de distribution.

Valeur retournée

L’ID de partition Azure Cosmos DB for PostgreSQL s’associe à la valeur de la colonne de distribution pour la table donnée.

Exemple

SELECT get_shard_id_for_distribution_column('my_table', 4);

 get_shard_id_for_distribution_column
--------------------------------------
                               540007
(1 row)

column_to_column_name

Convertit la colonne partkey de pg_dist_partition en nom de colonne textuel. La conversion est utile pour déterminer la colonne de distribution d’une table distribuée.

Pour plus d’informations, consultez choix d’une colonne de distribution.

Arguments

table_name : Table distribuée.

column_var_text : Valeur de partkey dans la table pg_dist_partition.

Valeur retournée

Nom de la colonne de distribution de table_name.

Exemple

-- get distribution column name for products table

SELECT column_to_column_name(logicalrelid, partkey) AS dist_col_name
  FROM pg_dist_partition
 WHERE logicalrelid='products'::regclass;

Sortie :

┌───────────────┐
│ dist_col_name │
├───────────────┤
│ company_id    │
└───────────────┘

citus_relation_size

Obtenez l’espace disque utilisé par toutes les partitions de la table distribuée spécifiée. L’espace disque inclut la taille de la « fourche principale », mais exclut la carte de visibilité et le mappage d’espace libre pour les partitions.

Arguments

logicalrelid : le nom d’une table distribuée.

Valeur retournée

Taille en octets comme bigint.

Exemple

SELECT pg_size_pretty(citus_relation_size('github_events'));

pg_size_pretty
--------------
23 MB

citus_table_size

Obtenez l’espace disque utilisé par toutes les partitions de la table distribuée spécifiée, à l’exclusion des index (mais TOAST, carte d’espace libre et carte de visibilité compris).

Arguments

logicalrelid : le nom d’une table distribuée.

Valeur retournée

Taille en octets comme bigint.

Exemple

SELECT pg_size_pretty(citus_table_size('github_events'));

pg_size_pretty
--------------
37 MB

citus_total_relation_size

Obtenez l’espace disque total utilisé par toutes les partitions de la table distribuée spécifiée, y compris tous les index et données TOAST.

Arguments

logicalrelid : le nom d’une table distribuée.

Valeur retournée

Taille en octets comme bigint.

Exemple

SELECT pg_size_pretty(citus_total_relation_size('github_events'));

pg_size_pretty
--------------
73 MB

citus_stat_statements_reset

Supprime toutes les lignes de citus_stat_statements. Cette fonction fonctionne indépendamment de pg_stat_statements_reset(). Pour réinitialiser toutes les statistiques, appelez les deux fonctions.

Arguments

N/A

Valeur retournée

None

citus_get_active_worker_nodes

La fonction citus_get_active_worker_nodes() retourne une liste des noms d’hôte Worker et des numéros de port actifs.

Arguments

N/A

Valeur retournée

Liste de tuples où chaque tuple contient les informations suivantes :

node_name : nom DNS du nœud Worker

node_port : port sur le nœud worker sur lequel le serveur de base de données est à l’écoute

Exemple

SELECT * from citus_get_active_worker_nodes();
 node_name | node_port
-----------+-----------
 localhost |      9700
 localhost |      9702
 localhost |      9701

(3 rows)

Gestion et réparation du cluster

master_copy_shard_placement

Si la sélection élective d’une partition ne peut pas être mise à jour au cours d’une commande de modification ou d’une opération DDL, il est marqué comme étant inactif. La fonction master_copy_shard_placement peut ensuite être appelée pour réparer un placement de partition inactif à l’aide de données provenant d’un placement sain.

Pour réparer une partition, la fonction supprime d’abord la sélection élective de partition défectueuse et la crée de nouveau à l’aide du schéma sur le coordinateur. Une fois la sélection élective de partition créée, la fonction copie les données à partir de l’emplacement sain et met à jour les métadonnées pour marquer la nouvelle sélection élective de partition comme saine. Cette fonction garantit que la partition est protégée contre toute modification simultanée pendant la réparation.

Arguments

shard_id : ID de la partition à réparer.

source_node_name : Nom DNS du nœud sur lequel le placement de partition sain est présent (nœud « source »).

source_node_port : Port sur le nœud worker source sur lequel le serveur de base de données est à l’écoute.

target_node_name : Nom DNS du nœud sur lequel le placement de partition non valide est présent (nœud « cible »).

target_node_port : Port sur le nœud worker cible sur lequel le serveur de base de données est à l’écoute.

Valeur retournée

N/A

Exemple

L’exemple ci-dessous répare un placement de partition inactif de la partition 12345, qui est présent sur le serveur de base de données en cours d’exécution sur « bad_host » sur le port 5432. Pour le réparer, il utilise les données d’un placement de partition sain présent sur le serveur en cours d’exécution sur « good_host » sur le port 5432.

SELECT master_copy_shard_placement(12345, 'good_host', 5432, 'bad_host', 5432);

master_move_shard_placement

Cette fonction déplace une partition donnée (et les partitions en colocation avec) d’un nœud à un autre. Il est généralement utilisé indirectement pendant le rééquilibrage de partition plutôt que directement appelé par un administrateur de base de données.

Il existe deux façons de déplacer les données : le blocage ou le non-blocage. L’approche de blocage signifie qu’au cours du déplacement, toutes les modifications apportées aux partitions sont suspendues. La seconde méthode, qui évite le blocage des écritures de partition, s’appuie sur la réplication logique Postgre 10.

Après une opération de déplacement réussie, les partitions dans le nœud source sont supprimées. Si le déplacement échoue, cette fonction génère une erreur et laisse les nœuds source et cible inchangés.

Arguments

shard_id : ID de la partition à déplacer.

source_node_name : Nom DNS du nœud sur lequel le placement de partition sain est présent (nœud « source »).

source_node_port : Port sur le nœud worker source sur lequel le serveur de base de données est à l’écoute.

target_node_name : Nom DNS du nœud sur lequel le placement de partition non valide est présent (nœud « cible »).

target_node_port : Port sur le nœud worker cible sur lequel le serveur de base de données est à l’écoute.

shard_transfer_mode : (Facultatif) Spécifiez la méthode de réplication, si vous souhaitez utiliser la réplication logique PostgreSQL ou une commande COPY inter-worker. Les valeurs possibles sont les suivantes :

auto: Exigez une identité de réplica si la réplication logique est possible, sinon utilisez le comportement hérité (par exemple, pour la réparation partition, PostgreSQL 9,6). Il s’agit de la valeur par défaut.

force_logical: Utilisez la réplication logique même si la table n’a pas d’identité de réplica. Toute commande update/delete simultanée vers la table échouera lors de la réplication.

block_writes: Utilisez COPY (blocking writes) pour les tables dépourvues d’une clé primaire ou d’une identité de réplica.

Valeur retournée

N/A

Exemple

SELECT master_move_shard_placement(12345, 'from_host', 5432, 'to_host', 5432);

rebalance_table_shards

La fonction rebalance_table_shards() déplace les partitions de la table donnée pour les distribuer uniformément entre les Workers. La fonction calcule d’abord la liste des déplacements qu’elle doit effectuer pour s’assurer que le cluster est équilibré dans le seuil donné. Ensuite, il déplace les emplacements partition un par un du nœud source vers le nœud de destination et met à jour les métadonnées de partition correspondantes pour refléter le déplacement.

Un coût est attribué à chaque partition pour déterminer si les partitions sont « réparties uniformément ». Par défaut, chaque partition a le même coût (une valeur de 1). Par conséquent, la distribution pour égaliser le coût entre les Workers est identique à l’égalisation du nombre de partitions sur chaque Worker. La stratégie de coût constant est appelée « by_shard_count » et est la stratégie de rééquilibrage par défaut.

La stratégie « by_shard_count » est appropriée dans les circonstances suivantes :

Les partitions sont à peu près de la même taille
Le partitions obtiennent à peu près la même quantité de trafic
Les nœuds worker sont de la même taille/type
Les partitions n’ont pas été épinglées à des workers particuliers

Si l’une de ces hypothèses ne tient pas, le rééquilibrage « by_shard_count » peut entraîner un mauvais plan.

La stratégie de rééquilibrage par défaut est « by_disk_size ». Vous pouvez toujours personnaliser la stratégie à l’aide du paramètre rebalance_strategy.

Il est recommandé d’appeler get_rebalance_table_shards_plan avant d’exécuter rebalance_table_shards pour afficher et vérifier les actions à effectuer.

Arguments

table_name : (Facultatif) Nom de la table dont les partitions doivent être rééquilibrées. Si la valeur est NULL, rééquilibrer tous les groupes de colocation existants.

threshold : (Facultatif) Nombre à virgule flottante compris entre 0,0 et 1,0 qui indique le taux de différence maximal de l’utilisation des nœuds par rapport à l’utilisation moyenne. Par exemple, si vous spécifiez 0,1, le rééquilibreur de partition tentera d’équilibrer tous les nœuds pour qu’ils contiennent le même nombre de partitions ± 10%. Plus précisément, le rééquilibreur de partition tente de converger l’utilisation de tous les nœuds Worker vers la plage (1 - threshold) * average_utilization ... (1

threshold) * average_utilization.

max_shard_moves : (Facultatif) Nombre maximal de partitions à déplacer.

excluded_shard_list : (Facultatif) Identificateurs de partitions qui ne doivent pas être déplacées au cours de l’opération de rééquilibrage.

auto: Exigez une identité de réplica si la réplication logique est possible, sinon utilisez le comportement hérité (par exemple, pour la réparation partition, PostgreSQL 9,6). Il s’agit de la valeur par défaut.

force_logical: Utilisez la réplication logique même si la table n’a pas d’identité de réplica. Toute commande update/delete simultanée vers la table échouera lors de la réplication.

block_writes: Utilisez COPY (blocking writes) pour les tables dépourvues d’une clé primaire ou d’une identité de réplica.

drain_only : (Facultatif) Si la valeur est true, déplace les partitions hors des nœuds Worker qui ont shouldhaveshards défini sur false dans pg_dist_node ; ne déplace aucune autre partition.

rebalance_strategy : (Facultatif) Le nom d’une stratégie dans pg_dist_rebalance_strategy. Si cet argument est omis, la fonction choisit la stratégie par défaut, comme indiqué dans la table.

Valeur retournée

N/A

Exemple

L’exemple ci-dessous tente de rééquilibrer les partitions de la table github_events dans le seuil par défaut.

SELECT rebalance_table_shards('github_events');

Cet exemple d’utilisation va tenter de rééquilibrer la table github_events sans déplacer de partitions avec les ID 1 et 2.

SELECT rebalance_table_shards('github_events', excluded_shard_list:='{1,2}');

get_rebalance_table_shards_plan

Générez les mouvements partition planifiés de rebalance_table_shards sans les exécuter. Bien que cela soit peu probable, get_rebalance_table_shards_plan peut générer un plan légèrement différent de celui d’un appel de rebalance_table_shards avec les mêmes arguments. Ils ne sont pas exécutés en même temps. par conséquent, les faits sur le cluster, par exemple l’espace disque, peuvent varier entre les appels.

Arguments

Les arguments sont les mêmes que ceux de rebalance_table_shards : relation, threshold, max_shard_moves, excluded_shard_list et drain_only. Consultez la documentation de cette fonction pour la signification des arguments.

Valeur retournée

Tuples contenant les colonnes suivantes :

table_name : Table dont les partitions se déplaceraient
shardid : La partition en question
shard_size : Taille en octets
sourcename : Nom d’hôte du nœud source
sourceport : Port du nœud source
targetname : Nom d’hôte du nœud de destination
targetport : Port du nœud de destination

get_rebalance_progress

Une fois qu’un rééquilibrage de partition commence, la fonction get_rebalance_progress() répertorie la progression de chaque partition impliquée. Elle surveille les déplacements planifiés et exécutés par rebalance_table_shards().

Arguments

N/A

Valeur retournée

Tuples contenant les colonnes suivantes :

sessionid : PID Postgres de l’analyse de rééquilibrage
table_name : Table dont les partitions se déplacent
shardid : La partition en question
shard_size : Taille en octets
sourcename : Nom d’hôte du nœud source
sourceport : Port du nœud source
targetname : Nom d’hôte du nœud de destination
targetport : Port du nœud de destination
progress : 0 = en attente de déplacement ; 1 = en déplacement ; 2 = terminé

Exemple

SELECT * FROM get_rebalance_progress();

┌───────────┬────────────┬─────────┬────────────┬───────────────┬────────────┬───────────────┬────────────┬──────────┐
│ sessionid │ table_name │ shardid │ shard_size │  sourcename   │ sourceport │  targetname   │ targetport │ progress │
├───────────┼────────────┼─────────┼────────────┼───────────────┼────────────┼───────────────┼────────────┼──────────┤
│      7083 │ foo        │  102008 │    1204224 │ n1.foobar.com │       5432 │ n4.foobar.com │       5432 │        0 │
│      7083 │ foo        │  102009 │    1802240 │ n1.foobar.com │       5432 │ n4.foobar.com │       5432 │        0 │
│      7083 │ foo        │  102018 │     614400 │ n2.foobar.com │       5432 │ n4.foobar.com │       5432 │        1 │
│      7083 │ foo        │  102019 │       8192 │ n3.foobar.com │       5432 │ n4.foobar.com │       5432 │        2 │
└───────────┴────────────┴─────────┴────────────┴───────────────┴────────────┴───────────────┴────────────┴──────────┘

citus_add_rebalance_strategy

Ajoutez une ligne à pg_dist_rebalance_strategy.

Arguments

Pour plus d’informations sur ces arguments, consultez les valeurs de colonnes correspondantes dans pg_dist_rebalance_strategy.

name : identificateur pour la nouvelle stratégie

shard_cost_function : Identifie la fonction utilisée pour déterminer le « coût » de chaque partition

node_capacity_function : Identifie la fonction pour mesurer la capacité du nœud

shard_allowed_on_node_function : Identifie la fonction qui détermine quelles partitions peuvent être placées sur quels nœuds

default_threshold : Un seuil à virgule flottante qui ajuste la précision avec laquelle le coût de partition cumulé doit être équilibré entre les nœuds

minimum_threshold : (Facultatif) Colonne de protection qui contient la valeur minimale autorisée pour l’argument de seuil de rebalance_table_shards(). Sa valeur par défaut est 0

Valeur retournée

N/A

citus_set_default_rebalance_strategy

Mettez à jour la table pg_dist_rebalance_strategy en modifiant la stratégie nommée par son argument comme étant la valeur par défaut choisie lors du rééquilibrage de partitions.

Arguments

name : (Facultatif) Nom de la stratégie dans pg_dist_rebalance_strategy

Valeur retournée

N/A

Exemple

SELECT citus_set_default_rebalance_strategy('by_disk_size');

citus_remote_connection_stats

La fonction citus_remote_connection_stats() indique le nombre de connexions actives à chaque nœud distant.

Arguments

N/A

Exemple

SELECT * from citus_remote_connection_stats();

    hostname    | port | database_name | connection_count_to_node
----------------+------+---------------+--------------------------
 citus_worker_1 | 5432 | postgres      |                        3
(1 row)

isolate_tenant_to_new_shard

Cette fonction crée une nouvelle partition pour stocker des lignes avec une valeur unique spécifique dans la colonne de distribution. Elle est particulièrement pratique pour le cas d’usage multilocataire, où un locataire volumineux peut être placé seul sur sa propre partition et finalement son propre nœud physique.

Arguments

table_name : Nom de la table pour laquelle obtenir une nouvelle partition.

tenant_id : Valeur de la colonne de distribution qui sera affectée à la nouvelle partition.

cascade_option : (Facultatif) Lorsqu’il est défini sur « CASCADE », isole également une partition de toutes les tables dans le groupe de colocation de la table active.

Valeur retournée

shard_id : La fonction retourne l’ID unique affecté à la partition nouvellement créée.

Exemples

Créez une nouvelle partition pour contenir les lineitems pour le locataire 135 :

SELECT isolate_tenant_to_new_shard('lineitem', 135);

┌─────────────────────────────┐
│ isolate_tenant_to_new_shard │
├─────────────────────────────┤
│                      102240 │
└─────────────────────────────┘

Étapes suivantes

La plupart des fonctions de cet article modifient les tables de métadonnées système
Paramètres du serveur personnaliser le comportement de certaines fonctions