Azure Cosmos DB for PostgreSQL-Funktionen
GILT FÜR: Azure Cosmos DB for PostgreSQL (unterstützt von der Citus-Datenbankerweiterung auf PostgreSQL)
Dieser Abschnitt enthält Referenzinformationen zu den benutzerdefinierten Funktionen, die von Azure Cosmos DB for PostgreSQL bereitgestellt werden. Diese Funktionen helfen bei der Bereitstellung verteilter Funktionalität für Azure Cosmos DB for PostgreSQL.
Hinweis
Cluster, auf denen ältere Versionen der Citus-Engine ausgeführt werden, bieten möglicherweise nicht alle auf diese Seite aufgeführten Funktionen.
Tabellen- und Shard-DDL
citus_schema_distribute
Konvertiert vorhandene reguläre Schemas in verteilte Schemas. Verteilte Schemas werden automatisch einzelnen Zusammenstellungsgruppen zugeordnet. Die in diesen Schemas erstellten Tabellen werden in zusammengestellte verteilte Tabellen ohne Shardschlüssel konvertiert. Bei der Schemaverteilung wird das Schema automatisch zugewiesen und in einen vorhandenen Knoten im Cluster verschoben.
Argumente
schemaname: Name des Schemas, das verteilt werden muss
Rückgabewert
Nicht zutreffend
Beispiel
SELECT citus_schema_distribute('tenant_a');
SELECT citus_schema_distribute('tenant_b');
SELECT citus_schema_distribute('tenant_c');
Weitere Beispiele finden Sie in der Anleitung zum Entwurf für Microservices.
citus_schema_undistribute
Konvertiert ein vorhandenes verteiltes Schema wieder in ein normales Schema. Der Prozess führt dazu, dass die Tabellen und Daten vom aktuellen Knoten zurück in den Koordinatorknoten im Cluster verschoben werden.
Argumente
schemaname: Name des Schemas, das verteilt werden muss
Rückgabewert
Nicht zutreffend
Beispiel
SELECT citus_schema_undistribute('tenant_a');
SELECT citus_schema_undistribute('tenant_b');
SELECT citus_schema_undistribute('tenant_c');
Weitere Beispiele finden Sie in der Anleitung zum Entwurf für Microservices.
create_distributed_table
Die Funktion „create_distributed_table()“ wird verwendet, um eine verteilte Tabelle zu definieren und deren Shards zu erstellen, wenn es sich um eine Tabelle mit Hashverteilung handelt. Diese Funktion nimmt einen Tabellennamen, die Verteilungsspalte und eine optionale Verteilungsmethode an und fügt geeignete Metadaten ein, um die Tabelle als verteilt zu kennzeichnen. Die Funktion ist standardmäßig auf die Verteilung „hash“ festgelegt, wenn keine Verteilungsmethode angegeben wird. Wenn die Tabelle Hashverteilung aufweist, erstellt die Funktion auch Workershards auf der Grundlage der Shardanzahl und der Konfigurationswerte für den Shardreplikationsfaktor. Wenn die Tabelle Zeilen enthält, werden diese automatisch an Workerknoten verteilt.
Diese Funktion ersetzt „master_create_distributed_table()“, gefolgt von „master_create_worker_shards()“.
Argumente
table_name: Name der Tabelle, die verteilt werden muss
distribution_column: Spalte, für die die Tabelle verteilt werden soll
distribution_type: (optional) Methode, nach der die Tabelle verteilt werden soll Zulässige Werte sind „append“ oder „hash“ mit dem Standardwert „hash“.
colocate_with: (optional) schließt die aktuelle Tabelle in die Colocationsgruppe einer anderen Tabelle ein. Standardmäßig werden Tabellen verbunden, wenn sie durch Spalten desselben Typs verteilt werden und die gleiche Shardanzahl und denselben Replikationsfaktor aufweisen. Mögliche Werte für colocate_with
sind default
, none
, um eine neue Colocationsgruppe zu starten, oder der Name einer anderen Tabelle, für die Colocation mit dieser Tabelle verwendet werden soll. (Weitere Informationen finden Sie unter Tabellencolocation.)
Beachten Sie, dass der Standardwert colocate_with
eine implizite Colocation vornimmt. Colocation kann eine hervorragende Lösung sein, wenn Tabellen in Beziehung stehen oder verknüpft werden sollen. Wenn jedoch zwei Tabellen nicht miteinander in Beziehung stehen, aber zufällig den gleichen Datentyp für ihre Verteilungsspalten verwenden, kann die Leistung bei Shardausgleich durch eine versehentliche Colocation beeinträchtigt werden. Die Tabellenshards werden unnötig in einer „Kaskade“ miteinander verschoben.
Wenn eine neue verteilte Tabelle nicht in Beziehung mit anderen Tabellen steht, ist es am besten, colocate_with => 'none'
anzugeben.
shard_count: (Optional) die Anzahl der Shards, die für die neue verteilte Tabelle erstellt werden sollen. Wenn Sie shard_count
angeben, können Sie nur den Wert von colocate_with
oder keinen angeben. Verwenden Sie die Funktion alter_distributed_table, um die Shardanzahl einer vorhandenen Tabelle oder Colocation-Gruppe zu ändern.
Mögliche Werte für shard_count
liegen zwischen 1 und 64.000. Eine Anleitung zur Auswahl des optimalen Werts finden Sie unter Anzahl von Shards.
Rückgabewert
Nicht zutreffend
Beispiel
Dieses Beispiel informiert die Datenbank, dass die Tabelle „github_events“ per Hash auf die Spalte „repo_id“ verteilt werden soll.
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
Diese Funktion hat die gleiche Schnittstelle und denselben Zweck wie create_distributed_function, blockiert aber Schreibvorgänge während der Tabellenverteilung nicht.
Für create_distributed_table_concurrently
gibt es jedoch einige Einschränkungen:
- Sie können die Funktion nicht in einem Transaktionsblock verwenden, was bedeutet, dass Sie nur jeweils eine Tabelle verteilen können. (Sie können die Funktion jedoch für zeitpartitionierte Tabellen verwenden.)
- Sie können
create_distributed_table_concurrently
nicht verwenden, wenn auf die Tabelle durch einen Fremdschlüssel verwiesen wird oder sie auf eine andere lokale Tabelle verweist. Fremdschlüssel zum Verweisen auf Tabellen funktionieren jedoch, und Sie können Fremdschlüssel für andere verteilte Tabellen erstellen, nachdem die Tabellenverteilung abgeschlossen ist. - Wenn Sie nicht über einen Primärschlüssel oder eine Replikatidentität in Ihrer Tabelle verfügen, schlagen Aktualisierungs- und Löschbefehle während der Tabellenverteilung aufgrund von Einschränkungen bei der logischen Replikation fehl.
truncate_local_data_after_distributing_table
Schneidet nach dem Verteilen einer Tabelle alle lokalen Zeilen ab und verhindert, dass bei Einschränkungen aufgrund veralteter lokaler Datensätze ein Fehler auftritt. Die Kürzung wird an Tabellen mit einem Fremdschlüssel für die vorgesehene Tabelle weitergegeben. Wenn die verweisenden Tabellen nicht selbst verteilt werden, ist das Abschneiden bis zu ihrer Verteilung unzulässig, um die referentielle Integrität zu schützen:
ERROR: cannot truncate a table referenced in a foreign key constraint by a local table
Das Abschneiden der Tabellendaten des lokalen Koordinatorknotens ist für verteilte Tabellen sicher, da ihre Zeilen (sofern vorhanden) während der Verteilung auf Workerknoten kopiert werden.
Argumente
table_name: Name der verteilten Tabelle, deren lokale Entsprechung im Koordinatorknoten abgeschnitten werden soll
Rückgabewert
Nicht zutreffend
Beispiel
-- requires that argument is a distributed table
SELECT truncate_local_data_after_distributing_table('public.github_events');
create_reference_table
Die Funktion „create_reference_table()“ wird verwendet, um eine kleine Verweis- oder Dimensionstabelle zu definieren. Diese Funktion nimmt einen Tabellennamen an und erstellt eine verteilte Tabelle mit nur einem Shard, der auf jeden Workerknoten repliziert wird.
Argumente
table_name: Name der kleinen Dimensions- oder Verweistabelle, die verteilt werden muss
Rückgabewert
Nicht zutreffend
Beispiel
Dieses Beispiel informiert die Datenbank, dass die Tabelle „nation“ als Verweistabelle definiert werden sollte.
SELECT create_reference_table('nation');
citus_add_local_table_to_metadata
Fügt eine lokale Postgres-Tabelle zu Citus-Metadaten hinzu. Ein wichtiger Anwendungsfall für diese Funktion besteht darin, lokale Tabellen auf dem Koordinator von jedem Knoten im Cluster aus zugänglich zu machen. Die Daten, die der lokalen Tabelle zugeordnet sind, bleiben auf dem Koordinator – nur das Schema und die Metadaten werden an die Worker gesendet.
Das Hinzufügen lokaler Tabellen zu den Metadaten ist mit geringen Kosten verbunden. Wenn Sie die Tabelle hinzufügen, muss Citus sie in der Partitionstabelle nachverfolgen. Lokale Tabellen, die Metadaten hinzugefügt werden, erben dieselben Einschränkungen wie Verweistabellen.
Wenn Sie die Verteilung der Tabelle aufheben, entfernt Citus die resultierenden lokalen Tabellen aus den Metadaten. Dadurch werden solche Einschränkungen für diese Tabellen beseitigt.
Argumente
table_name: Name der Tabelle auf einem Koordinator, die den Citus-Metadaten hinzugefügt werden soll
cascade_via_foreign_keys: (Optional) Wenn dieses Argument auf „true“ festgelegt ist, fügt citus_add_local_table_to_metadata andere Tabellen, die in einer Fremdschlüsselbeziehung zu der angegebenen Tabelle stehen, automatisch zu den Metadaten hinzu. Verwenden Sie diesen Parameter mit Vorsicht, da er sich potenziell auf zahlreiche Tabellen auswirken kann.
Rückgabewert
Nicht zutreffend
Beispiel
Dieses Beispiel informiert die Datenbank, dass die Tabelle „nation“ als im Koordinator lokale Tabelle definiert werden sollte, auf die von jedem Knoten zugegriffen werden kann:
SELECT citus_add_local_table_to_metadata('nation');
alter_distributed_table
Die Funktion „alter_distributed_table()“ kann verwendet werden, um die Verteilungsspalte, die Shardanzahl oder die Zusammenstellungseigenschaften einer verteilten Tabelle zu ändern.
Argumente
table_name: Name der Tabelle, die geändert wird
distribution_column: (Optional) Name der neuen Verteilungsspalte
shard_count: (Optional) Die neue Shardanzahl
colocate_with: (Optional) Die Tabelle, mit der die derzeit verteilte Tabelle zusammengestellt wird. Mögliche Werte sind default
, none
zum Beginnen einer neuen Zusammenstellungsgruppe oder der Name einer anderen Tabelle, mit der die Zusammenstellung erfolgen soll. (Weitere Informationen finden Sie unter Tabellencolocation.)
cascade_to_colocated: (Optional) Wenn dieses Argument auf „true“ festgelegt wird, werden Änderungen an shard_count
und colocate_with
auch auf alle Tabellen angewendet, die zuvor mit der Tabelle verbunden waren, und die Zusammenstellung wird beibehalten. Wenn der Wert „false“ lautet, wird die aktuelle Zusammenstellung dieser Tabelle aufgehoben.
Rückgabewert
Nicht zutreffend
Beispiel
-- 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
Die Funktion „update_distributed_table_colocation()“ wird zum Aktualisieren der Zusammenstellung einer verteilten Tabelle verwendet. Diese Funktion kann auch verwendet werden, um die Zusammenstellung einer verteilten Tabelle aufzuheben. Azure Cosmos DB for PostgreSQL stellt implizit zwei Tabellen zusammen, wenn die Verteilungsspalte denselben Typ aufweist. Dies kann nützlich sein, wenn die Tabellen in Beziehung stehen oder Verknüpfungen herstellen. Wenn Tabellen A und B zusammengestellt werden und Tabelle A neu ausgeglichen wird, wird auch Tabelle B neu ausgeglichen. Verfügt Tabelle B nicht über eine Replikatidentität, tritt beim Neuausgleich ein Fehler auf. Daher kann diese Funktion hilfreich sein, um die implizite Zusammenstellung in diesem Fall aufzuheben.
Mit dieser Funktion werden Daten nicht physisch verschoben.
Argumente
table_name: Name der Tabellenzusammenstellung, die aktualisiert wird
colocate_with: Die Tabelle, mit der die Tabelle zusammengestellt werden soll.
Wenn Sie die Zusammenstellung einer Tabelle aufheben möchten, müssen Sie colocate_with => 'none'
angeben.
Rückgabewert
Nicht zutreffend
Beispiel
Dieses Beispiel zeigt, dass die Zusammenstellung von Tabelle A als Zusammenstellung von Tabelle B aktualisiert wird.
SELECT update_distributed_table_colocation('A', colocate_with => 'B');
Angenommen, Tabelle A und Tabelle B werden (möglicherweise implizit) zusammengestellt, wenn Sie die Zusammenstellung aufheben möchten:
SELECT update_distributed_table_colocation('A', colocate_with => 'none');
Nehmen wir nun an, dass Tabelle A, Tabelle B, Tabelle C und Tabelle D zusammengestellt sind und Sie Tabelle A und Tabelle B sowie Tabelle C und Tabelle D zusammenstellen möchten:
SELECT update_distributed_table_colocation('C', colocate_with => 'none');
SELECT update_distributed_table_colocation('D', colocate_with => 'C');
Wenn Sie über eine Tabelle mit Hashverteilung mit dem Namen „none“ verfügen und deren Zusammenstellung aktualisieren möchten, können Sie Folgendes ausführen:
SELECT update_distributed_table_colocation('"none"', colocate_with => 'some_other_hash_distributed_table');
undistribute_table
Mit der Funktion „undistribute_table()“ wird die Aktion von „create_distributed_table“ oder „create_reference_table“ rückgängig gemacht. Beim Aufheben der Verteilung werden alle Daten von Shards zurück in eine lokale Tabelle im Koordinatorknoten verschoben (vorausgesetzt, die Daten passen hinein). Anschließend werden die Shards gelöscht.
Azure Cosmos DB for PostgreSQL hebt die Verteilung von Tabellen, die über Fremdschlüssel verfügen oder auf die durch Fremdschlüssel verwiesen wird, nicht auf, es sei denn, das Argument „cascade_via_foreign_keys“ wird auf „true“ festgelegt. Wird dieses Argument auf „false“ festgelegt (oder ausgelassen), müssen Sie die problematischen Einschränkungen des Fremdschlüssels manuell löschen, bevor Sie die Verteilung aufheben.
Argumente
table_name: Name der verteilten Tabelle oder Verweistabelle, deren Verteilung aufgehoben werden soll
cascade_via_foreign_keys: (Optional) Wenn dieses Argument auf „true“ festgelegt wird, wird mit „undistribute_table“ auch die Verteilung aller Tabellen aufgehoben, die über Fremdschlüssel mit „table_name“ in Beziehung stehen. Verwenden Sie diesen Parameter mit Vorsicht, da er sich potenziell auf zahlreiche Tabellen auswirken kann.
Rückgabewert
Nicht zutreffend
Beispiel
In diesem Beispiel wird eine Tabelle vom Typ github_events
verteilt und ihre Verteilung anschließend wieder aufgehoben.
-- 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
Gibt eine Funktion vom Koordinatorknoten an Worker weiter und markiert sie für verteilte Ausführung. Wenn eine verteilte Funktion für den Koordinator aufgerufen wird, verwendet Azure Cosmos DB for PostgreSQL den Wert des distribution-Arguments, um einen Workerknoten zum Ausführen der Funktion auszuwählen. Das Ausführen der Funktion für Worker erhöht die Parallelität und kann den Code in Shards näher an Daten bringen, um geringere Latenz zu erzielen.
Der Postgres-Suchpfad wird während der Ausführung verteilter Funktionen nicht vom Koordinator an Worker weitergegeben. Daher sollte der Code der verteilten Funktion die Namen von Datenbankobjekten als vollqualifizierte Namen angeben. Außerdem werden dem Benutzer keine Benachrichtigungen angezeigt, die von den Funktionen ausgegeben werden.
Argumente
function_name: Name der zu verteilenden Funktion. Der Name muss die Parametertypen der Funktion in Klammern enthalten, da mehrere Funktionen in PostgreSQL denselben Namen haben können. Beispielsweise unterscheidet sich 'foo(int)'
von 'foo(int, text)'
.
distribution_arg_name: (optional) Argumentname, nach dem verteilt werden soll. Zur einfacheren Handhabung (oder wenn die Funktionsargumente keine Namen besitzen) ist ein Positionsplatzhalter zulässig, z. B. '$1'
. Wenn dieser Parameter nicht angegeben wird, wird die durch function_name
benannte Funktion nur für die Worker erstellt. Wenn Workerknoten zu einem späteren Zeitpunkt hinzugefügt werden, wird die Funktion auf ihnen ebenfalls automatisch erstellt.
colocate_with: (optional) Wenn die verteilte Funktion Lese- oder Schreibvorgänge für eine verteilte Tabelle (oder allgemeiner für eine Colocationgruppe) ausführt, stellen Sie sicher, dass Sie diese Tabelle mithilfe des Parameters colocate_with
benennen. Anschließend wird jeder Aufruf der Funktion auf dem Workerknoten ausgeführt, der relevante Shards enthält.
Rückgabewert
Nicht zutreffend
Beispiel
-- 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
Die Funktion „alter_columnar_table_set()“ ändert die Einstellungen bei einer Spaltentabelle. Das Aufrufen dieser Funktion bei einer Nicht-Spaltentabelle führt zu einem Fehler. Alle Argumente außer dem Tabellennamen sind optional.
Informationen zum Anzeigen der aktuellen Optionen für alle Spaltentabellen finden Sie in dieser Tabelle:
SELECT * FROM columnar.options;
Die Standardwerte für Spalteneinstellungen bei neu erstellten Tabellen können mit diesen GUCs überschrieben werden:
- columnar.compression
- columnar.compression_level
- columnar.stripe_row_count
- columnar.chunk_row_count
Argumente
table_name: Der Name der Spaltentabelle.
chunk_row_count: (Optional) Die maximale Anzahl von Zeilen pro Block für neu eingefügte Daten. Vorhandene Datenblöcke werden nicht geändert und enthalten möglicherweise mehr Zeilen als diesen Höchstwert. Der Standardwert ist 10.000.
stripe_row_count: (Optional) Die maximale Anzahl von Zeilen pro Bereichsstreifen für neu eingefügte Daten. Vorhandene Bereichsstreifen von Daten werden nicht geändert und enthalten möglicherweise mehr Zeilen als diesen Höchstwert. Der Standardwert ist 150.000.
compression: (Optional) [none|pglz|zstd|lz4|lz4hc]
Der Komprimierungstyp für neu eingefügte Daten. Vorhandene Daten werden nicht erneut komprimiert oder dekomprimiert. Der Standardwert und der vorgeschlagene Wert ist „zstd“ (wenn die Unterstützung kompiliert wurde).
compression_level: (Optional) Gültige Einstellungen liegen zwischen 1 und 19. Wenn die Komprimierungsmethode die ausgewählte Ebene nicht unterstützt, wird stattdessen die nächstgelegene Ebene ausgewählt.
Rückgabewert
Nicht zutreffend
Beispiel
SELECT alter_columnar_table_set(
'my_columnar_table',
compression => 'none',
stripe_row_count => 10000);
alter_table_set_access_method
Mit der Funktion „alter_table_set_access_method()“ wird die Zugriffsmethode einer Tabelle (etwa einer Heap- oder Spaltentabelle) geändert.
Argumente
table_name: Name der Tabelle, deren Zugriffsmethode geändert wird
access_method: Name der neuen Zugriffsmethode
Rückgabewert
Nicht zutreffend
Beispiel
SELECT alter_table_set_access_method('github_events', 'columnar');
create_time_partitions
Die Funktion „create_time_partitions()“ erstellt Partitionen eines bestimmten Intervalls, um einen bestimmten Zeitbereich abzudecken.
Argumente
table_name: (regclass) Tabelle, für die neue Partitionen erstellt werden sollen. Die Tabelle muss nach einer Spalte vom Typ „date“, „timestamp“ oder „timestamptz“ partitioniert werden.
partition_interval: Ein Zeitintervall wie '2 hours'
oder '1 month'
, das zum Festlegen von Bereichen für neue Partitionen verwendet werden soll
end_at: (timestamptz) Mit diesem Argument werden Partitionen bis zu diesem Zeitpunkt erstellt. Die letzte Partition enthält den Punkt „end_at“, und es werden keine späteren Partitionen erstellt.
start_from: (timestamptz, optional) Wählen Sie die erste Partition aus, sodass sie den Punkt „start_from“ enthält. Der Standardwert ist now()
.
Rückgabewert
„true“, wenn neue Partitionen erstellt werden müssen, „false“, wenn alle bereits vorhanden waren.
Beispiel
-- 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
Mit der Funktion „drop_old_time_partitions()“ werden alle Partitionen entfernt, deren Intervalle vor einem bestimmten Zeitstempel liegen. Zusätzlich zu dieser Funktion können Sie die Verwendung von alter_old_partitions_set_access_method zum Komprimieren der alten Partitionen mit spaltenbasiertem Speicher in Erwägung ziehen.
Argumente
table_name: (regclass) Tabelle, für die Partitionen entfernt werden sollen. Die Tabelle muss nach einer Spalte vom Typ „date“, „timestamp“ oder „timestamptz“ partitioniert werden.
older_than: (timestamptz) Dient zum Löschen von Partitionen, deren oberer Bereich kleiner oder gleich „older_than“ ist
Rückgabewert
Nicht zutreffend
Beispiel
-- drop partitions that are over a year old
CALL drop_old_time_partitions('foo', now() - interval '12 months');
alter_old_partitions_set_access_method
In einem Anwendungsfall mit Zeitreihen werden Tabellen häufig nach Zeit partitioniert, und alte Partitionen werden in schreibgeschütztem spaltenbasiertem Speicher komprimiert.
Argumente
parent_table_name: (regclass) Tabelle, für die Partitionen geändert werden sollen. Die Tabelle muss nach einer Spalte vom Typ „date“, „timestamp“ oder „timestamptz“ partitioniert werden.
older_than: (timestamptz) Dient zum Ändern von Partitionen, deren oberer Bereich kleiner oder gleich „older_than“ ist
new_access_method: (name) entweder „heap“ für zeilenbasierten Speicher oder „columnar“ für spaltenbasierten Speicher.
Rückgabewert
Nicht zutreffend
Beispiel
CALL alter_old_partitions_set_access_method(
'foo', now() - interval '6 months',
'columnar'
);
Metadaten/Konfigurationsinformationen
get_shard_id_for_distribution_column
Azure Cosmos DB for PostgreSQL weist jede Zeile einer verteilten Tabelle einem Shard basierend auf dem Wert der Verteilungsspalte der Zeile und der Verteilungsmethode der Tabelle zu. In den meisten Fällen handelt es sich bei der exakten Zuordnung um Details auf niedriger Ebene, die vom Datenbankadministrator ignoriert werden können. Allerdings kann es hilfreich sein, den Shard einer Zeile zu bestimmen, entweder für manuelle Datenbankverwaltungsaufgaben oder nur aus Neugier. Die Funktion get_shard_id_for_distribution_column
stellt diese Informationen für Tabellen mit Hash- und Bereichsverteilung sowie für Verweistabellen bereit. Dies funktioniert nicht für die Anfügeverteilung.
Argumente
table_name: die verteilte Tabelle
distribution_value: Wert der Verteilungsspalte
Rückgabewert
Die Shard-ID, die Azure Cosmos DB for PostgreSQL mit dem Wert der Verteilungsspalte für die angegebene Tabelle verknüpft.
Beispiel
SELECT get_shard_id_for_distribution_column('my_table', 4);
get_shard_id_for_distribution_column
--------------------------------------
540007
(1 row)
column_to_column_name
Übersetzt die partkey
-Spalte von pg_dist_partition
in einen Textspaltennamen. Die Übersetzung ist hilfreich, um die Verteilungsspalte einer verteilten Tabelle zu ermitteln.
Eine ausführlichere Erläuterung finden Sie unter Auswählen einer Verteilungsspalte.
Argumente
table_name: die verteilte Tabelle
column_var_text: Wert von partkey
in der Tabelle pg_dist_partition
Rückgabewert
Der Name der Verteilungsspalte von table_name
.
Beispiel
-- 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;
Ausgabe:
┌───────────────┐
│ dist_col_name │
├───────────────┤
│ company_id │
└───────────────┘
citus_relation_size
Ruft den von allen Shards der angegebenen verteilten Tabelle verwendeten Speicherplatz auf dem Datenträger ab. Der Speicherplatz auf dem Datenträger umfasst die Größe des „Hauptforks“, schließt jedoch die Sichtbarkeitszuordnung und die Zuordnung des freien Speicherplatzes für die Shards aus.
Argumente
logicalrelid: Der Name einer verteilten Tabelle.
Rückgabewert
Die Größe in Bytes als bigint-Wert.
Beispiel
SELECT pg_size_pretty(citus_relation_size('github_events'));
pg_size_pretty
--------------
23 MB
citus_table_size
Ruft den Speicherplatz auf dem Datenträger ab, der von allen Shards der angegebenen verteilten Tabelle verwendet wird, ausschließlich der Indizes (jedoch einschließlich TOAST, Zuordnung des freien Speicherplatzes und Sichtbarkeitszuordnung).
Argumente
logicalrelid: Der Name einer verteilten Tabelle.
Rückgabewert
Die Größe in Bytes als bigint-Wert.
Beispiel
SELECT pg_size_pretty(citus_table_size('github_events'));
pg_size_pretty
--------------
37 MB
citus_total_relation_size
Ruft den Speicherplatz auf dem Datenträger ab, der von allen Shards der angegebenen verteilten Tabelle verwendet wird, einschließlich aller Indizes und TOAST-Daten.
Argumente
logicalrelid: Der Name einer verteilten Tabelle.
Rückgabewert
Die Größe in Bytes als bigint-Wert.
Beispiel
SELECT pg_size_pretty(citus_total_relation_size('github_events'));
pg_size_pretty
--------------
73 MB
citus_stat_statements_reset
Entfernt alle Zeilen aus citus_stat_statements.
Diese Funktion funktioniert unabhängig von pg_stat_statements_reset()
. Um alle Statistiken zurückzusetzen, rufen Sie beide Funktionen auf.
Argumente
Nicht zutreffend
Rückgabewert
Keiner
citus_get_active_worker_nodes
Mit der Funktion „citus_get_active_worker_nodes()“ wird eine Liste mit Hostnamen und Portnummern aktiver Worker zurückgegeben.
Argumente
Nicht zutreffend
Rückgabewert
Liste der Tupel, wobei jedes Tupel die folgenden Informationen enthält:
node_name: DNS-Name des Workerknotens
node_port: Port im Workerknoten, auf dem der Datenbankserver lauscht
Beispiel
SELECT * from citus_get_active_worker_nodes();
node_name | node_port
-----------+-----------
localhost | 9700
localhost | 9702
localhost | 9701
(3 rows)
Clusterverwaltung und -reparatur
master_copy_shard_placement
Wenn eine Shardplatzierung bei einem Änderungsbefehl oder einem DDL-Vorgang nicht aktualisiert werden kann, wird sie als inaktiv markiert. Die Funktion „master_copy_shard_placement“ kann dann aufgerufen werden, um eine inaktive Shardplatzierung mithilfe von Daten aus einer fehlerfreien Platzierung zu reparieren.
Zum Reparieren eines Shards löscht die Funktion zuerst die fehlerhafte Shardplatzierung und erstellt sie mithilfe des Schemas für den Koordinator neu. Nachdem die Shardplatzierung erstellt wurde, kopiert die Funktion Daten aus der fehlerfreien Platzierung und aktualisiert die Metadaten, um die neue Shardplatzierung als fehlerfrei zu markieren. Diese Funktion stellt sicher, dass der Shard vor gleichzeitigen Änderungen während der Reparatur geschützt wird.
Argumente
shard_id: ID des zu reparierenden Shards
source_node_name: DNS-Name des Knotens, auf dem die fehlerfreie Shardplatzierung vorhanden ist (Quellknoten)
source_node_port: Port auf dem Quellworkerknoten, an dem der Datenbankserver lauscht
target_node_name: DNS-Name des Knotens, auf dem die ungültige Shardplatzierung vorhanden ist (Zielknoten)
target_node_port: Port auf dem Zielworkerknoten, an dem der Datenbankserver lauscht
Rückgabewert
Nicht zutreffend
Beispiel
Im folgenden Beispiel wird eine inaktive Shardplatzierung von Shard 12345 repariert, die sich auf dem Datenbankserver befindet, der für „bad_host“ an Port 5432 ausgeführt wird. Um sie zu reparieren, werden Daten aus einer fehlerfreien Shardplatzierung auf dem Server verwendet, der für „good_host“ an Port 5432 ausgeführt wird.
SELECT master_copy_shard_placement(12345, 'good_host', 5432, 'bad_host', 5432);
master_move_shard_placement
Diese Funktion verschiebt einen angegebenen Shard (und darin verbundene Shards) von einem Knoten auf einen anderen. Sie wird in der Regel indirekt beim Shardausgleich verwendet, anstatt direkt von einem Datenbankadministrator aufgerufen zu werden.
Es gibt zwei Möglichkeiten, die Daten zu verschieben: blockierend oder nicht blockierend. Der Blockierungsansatz bedeutet, dass während der Verschiebung alle Änderungen am Shard angehalten werden. Die zweite Möglichkeit, mit der das Blockieren von Shardschreibvorgängen vermieden wird, beruht auf logischer Postgres 10-Replikation.
Nach einem erfolgreichen Verschiebevorgang werden Shards im Quellknoten gelöscht. Wenn die Verschiebung zu einem beliebigen Zeitpunkt fehlschlägt, löst diese Funktion einen Fehler aus, und die Quell- und Zielknoten bleiben unverändert.
Argumente
shard_id: ID des zu verschiebenden Shards
source_node_name: DNS-Name des Knotens, auf dem die fehlerfreie Shardplatzierung vorhanden ist (Quellknoten)
source_node_port: Port auf dem Quellworkerknoten, an dem der Datenbankserver lauscht
target_node_name: DNS-Name des Knotens, auf dem die ungültige Shardplatzierung vorhanden ist (Zielknoten)
target_node_port: Port auf dem Zielworkerknoten, an dem der Datenbankserver lauscht
shard_transfer_mode: (optional) Geben Sie die Replikationsmethode an: logische PostgreSQL-Replikation oder einen workerübergreifenden COPY-Befehl. Mögliche Werte sind:
auto
: Erfordert Replikatidentität, wenn logische Replikation möglich ist, andernfalls wird das Legacyverhalten (für Shardreparatur z. B. PostgreSQL 9.6) verwendet. Dies ist der Standardwert.force_logical
: Verwendet logische Replikation auch dann, wenn die Tabelle keine Replikatidentität besitzt. Alle gleichzeitigen update/delete-Anweisungen für die Tabelle schlagen während der Replikation fehl.block_writes
: Verwenden Sie COPY (blockierende Schreibvorgänge) für Tabellen, die keinen Primärschlüssel oder keine Replikatidentität aufweisen.
Rückgabewert
Nicht zutreffend
Beispiel
SELECT master_move_shard_placement(12345, 'from_host', 5432, 'to_host', 5432);
rebalance_table_shards
Die Funktion „rebalance_table_shards()“ verschiebt Shards der angegebenen Tabelle, damit sie gleichmäßig auf die Worker verteilt werden. Die Funktion berechnet zunächst die Liste der erforderlichen Verschiebungen, um sicherzustellen, dass der Cluster innerhalb des angegebenen Schwellenwerts ausgeglichen ist. Anschließend werden die Shardplatzierungen nacheinander vom Quellknoten auf den Zielknoten verschoben, und die entsprechenden Shardmetadaten werden aktualisiert, um die Verschiebung widerzuspiegeln.
Jedem Shard werden Kosten zugewiesen, wenn ermittelt wird, ob Shards gleichmäßig verteilt sind. Standardmäßig weist jeder Shard die gleichen Kosten (den Wert 1) auf. Daher ist die Verteilung zum Ausgleichen der Kosten auf mehrere Worker identisch mit dem Ausgleichen der Anzahl der Shards für jeden Worker. Die konstante Kostenstrategie wird als „by_shard_count“ bezeichnet und ist die standardmäßige Ausgleichsstrategie.
Die Strategie „by_shard_count“ ist unter den folgenden Umständen angemessen:
- Die Shards weisen ungefähr dieselbe Größe auf.
- Die Shards erhalten ungefähr die gleiche Menge an Datenverkehr.
- Die Workerknoten weisen alle dieselbe Größe bzw. denselben Typ auf.
- Shards wurden nicht an bestimmte Worker angeheftet.
Wenn eine dieser Annahmen nicht zutrifft, dann kann der Neuausgleich von „by_shard_count“ zu einem schlechten Plan führen.
Die Standardstrategie für den Neuausgleich ist „by_disk_size“. Sie können die Strategie stets anpassen, indem Sie den Parameter rebalance_strategy
verwenden.
Es empfiehlt sich, get_rebalance_table_shards_plan aufzurufen, bevor Sie „rebalance_table_shards“ ausführen, um die auszuführenden Aktionen anzuzeigen und zu überprüfen.
Argumente
table_name: (optional) Name der Tabelle, deren Shards ausgeglichen werden müssen. Wenn der Wert NULL ist, werden alle vorhandenen Colocationsgruppen ausgeglichen.
threshold: (Optional) Eine Gleitkommazahl zwischen 0,0 und 1,0, die das maximale Differenzverhältnis der Knotenverwendung von der durchschnittlichen Auslastung angibt. Wenn Sie z. B. 0,1 angeben, versucht der Shardrebalancer, alle Knoten so auszugleichen, dass sie die gleiche Anzahl von Shards (± 10 %) enthalten. Der Shardrebalancer versucht insbesondere, die Auslastung aller Workerknoten auf den (1 - Schwellenwert) × average_utilization ... (1
- Schwellenwert) × average_utilization anzugleichen.
max_shard_moves: (optional) maximale Anzahl der zu verschiebenden Shards
excluded_shard_list: (optional) Bezeichner von Shards, die während des Vorgangs zum erneuten Ausgleichen nicht verschoben werden sollten
shard_transfer_mode: (optional) Geben Sie die Replikationsmethode an: logische PostgreSQL-Replikation oder einen workerübergreifenden COPY-Befehl. Mögliche Werte sind:
auto
: Erfordert Replikatidentität, wenn logische Replikation möglich ist, andernfalls wird das Legacyverhalten (für Shardreparatur z. B. PostgreSQL 9.6) verwendet. Dies ist der Standardwert.force_logical
: Verwendet logische Replikation auch dann, wenn die Tabelle keine Replikatidentität besitzt. Alle gleichzeitigen update/delete-Anweisungen für die Tabelle schlagen während der Replikation fehl.block_writes
: Verwenden Sie COPY (blockierende Schreibvorgänge) für Tabellen, die keinen Primärschlüssel oder keine Replikatidentität aufweisen.
drain_only: (optional) beim Wert TRUE werden Shards von Workerknoten verschoben, für die shouldhaveshards
in pg_dist_node auf FALSE festgelegt ist. Andere Shards werden nicht verschoben.
rebalance_strategy: (optional) Name einer Strategie in pg_dist_rebalance_strategy. Wenn dieses Argument ausgelassen wird, wählt die Funktion die Standardstrategie (wie in der Tabelle angegeben) aus.
Rückgabewert
Nicht zutreffend
Beispiel
Im folgenden Beispiel wird versucht, die Shards in der Tabelle „github_events“ innerhalb des Standardschwellenwerts auszugleichen.
SELECT rebalance_table_shards('github_events');
In diesem Beispiel wird versucht, die Tabelle „github_events“ neu auszugleichen, ohne Shards mit der ID 1 und 2 zu verschieben.
SELECT rebalance_table_shards('github_events', excluded_shard_list:='{1,2}');
get_rebalance_table_shards_plan
Gibt die geplanten Shardbewegungen von rebalance_table_shards aus, ohne sie auszuführen. Es ist zwar unwahrscheinlich, aber „get_rebalance_table_shards_plan“ kann einen etwas anderen Plan ausgeben als ein Aufruf von „rebalance_table_shards“ mit den gleichen Argumenten. Die Aufrufe werden nicht gleichzeitig ausgeführt, sodass sich Fakten zum Cluster (z. B. der Speicherplatz) auf dem Datenträger möglicherweise zwischen den Aufrufen unterscheiden.
Argumente
Dieselben Argumente wie bei „rebalance_table_shards“: relation, threshold, max_shard_moves, excluded_shard_list und drain_only. Die Bedeutung der Argumente finden Sie in der Dokumentation der jeweiligen Funktion.
Rückgabewert
Tupel, die die folgenden Spalten enthalten:
- table_name: Tabelle, deren Shards verschoben werden
- shardid: Der jeweilige Shard.
- shard_size: Größe in Byte
- sourcename: Der Hostname des Quellknotens.
- sourceport: Der Port des Quellknotens.
- targetname: Der Hostname des Zielknotens.
- targetport: Der Port des Zielknotens.
get_rebalance_progress
Nachdem ein Shardausgleich begonnen wurde, listet die get_rebalance_progress()
-Funktion den Fortschritt aller beteiligten Shards auf. Sie überwacht die geplanten und von rebalance_table_shards()
ausgeführten Verschiebungen.
Argumente
Nicht zutreffend
Rückgabewert
Tupel, die die folgenden Spalten enthalten:
- sessionid: Die Postgres-PID des Ausgleichsmonitors.
- table_name: Tabelle, deren Shards verschoben werden
- shardid: Der jeweilige Shard.
- shard_size: Größe in Byte
- sourcename: Der Hostname des Quellknotens.
- sourceport: Der Port des Quellknotens.
- targetname: Der Hostname des Zielknotens.
- targetport: Der Port des Zielknotens.
- progress: 0 = auf Verschiebung wird gewartet, 1 = wird verschoben; 2 = abgeschlossen
Beispiel
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
Fügt pg_dist_rebalance_strategy eine Zeile hinzu.
Argumente
Weitere Informationen zu diesen Argumenten finden Sie in den entsprechenden Spaltenwerten in pg_dist_rebalance_strategy
.
name: Bezeichner für die neue Strategie.
shard_cost_function: gibt die Funktion an, mit der die „Kosten“ der einzelnen Shards bestimmt werden
node_capacity_function: gibt die Funktion zum Messen der Knotenkapazitätapazität an
shard_allowed_on_node_function: gibt die Funktion an, die ermittelt, welche Shards auf welchen Knoten platziert werden können
default_threshold: Gleitkommaschwellenwert, der optimiert, wie genau die kumulierten Shardkosten zwischen den Knoten ausgeglichen werden sollen
minimum_threshold: (optional) Schutzspalte, die den Mindestwert enthält, der für das Schwellenwertargument von „rebalance_table_shards()“ zulässig ist. Der Standardwert ist 0.
Rückgabewert
Nicht zutreffend
citus_set_default_rebalance_strategy
Aktualisiert die pg_dist_rebalance_strategy-Tabelle und ändern die durch das Argument benannte Strategie so, dass sie beim erneuten Ausgleichen von Shards als Standard ausgewählt wird.
Argumente
name: Name einer Strategie in „pg_dist_rebalance_strategy“
Rückgabewert
Nicht zutreffend
Beispiel
SELECT citus_set_default_rebalance_strategy('by_disk_size');
citus_remote_connection_stats
Die Funktion „citus_remote_connection_stats“ zeigt die Anzahl der aktiven Verbindungen mit den einzelnen Remoteknoten an.
Argumente
Nicht zutreffend
Beispiel
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
Diese Funktion erstellt einen neuen Shard, der Zeilen mit einem bestimmten einzelnen Wert in der Verteilungsspalte enthält. Dies ist besonders nützlich für den Anwendungsfall mit mehreren Mandanten, bei dem ein großer Mandant allein in seinem eigenen Shard und damit auf seinem eigenen physischen Knoten platziert werden kann.
Argumente
table_name: Name der Tabelle, um einen neuen Shard abzurufen
tenant_id: Wert der Verteilungsspalte, der dem neuen Shard zugewiesen wird
cascade_option: (optional) Wenn diese Option auf CASCADE festgelegt ist, wird auch einen Shard aus allen Tabellen in der Colocationsguppe der aktuellen Tabelle isoliert.
Rückgabewert
shard_id: Die Funktion gibt die eindeutige ID zurück, die dem neu erstellten Shard zugewiesen ist.
Beispiele
Erstellen Sie einen neuen Shard, der die lineitems für den Mandanten 135 enthalten soll:
SELECT isolate_tenant_to_new_shard('lineitem', 135);
┌─────────────────────────────┐
│ isolate_tenant_to_new_shard │
├─────────────────────────────┤
│ 102240 │
└─────────────────────────────┘
Nächste Schritte
- Viele der Funktionen in diesem Artikel ändern Metadatentabellen des Systems.
- Serverparameter passen das Verhalten einiger Funktionen an.