Azure Cosmos DB for PostgreSQL-functies
VAN TOEPASSING OP: 
Azure Cosmos DB for PostgreSQL (mogelijk gemaakt door de Citus-database-extensie naar PostgreSQL)
Deze sectie bevat naslaginformatie over de door de gebruiker gedefinieerde functies van Azure Cosmos DB for PostgreSQL. Deze functies helpen bij het bieden van gedistribueerde functionaliteit aan Azure Cosmos DB for PostgreSQL.
Notitie
clusters met oudere versies van de Citus Engine bieden mogelijk niet alle functies die op deze pagina worden vermeld.
Tabel en Shard DDL
citus_schema_distribute
Converteert bestaande reguliere schema's naar gedistribueerde schema's. Gedistribueerde schema's worden automatisch gekoppeld aan afzonderlijke colocatiegroepen. Tabellen die in deze schema's worden gemaakt, worden geconverteerd naar gedistribueerde tabellen met een puntkomma zonder shardsleutel. Het proces voor het distribueren van het schema wordt automatisch toegewezen en verplaatst naar een bestaand knooppunt in het cluster.
Argumenten
schemanaam: naam van het schema, dat moet worden gedistribueerd.
Retourwaarde
N.v.t.
Opmerking
SELECT citus_schema_distribute('tenant_a');
SELECT citus_schema_distribute('tenant_b');
SELECT citus_schema_distribute('tenant_c');
Zie instructies voor microservices voor meer voorbeelden.
citus_schema_undistribute
Converteert een bestaand gedistribueerd schema terug naar een normaal schema. Het proces resulteert in de tabellen en gegevens die van het huidige knooppunt worden verplaatst naar het coördinatorknooppunt in het cluster.
Argumenten
schemanaam: naam van het schema, dat moet worden gedistribueerd.
Retourwaarde
N.v.t.
Opmerking
SELECT citus_schema_undistribute('tenant_a');
SELECT citus_schema_undistribute('tenant_b');
SELECT citus_schema_undistribute('tenant_c');
Zie instructies voor microservices voor meer voorbeelden.
create_distributed_table
De functie create_distributed_table() wordt gebruikt om een gedistribueerde tabel te definiëren en de shards te maken als het een hash-gedistribueerde tabel is. Deze functie neemt een tabelnaam, de distributiekolom en een optionele distributiemethode in en voegt de juiste metagegevens in om de tabel als gedistribueerd te markeren. De functie wordt standaard ingesteld op hash-distributie als er geen distributiemethode is opgegeven. Als de tabel hash-gedistribueerd is, maakt de functie ook werkrol-shards op basis van het aantal shards en configuratiewaarden voor shard-replicatiefactor. Als de tabel rijen bevat, worden deze automatisch gedistribueerd naar werkknooppunten.
Deze functie vervangt het gebruik van master_create_distributed_table() gevolgd door master_create_worker_shards().
Argumenten
table_name: naam van de tabel die moet worden gedistribueerd.
distribution_column: De kolom waarop de tabel moet worden gedistribueerd.
distribution_type: (optioneel) De methode waarop de tabel moet worden gedistribueerd. Toegestane waarden worden toegevoegd of hash, met een standaardwaarde van 'hash'.
colocate_with: (Optioneel) bevatten de huidige tabel in de colocatiegroep van een andere tabel. Standaard worden tabellen op een punt weergegeven wanneer ze worden gedistribueerd door kolommen van hetzelfde type, hetzelfde aantal shards hebben en dezelfde replicatiefactor hebben. Mogelijke waarden zijn colocate_withdefault, none om een nieuwe colocatiegroep te starten, of de naam van een andere tabel die met die tabel moet worden geplaatst. (Zie tabelcolocatie.)
Houd er rekening mee dat de standaardwaarde van colocate_with impliciete colocatie wordt uitgevoerd. Colocatie kan handig zijn wanneer tabellen zijn gerelateerd of worden samengevoegd. Wanneer twee tabellen echter niet gerelateerd zijn, maar hetzelfde gegevenstype gebruiken voor hun distributiekolommen, kunnen ze per ongeluk de prestaties verminderen tijdens het opnieuw verdelen van shards. De tabelshards worden onnodig samengebracht in een 'trapsgewijs'.
Als een nieuwe gedistribueerde tabel niet is gerelateerd aan andere tabellen, kunt u het beste opgeven colocate_with => 'none'.
shard_count: (optioneel) het aantal shards dat moet worden gemaakt voor de nieuwe gedistribueerde tabel. Wanneer u opgeeft shard_count , kunt u geen andere waarde dan geen waarde colocate_with opgeven. Als u het aantal shards van een bestaande tabel of colocatiegroep wilt wijzigen, gebruikt u de functie alter_distributed_table .
Mogelijke waarden shard_count zijn tussen 1 en 64000. Zie Shard Count voor hulp bij het kiezen van de optimale waarde.
Retourwaarde
N.v.t.
Opmerking
In dit voorbeeld wordt de database geïnformeerd dat de github_events tabel moet worden gedistribueerd per hash in de kolom 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
Deze functie heeft dezelfde interface en hetzelfde doel als create_distributed_function, maar blokkeert geen schrijfbewerkingen tijdens de tabeldistributie.
create_distributed_table_concurrently Er gelden echter enkele beperkingen:
- U kunt de functie niet gebruiken in een transactieblok, wat betekent dat u slechts één tabel tegelijk kunt distribueren. (U kunt de functie echter gebruiken voor tabellen met tijdpartitionering.)
- U kunt niet gebruiken
create_distributed_table_concurrentlywanneer naar de tabel wordt verwezen door een refererende sleutel of verwijst naar een andere lokale tabel. Refererende sleutels om te verwijzen naar tabellen werken echter wel en u kunt refererende sleutels maken voor andere gedistribueerde tabellen nadat de tabeldistributie is voltooid. - Als u geen primaire sleutel of replica-identiteit in uw tabel hebt, mislukken opdrachten bijwerken en verwijderen tijdens de tabeldistributie vanwege beperkingen voor logische replicatie.
truncate_local_data_after_distributing_table
Kap alle lokale rijen af na het distribueren van een tabel en voorkom dat beperkingen mislukken vanwege verouderde lokale records. De afkapping trapsgewijs af op tabellen met een refererende sleutel voor de aangewezen tabel. Als de verwijzende tabellen niet zelf worden gedistribueerd, is afkappen verboden totdat ze zijn, om referentiële integriteit te beschermen:
ERROR: cannot truncate a table referenced in a foreign key constraint by a local table
Het afkappen van lokale coördinatorknooppunttabelgegevens is veilig voor gedistribueerde tabellen, omdat hun rijen, indien aanwezig, tijdens de distributie naar werkknooppunten worden gekopieerd.
Argumenten
table_name: Naam van de gedistribueerde tabel waarvan de lokale tegenhanger op het coördinatorknooppunt moet worden afgekapt.
Retourwaarde
N.v.t.
Opmerking
-- requires that argument is a distributed table
SELECT truncate_local_data_after_distributing_table('public.github_events');
create_reference_table
De functie create_reference_table() wordt gebruikt om een kleine verwijzings- of dimensietabel te definiëren. Deze functie neemt een tabelnaam in beslag en maakt een gedistribueerde tabel met slechts één shard, gerepliceerd naar elk werkknooppunt.
Argumenten
table_name: naam van de kleine dimensie of referentietabel die moet worden gedistribueerd.
Retourwaarde
N.v.t.
Opmerking
In dit voorbeeld wordt de database geïnformeerd dat de nationale tabel moet worden gedefinieerd als referentietabel
SELECT create_reference_table('nation');
citus_add_local_table_to_metadata
Voegt een lokale Postgres-tabel toe aan Citus-metagegevens. Een belangrijke use-case voor deze functie is om lokale tabellen in de coördinator toegankelijk te maken vanaf elk knooppunt in het cluster. De gegevens die aan de lokale tabel zijn gekoppeld, blijven op de coördinator staan. Alleen het schema en de metagegevens worden naar de werknemers verzonden.
Het toevoegen van lokale tabellen aan de metagegevens kost iets. Wanneer u de tabel toevoegt, moet Citus deze bijhouden in de partitietabel. Lokale tabellen die aan metagegevens worden toegevoegd, nemen dezelfde beperkingen over als referentietabellen.
Wanneer u de tabel ontkoppelt, verwijdert Citus de resulterende lokale tabellen uit metagegevens, waardoor dergelijke beperkingen voor deze tabellen worden geëlimineerd.
Argumenten
table_name: Naam van de tabel op de coördinator die moet worden toegevoegd aan citus-metagegevens.
cascade_via_foreign_keys: (Optioneel) Wanneer dit argument is ingesteld op 'true', citus_add_local_table_to_metadata andere tabellen die zich in een refererende-sleutelrelatie met de gegeven tabel bevinden, automatisch in metagegevens worden toegevoegd. Wees voorzichtig met deze parameter, omdat deze mogelijk van invloed kan zijn op veel tabellen.
Retourwaarde
N.v.t.
Opmerking
In dit voorbeeld wordt de database geïnformeerd dat de natietabel moet worden gedefinieerd als een coördinatortabel die toegankelijk is vanaf elk knooppunt:
SELECT citus_add_local_table_to_metadata('nation');
alter_distributed_table
De functie alter_distributed_table() kan worden gebruikt om de eigenschappen van de distributiekolom, het aantal shards of de colocatie van een gedistribueerde tabel te wijzigen.
Argumenten
table_name: naam van de tabel die wordt gewijzigd.
distribution_column: (Optioneel) Naam van de nieuwe distributiekolom.
shard_count: (optioneel) Het nieuwe aantal shards.
colocate_with: (optioneel) De tabel waarmee de huidige gedistribueerde tabel wordt geplaatst. Mogelijke waarden zijn default, none om een nieuwe colocatiegroep te starten of de naam van een andere tabel waarmee een punt moet worden geplaatst. (Zie tabelcolocatie.)
cascade_to_colocated: (Optioneel) Wanneer dit argument is ingesteld op 'true', shard_count worden colocate_with wijzigingen ook toegepast op alle tabellen die eerder zijn geplaatst met de tabel en blijft de colocatie behouden. Als deze 'onwaar' is, wordt de huidige colocatie van deze tabel verbroken.
Retourwaarde
N.v.t.
Opmerking
-- 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
De functie update_distributed_table_colocation() wordt gebruikt om de colocatie van een gedistribueerde tabel bij te werken. Deze functie kan ook worden gebruikt om colocatie van een gedistribueerde tabel te verbreken. Azure Cosmos DB for PostgreSQL plaatst impliciet twee tabellen als de distributiekolom hetzelfde type is. Dit kan handig zijn als de tabellen gerelateerd zijn en enkele joins uitvoeren. Als de tabellen A en B zijn geplaatst en tabel A opnieuw wordt verdeeld, wordt tabel B ook opnieuw verdeeld. Als tabel B geen replica-identiteit heeft, mislukt het opnieuw verdelen. Daarom kan deze functie nuttig zijn om de impliciete colocatie in dat geval te verbreken.
Met deze functie worden geen gegevens fysiek verplaatst.
Argumenten
table_name: de naam van de colocatie van de tabel waarvan deze wordt bijgewerkt.
colocate_with: De tabel waarmee de tabel moet worden geplaatst.
Als u de colocatie van een tabel wilt verbreken, moet u opgeven colocate_with => 'none'.
Retourwaarde
N.v.t.
Opmerking
In dit voorbeeld ziet u dat de colocatie van tabel A wordt bijgewerkt als colocatie van tabel B.
SELECT update_distributed_table_colocation('A', colocate_with => 'B');
Stel dat tabel A en tabel B zijn geplaatst (mogelijk impliciet), als u de colocatie wilt verbreken:
SELECT update_distributed_table_colocation('A', colocate_with => 'none');
Stel nu dat tabel A, tabel B, tabel C en tabel D een punt hebben en u de tabel A en tabel B samen wilt plaatsen, en tabel C en tabel D samen:
SELECT update_distributed_table_colocation('C', colocate_with => 'none');
SELECT update_distributed_table_colocation('D', colocate_with => 'C');
Als u een gedistribueerde hash-tabel met de naam geen hebt en u de colocatie wilt bijwerken, kunt u het volgende doen:
SELECT update_distributed_table_colocation('"none"', colocate_with => 'some_other_hash_distributed_table');
undistribute_table
Met de functie undistribute_table() wordt de actie van create_distributed_table of create_reference_table ongedaan gemaakt. Als u de distributie ongedaan maakt, worden alle gegevens van shards weer teruggezet naar een lokale tabel op het coördinatorknooppunt (ervan uitgaande dat de gegevens passen), waarna de shards worden verwijderd.
In Azure Cosmos DB for PostgreSQL worden tabellen waarnaar wordt verwezen door refererende sleutels niet ongedaan gemaakt, tenzij het argument cascade_via_foreign_keys is ingesteld op waar. Als dit argument onwaar (of weggelaten) is, moet u de beperkingen voor refererende sleutels handmatig verwijderen voordat u de distributie ongedaan maakt.
Argumenten
table_name: naam van de gedistribueerde of verwijzingstabel om niet te distribueren.
cascade_via_foreign_keys: (Optioneel) Wanneer dit argument is ingesteld op 'true', undistribute_table ook alle tabellen die zijn gerelateerd aan table_name via refererende sleutels, niet worden distribueren. Wees voorzichtig met deze parameter, omdat deze mogelijk van invloed kan zijn op veel tabellen.
Retourwaarde
N.v.t.
Opmerking
In dit voorbeeld wordt een github_events tabel gedistribueerd en wordt deze vervolgens ontkoppeld.
-- 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
Hiermee wordt een functie van het coördinatorknooppunt doorgegeven aan werkrollen en wordt deze gemarkeerd voor gedistribueerde uitvoering. Wanneer een gedistribueerde functie wordt aangeroepen voor de coördinator, gebruikt Azure Cosmos DB for PostgreSQL de waarde van het 'distributieargument' om een werkrolknooppunt te kiezen om de functie uit te voeren. Het uitvoeren van de functie op werkrollen verhoogt parallelle uitvoering en kan de code dichter bij gegevens in shards brengen voor lagere latentie.
Het Postgres-zoekpad wordt niet doorgegeven van de coördinator aan werkrollen tijdens het uitvoeren van gedistribueerde functies. Daarom moet gedistribueerde functiecode de namen van databaseobjecten volledig kwalificeren. Ook meldingen die door de functies worden verzonden, worden niet weergegeven aan de gebruiker.
Argumenten
function_name: naam van de functie die moet worden gedistribueerd. De naam moet de parametertypen van de functie tussen haakjes bevatten, omdat meerdere functies dezelfde naam kunnen hebben in PostgreSQL. Is bijvoorbeeld 'foo(int)' anders dan 'foo(int, text)'.
distribution_arg_name: (optioneel) De naam van het argument waarmee moet worden gedistribueerd. Voor het gemak (of als de functieargumenten geen namen hebben), is een positionele tijdelijke aanduiding toegestaan, zoals '$1'. Als deze parameter niet is opgegeven, wordt de functie met de naam function_name alleen gemaakt op de werkrollen. Als werkknooppunten in de toekomst worden toegevoegd, wordt de functie daar ook automatisch gemaakt.
colocate_with: (optioneel) Wanneer de gedistribueerde functie leest of schrijft naar een gedistribueerde tabel (of, meer algemeen, colocatiegroep), moet u die tabel een naam geven met behulp van de colocate_with parameter. Vervolgens wordt elke aanroep van de functie uitgevoerd op het werkknooppunt met relevante shards.
Retourwaarde
N.v.t.
Opmerking
-- 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
Met de functie alter_columnar_table_set() worden instellingen voor een kolomtabel gewijzigd. Het aanroepen van deze functie in een tabel zonder kolom geeft een fout. Alle argumenten behalve de tabelnaam zijn optioneel.
Raadpleeg deze tabel om de huidige opties voor alle kolomtabellen weer te geven:
SELECT * FROM columnar.options;
De standaardwaarden voor kolominstellingen voor nieuw gemaakte tabellen kunnen worden overschreven met deze GUC's:
- columnar.compression
- columnar.compression_level
- columnar.stripe_row_count
- columnar.chunk_row_count
Argumenten
table_name: Naam van de kolomtabel.
chunk_row_count: (optioneel) Het maximum aantal rijen per segment voor nieuw ingevoegde gegevens. Bestaande segmenten gegevens worden niet gewijzigd en hebben mogelijk meer rijen dan deze maximumwaarde. De standaardwaarde is 10000.
stripe_row_count: (optioneel) Het maximum aantal rijen per streep voor nieuw ingevoegde gegevens. Bestaande strepen met gegevens worden niet gewijzigd en hebben mogelijk meer rijen dan deze maximumwaarde. De standaardwaarde is 150000.
compressie: (optioneel) [none|pglz|zstd|lz4|lz4hc] Het compressietype voor nieuw ingevoegde gegevens. Bestaande gegevens worden niet opnieuw gecomprimeerd of gedecomprimeerd. De standaardwaarde en de voorgestelde waarde zijn zstd (als de ondersteuning is gecompileerd).
compression_level: (Optioneel) Geldige instellingen liggen tussen 1 en 19. Als de compressiemethode het gekozen niveau niet ondersteunt, wordt in plaats daarvan het dichtstbijzijnde niveau geselecteerd.
Retourwaarde
N.v.t.
Opmerking
SELECT alter_columnar_table_set(
'my_columnar_table',
compression => 'none',
stripe_row_count => 10000);
alter_table_set_access_method
De functie alter_table_set_access_method() wijzigt de toegangsmethode van een tabel (bijvoorbeeld heap of kolom).
Argumenten
table_name: naam van de tabel waarvan de toegangsmethode wordt gewijzigd.
access_method: naam van de nieuwe toegangsmethode.
Retourwaarde
N.v.t.
Opmerking
SELECT alter_table_set_access_method('github_events', 'columnar');
create_time_partitions
Met de functie create_time_partitions() worden partities van een bepaald interval gemaakt om een bepaald tijdsbereik te dekken.
Argumenten
table_name: (regclass)-tabel waarvoor nieuwe partities moeten worden gemaakt. De tabel moet worden gepartitioneerd op één kolom, van het type datum, tijdstempel of timestamptz.
partition_interval: een tijdsinterval, zoals '2 hours', of '1 month', om te gebruiken bij het instellen van bereiken voor nieuwe partities.
end_at: (timestamptz) maakt tot nu toe partities. De laatste partitie bevat het punt end_at en er worden geen latere partities gemaakt.
start_from: (timestamptz, optioneel) kiest u de eerste partitie, zodat deze het punt start_from bevat. De standaardwaarde is now().
Retourwaarde
Waar als het nodig is om nieuwe partities te maken, onwaar als ze allemaal al bestaan.
Opmerking
-- 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
Met de functie drop_old_time_partitions() worden alle partities verwijderd waarvan de intervallen vóór een bepaalde tijdstempel vallen. Naast het gebruik van deze functie kunt u overwegen alter_old_partitions_set_access_method om de oude partities te comprimeren met kolomopslag.
Argumenten
table_name: (regclass)-tabel waarvoor partities moeten worden verwijderd. De tabel moet worden gepartitioneerd op één kolom, van het type datum, tijdstempel of timestamptz.
older_than: (timestamptz)-partities waarvan het bovenste bereik kleiner is dan of gelijk is aan older_than.
Retourwaarde
N.v.t.
Opmerking
-- 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 een use-case voor tijdreeksen worden tabellen vaak gepartitioneerd op tijd en worden oude partities gecomprimeerd in alleen-lezen kolomopslag.
Argumenten
parent_table_name: (regclass)-tabel waarvoor partities moeten worden gewijzigd. De tabel moet worden gepartitioneerd op één kolom, van het type datum, tijdstempel of timestamptz.
older_than: (timestamptz) wijzigen partities waarvan het bovenste bereik kleiner is dan of gelijk is aan older_than.
new_access_method: (naam) 'heap' voor opslag op basis van rijen of kolom voor kolomopslag.
Retourwaarde
N.v.t.
Opmerking
CALL alter_old_partitions_set_access_method(
'foo', now() - interval '6 months',
'columnar'
);
Metagegevens/configuratiegegevens
get_shard_id_for_distribution_column
Azure Cosmos DB for PostgreSQL wijst elke rij van een gedistribueerde tabel toe aan een shard op basis van de waarde van de distributiekolom van de rij en de distributiemethode van de tabel. In de meeste gevallen is de nauwkeurige toewijzing een detail op laag niveau die de databasebeheerder kan negeren. Het kan echter handig zijn om de shard van een rij te bepalen, voor handmatige databaseonderhoudstaken of alleen om nieuwsgierigheid te bevredigen. De get_shard_id_for_distribution_column functie biedt deze informatie voor hash-gedistribueerde, bereik-gedistribueerde en referentietabellen. Het werkt niet voor de toevoegdistributie.
Argumenten
table_name: De gedistribueerde tabel.
distribution_value: de waarde van de distributiekolom.
Retourwaarde
De shard-id van Azure Cosmos DB for PostgreSQL wordt gekoppeld aan de waarde van de distributiekolom voor de opgegeven tabel.
Opmerking
SELECT get_shard_id_for_distribution_column('my_table', 4);
get_shard_id_for_distribution_column
--------------------------------------
540007
(1 row)
column_to_column_name
Hiermee wordt de partkey kolom pg_dist_partition omgezet in een tekstuele kolomnaam. De vertaling is handig om de distributiekolom van een gedistribueerde tabel te bepalen.
Zie een distributiekolom kiezen voor een gedetailleerdere discussie.
Argumenten
table_name: De gedistribueerde tabel.
column_var_text: de waarde van partkey de pg_dist_partition tabel.
Retourwaarde
De naam van table_namede distributiekolom.
Opmerking
-- 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;
Uitvoer:
┌───────────────┐
│ dist_col_name │
├───────────────┤
│ company_id │
└───────────────┘
citus_relation_size
Haal de schijfruimte op die wordt gebruikt door alle shards van de opgegeven gedistribueerde tabel. De schijfruimte bevat de grootte van de 'hoofdfork', maar sluit de zichtbaarheidstoewijzing en vrije ruimtetoewijzing voor de shards uit.
Argumenten
logicalrelid: de naam van een gedistribueerde tabel.
Retourwaarde
Grootte in bytes als bigint.
Opmerking
SELECT pg_size_pretty(citus_relation_size('github_events'));
pg_size_pretty
--------------
23 MB
citus_table_size
Haal de schijfruimte op die wordt gebruikt door alle shards van de opgegeven gedistribueerde tabel, met uitzondering van indexen (maar inclusief TOAST, vrije ruimtetoewijzing en zichtbaarheidskaart).
Argumenten
logicalrelid: de naam van een gedistribueerde tabel.
Retourwaarde
Grootte in bytes als bigint.
Opmerking
SELECT pg_size_pretty(citus_table_size('github_events'));
pg_size_pretty
--------------
37 MB
citus_total_relation_size
Haal de totale schijfruimte op die wordt gebruikt door alle shards van de opgegeven gedistribueerde tabel, inclusief alle indexen en TOAST-gegevens.
Argumenten
logicalrelid: de naam van een gedistribueerde tabel.
Retourwaarde
Grootte in bytes als bigint.
Opmerking
SELECT pg_size_pretty(citus_total_relation_size('github_events'));
pg_size_pretty
--------------
73 MB
citus_stat_statements_reset
Hiermee verwijdert u alle rijen uit citus_stat_statements.
Deze functie werkt onafhankelijk van pg_stat_statements_reset(). Als u alle statistieken opnieuw wilt instellen, roept u beide functies aan.
Argumenten
N.v.t.
Retourwaarde
Geen
citus_get_active_worker_nodes
De functie citus_get_active_worker_nodes() retourneert een lijst met actieve werkrolhostnamen en poortnummers.
Argumenten
N.v.t.
Retourwaarde
Lijst met tuples waarin elke tuple de volgende informatie bevat:
node_name: DNS-naam van het werkknooppunt
node_port: Poort op het werkknooppunt waarop de databaseserver luistert
Opmerking
SELECT * from citus_get_active_worker_nodes();
node_name | node_port
-----------+-----------
localhost | 9700
localhost | 9702
localhost | 9701
(3 rows)
Clusterbeheer en herstel
master_copy_shard_placement
Als een shardplaatsing niet kan worden bijgewerkt tijdens een wijzigingsopdracht of een DDL-bewerking, wordt deze gemarkeerd als inactief. De functie master_copy_shard_placement kan vervolgens worden aangeroepen om een inactieve shardplaatsing te herstellen met behulp van gegevens van een gezonde plaatsing.
Als u een shard wilt herstellen, verwijdert de functie eerst de beschadigde shardplaatsing en maakt deze opnieuw met behulp van het schema van de coördinator. Zodra de shardplaatsing is gemaakt, kopieert de functie gegevens van de plaatsing in orde en werkt de metagegevens bij om de nieuwe shardplaatsing als in orde te markeren. Deze functie zorgt ervoor dat de shard wordt beschermd tegen gelijktijdige wijzigingen tijdens de reparatie.
Argumenten
shard_id: id van de shard die moet worden hersteld.
source_node_name: DNS-naam van het knooppunt waarop de gezonde shardplaatsing aanwezig is (bronknooppunt).
source_node_port: de poort op het bronwerkrolknooppunt waarop de databaseserver luistert.
target_node_name: DNS-naam van het knooppunt waarop de ongeldige shardplaatsing aanwezig is (doelknooppunt).
target_node_port: de poort op het doelwerkknooppunt waarop de databaseserver luistert.
Retourwaarde
N.v.t.
Opmerking
In het onderstaande voorbeeld wordt een inactieve shardplaatsing van shard 12345 hersteld, die aanwezig is op de databaseserver die wordt uitgevoerd op bad_host op poort 5432. Om deze te herstellen, worden gegevens uit een gezonde shardplaatsing gebruikt die aanwezig is op de server die wordt uitgevoerd op 'good_host' op poort 5432.
SELECT master_copy_shard_placement(12345, 'good_host', 5432, 'bad_host', 5432);
master_move_shard_placement
Met deze functie wordt een bepaalde shard (en shards ermee) verplaatst van het ene knooppunt naar het andere. Deze wordt doorgaans indirect gebruikt tijdens het opnieuw verdelen van shards in plaats van rechtstreeks aan te roepen door een databasebeheerder.
Er zijn twee manieren om de gegevens te verplaatsen: blokkeren of niet-blokkeren. De blokkeringsmethode betekent dat tijdens het verplaatsen alle wijzigingen in de shard worden onderbroken. De tweede manier, waardoor shard-schrijfbewerkingen worden geblokkeerd, is afhankelijk van logische replicatie van Postgres 10.
Na een geslaagde verplaatsing worden shards in het bronknooppunt verwijderd. Als de verplaatsing op enig moment mislukt, genereert deze functie een fout en blijft de bron- en doelknooppunten ongewijzigd.
Argumenten
shard_id: id van de shard die moet worden verplaatst.
source_node_name: DNS-naam van het knooppunt waarop de gezonde shardplaatsing aanwezig is (bronknooppunt).
source_node_port: de poort op het bronwerkrolknooppunt waarop de databaseserver luistert.
target_node_name: DNS-naam van het knooppunt waarop de ongeldige shardplaatsing aanwezig is (doelknooppunt).
target_node_port: de poort op het doelwerkknooppunt waarop de databaseserver luistert.
shard_transfer_mode: (Optioneel) Geef de replicatiemethode op, of u nu logische PostgreSQL-replicatie of een opdracht COPY tussen werkrollen wilt gebruiken. Mogelijke waarden zijn:
auto: Replica-identiteit vereisen als logische replicatie mogelijk is, gebruik anders verouderd gedrag (bijvoorbeeld voor shardherstel, PostgreSQL 9.6). Dit is de standaardwaarde.force_logical: Gebruik logische replicatie, zelfs als de tabel geen replica-identiteit heeft. Eventuele gelijktijdige update-/verwijderinstructies voor de tabel mislukken tijdens de replicatie.block_writes: Gebruik COPY (blokkering van schrijfbewerkingen) voor tabellen die geen primaire sleutel of replica-identiteit hebben.
Retourwaarde
N.v.t.
Opmerking
SELECT master_move_shard_placement(12345, 'from_host', 5432, 'to_host', 5432);
rebalance_table_shards
Met de functie rebalance_table_shards() worden shards van de opgegeven tabel verplaatst om ze gelijkmatig over de werkrollen te verdelen. De functie berekent eerst de lijst met verplaatsingen die moeten worden uitgevoerd om ervoor te zorgen dat het cluster binnen de opgegeven drempelwaarde wordt verdeeld. Vervolgens worden shardplaatsingen één voor één verplaatst van het bronknooppunt naar het doelknooppunt en worden de bijbehorende shardmetagegevens bijgewerkt om de verplaatsing weer te geven.
Aan elke shard wordt een kosten toegewezen bij het bepalen of shards 'gelijkmatig verdeeld' zijn. Elke shard heeft standaard dezelfde kosten (een waarde van 1), dus het verdelen om de kosten voor alle werkrollen gelijk te maken, is hetzelfde als het gelijkmaken van het aantal shards op elk. De strategie voor constante kosten wordt 'by_shard_count' genoemd en is de standaardstrategie voor opnieuw verdelen.
De strategie 'by_shard_count' is geschikt onder deze omstandigheden:
- De shards hebben ongeveer dezelfde grootte
- De shards krijgen ongeveer dezelfde hoeveelheid verkeer
- Werkknooppunten hebben allemaal dezelfde grootte/hetzelfde type
- Shards zijn niet vastgemaakt aan bepaalde werkrollen
Als een van deze veronderstellingen niet vasthoudt, kan het opnieuw verdelen van 'by_shard_count' resulteren in een slecht plan.
De standaardstrategie voor opnieuw verdelen is 'by_disk_size'. U kunt de strategie altijd aanpassen met behulp van de rebalance_strategy parameter.
Het is raadzaam om get_rebalance_table_shards_plan aan te roepen voordat u rebalance_table_shards uitvoert, om de acties te bekijken en te controleren die moeten worden uitgevoerd.
Argumenten
table_name: (Optioneel) De naam van de tabel waarvan de shards opnieuw moeten worden gebalanceerd. Als NULL, moet u alle bestaande colocatiegroepen opnieuw verdelen.
drempelwaarde: (Optioneel) Een floatnummer tussen 0,0 en 1,0 dat de maximale verschilverhouding van het knooppuntgebruik aangeeft ten opzichte van het gemiddelde gebruik. Als u bijvoorbeeld 0.1 opgeeft, wordt de shard-herverdeling geprobeerd om alle knooppunten te verdelen over hetzelfde aantal shards ±10%. Met name probeert de shard-herbalancer het gebruik van alle werkknooppunten te convergeren naar de (1 - drempelwaarde) * average_utilization ... (1
- drempelwaarde) * average_utilization bereik.
max_shard_moves: (optioneel) Het maximum aantal shards dat moet worden verplaatst.
excluded_shard_list: (optioneel) id's van shards die niet moeten worden verplaatst tijdens de herbalance-bewerking.
shard_transfer_mode: (Optioneel) Geef de replicatiemethode op, of u nu logische PostgreSQL-replicatie of een opdracht COPY tussen werkrollen wilt gebruiken. Mogelijke waarden zijn:
auto: Replica-identiteit vereisen als logische replicatie mogelijk is, gebruik anders verouderd gedrag (bijvoorbeeld voor shardherstel, PostgreSQL 9.6). Dit is de standaardwaarde.force_logical: Gebruik logische replicatie, zelfs als de tabel geen replica-identiteit heeft. Eventuele gelijktijdige update-/verwijderinstructies voor de tabel mislukken tijdens de replicatie.block_writes: Gebruik COPY (blokkering van schrijfbewerkingen) voor tabellen die geen primaire sleutel of replica-identiteit hebben.
drain_only: (Optioneel) Wanneer waar, verplaatst u shards van werkknooppunten die zijn shouldhaveshards ingesteld op onwaar in pg_dist_node; verplaats geen andere shards.
rebalance_strategy: (optioneel) de naam van een strategie in pg_dist_rebalance_strategy. Als dit argument wordt weggelaten, kiest de functie de standaardstrategie, zoals aangegeven in de tabel.
Retourwaarde
N.v.t.
Opmerking
In het onderstaande voorbeeld wordt geprobeerd de shards van de github_events tabel binnen de standaarddrempelwaarde opnieuw te verdelen.
SELECT rebalance_table_shards('github_events');
In dit voorbeeld wordt geprobeerd de github_events tabel opnieuw te verdelen zonder shards te verplaatsen met id 1 en 2.
SELECT rebalance_table_shards('github_events', excluded_shard_list:='{1,2}');
get_rebalance_table_shards_plan
Voer de geplande shardverplaatsingen van rebalance_table_shards uit zonder ze uit te voeren. Hoewel het onwaarschijnlijk is, kan get_rebalance_table_shards_plan een iets ander plan uitvoeren dan wat een rebalance_table_shards aanroep met dezelfde argumenten zal doen. Ze worden niet tegelijkertijd uitgevoerd, dus feiten over het cluster, bijvoorbeeld schijfruimte, kunnen verschillen tussen de aanroepen.
Argumenten
Dezelfde argumenten als rebalance_table_shards: relatie, drempelwaarde, max_shard_moves, excluded_shard_list en drain_only. Raadpleeg de documentatie van die functie voor de betekenis van de argumenten.
Retourwaarde
Tuples met deze kolommen:
- table_name: de tabel waarvan de shards worden verplaatst
- shardid: De shard in kwestie
- shard_size: Grootte in bytes
- bronnaam: Hostnaam van het bronknooppunt
- sourceport: Poort van het bronknooppunt
- targetname: Hostnaam van het doelknooppunt
- targetport: Poort van het doelknooppunt
get_rebalance_progress
Zodra een shard opnieuw wordt geherbalanceerd, geeft de get_rebalance_progress() functie de voortgang weer van elke betrokken shard. Het bewaakt de verplaatsingen gepland en uitgevoerd door rebalance_table_shards().
Argumenten
N.v.t.
Retourwaarde
Tuples met deze kolommen:
- sessionid: Postgres PID van de monitor voor opnieuw verdelen
- table_name: de tabel waarvan de shards worden verplaatst
- shardid: De shard in kwestie
- shard_size: Grootte in bytes
- bronnaam: Hostnaam van het bronknooppunt
- sourceport: Poort van het bronknooppunt
- targetname: Hostnaam van het doelknooppunt
- targetport: Poort van het doelknooppunt
- voortgang: 0 = wachten om te worden verplaatst; 1 = verplaatsen; 2 = voltooid
Opmerking
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
Voeg een rij toe aan pg_dist_rebalance_strategy .
Argumenten
Zie de bijbehorende kolomwaarden in pg_dist_rebalance_strategyvoor meer informatie over deze argumenten.
naam: id voor de nieuwe strategie
shard_cost_function: identificeert de functie die wordt gebruikt om de 'kosten' van elke shard te bepalen
node_capacity_function: identificeert de functie om de capaciteit van het knooppunt te meten
shard_allowed_on_node_function: identificeert de functie die bepaalt welke shards kunnen worden geplaatst op welke knooppunten
default_threshold: een drempelwaarde voor drijvende komma die aangeeft hoe precies de cumulatieve shardkosten moeten worden verdeeld tussen knooppunten
minimum_threshold: (Optioneel) een beveiligingskolom met de minimumwaarde die is toegestaan voor het drempelwaardeargument van rebalance_table_shards(). De standaardwaarde is 0
Retourwaarde
N.v.t.
citus_set_default_rebalance_strategy
Werk de pg_dist_rebalance_strategy tabel bij en wijzig de strategie met de naam van het argument in de standaardinstelling die wordt gekozen bij het opnieuw verdelen van shards.
Argumenten
naam: de naam van de strategie in pg_dist_rebalance_strategy
Retourwaarde
N.v.t.
Opmerking
SELECT citus_set_default_rebalance_strategy('by_disk_size');
citus_remote_connection_stats
De functie citus_remote_connection_stats() toont het aantal actieve verbindingen met elk extern knooppunt.
Argumenten
N.v.t.
Opmerking
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
Met deze functie maakt u een nieuwe shard voor het opslaan van rijen met één specifieke waarde in de distributiekolom. Het is vooral handig voor de multitenant-use-case, waarbij een grote tenant alleen op zijn eigen shard en uiteindelijk een eigen fysiek knooppunt kan worden geplaatst.
Argumenten
table_name: de naam van de tabel om een nieuwe shard op te halen.
tenant_id: de waarde van de distributiekolom die wordt toegewezen aan de nieuwe shard.
cascade_option: (Optioneel) Als deze optie is ingesteld op TRAPSGEWIJS, wordt ook een shard geïsoleerd van alle tabellen in de colocatiegroep van de huidige tabel.
Retourwaarde
shard_id: De functie retourneert de unieke id die is toegewezen aan de zojuist gemaakte shard.
Voorbeelden
Maak een nieuwe shard voor het opslaan van de lineitems voor tenant 135:
SELECT isolate_tenant_to_new_shard('lineitem', 135);
┌─────────────────────────────┐
│ isolate_tenant_to_new_shard │
├─────────────────────────────┤
│ 102240 │
└─────────────────────────────┘
Volgende stappen
- Veel van de functies in dit artikel wijzigen tabellen met systeemmetagegevens
- Serverparameters passen het gedrag van sommige functies aan