Azure Cosmos DB for PostgreSQL-funktioner

Artikel
10/27/2023

GÄLLER FÖR: Azure Cosmos DB for PostgreSQL (drivs av Citus-databastillägget till PostgreSQL)

Det här avsnittet innehåller referensinformation för de användardefinierade funktioner som tillhandahålls av Azure Cosmos DB för PostgreSQL. De här funktionerna hjälper dig att tillhandahålla distribuerade funktioner till Azure Cosmos DB for PostgreSQL.

Kommentar

kluster som kör äldre versioner av Citus-motorn kanske inte erbjuder alla funktioner som anges på den här sidan.

Tabell och Shard DDL

citus_schema_distribute

Konverterar befintliga vanliga scheman till distribuerade scheman. Distribuerade scheman associeras automatiskt med enskilda samlokaliseringsgrupper. Tabeller som skapats i dessa scheman konverteras till samallokerade distribuerade tabeller utan en shardnyckel. Processen för att distribuera schemat tilldelar och flyttar det automatiskt till en befintlig nod i klustret.

Argument

schemaname: Namnet på schemat, som måste distribueras.

Returvärde

Inte tillgängligt

Exempel

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

Fler exempel finns i hur du utformar för mikrotjänster.

citus_schema_undistribute

Konverterar ett befintligt distribuerat schema tillbaka till ett vanligt schema. Processen resulterar i att tabeller och data flyttas från den aktuella noden tillbaka till koordinatornoden i klustret.

Argument

schemaname: Namnet på schemat, som måste distribueras.

Returvärde

Inte tillgängligt

Exempel

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

Fler exempel finns i hur du utformar för mikrotjänster.

create_distributed_table

Funktionen create_distributed_table() används för att definiera en distribuerad tabell och skapa dess shards om det är en hash-distribuerad tabell. Den här funktionen tar in ett tabellnamn, en distributionskolumn och en valfri distributionsmetod och infogar lämpliga metadata för att markera tabellen som distribuerad. Funktionen är standard för "hash"-distribution om ingen distributionsmetod har angetts. Om tabellen är hash-distribuerad skapar funktionen även arbetsshards baserat på shardantalet och konfigurationsvärdena för shardreplikeringsfaktorn. Om tabellen innehåller några rader distribueras de automatiskt till arbetsnoder.

Den här funktionen ersätter användningen av master_create_distributed_table() följt av master_create_worker_shards().

Argument

table_name: Namnet på tabellen som måste distribueras.

distribution_column: Kolumnen där tabellen ska distribueras.

distribution_type: (Valfritt) Metoden enligt vilken tabellen ska distribueras. Tillåtna värden läggs till eller hash, med standardvärdet "hash".

colocate_with: (Valfritt) inkludera aktuell tabell i samlokaliseringsgruppen i en annan tabell. Som standard samallokeras tabeller när de distribueras av kolumner av samma typ, har samma shardantal och har samma replikeringsfaktor. Möjliga värden för är default, none för colocate_with att starta en ny samlokaliseringsgrupp eller namnet på en annan tabell som ska samlokaliseras med den tabellen. (Se tabellsamlokalisering.)

Tänk på att standardvärdet colocate_with för gör implicit samlokalisering. Samlokalisering kan vara en bra sak när tabeller är relaterade eller kommer att kopplas. Men när två tabeller är orelaterade men råkar använda samma datatyp för sina distributionskolumner kan oavsiktligt samlokalisering av dem minska prestanda vid horisontell ombalansering. Tabellskärvorna flyttas i onödan i en "kaskad".

Om en ny distribuerad tabell inte är relaterad till andra tabeller är det bäst att ange colocate_with => 'none'.

shard_count: (Valfritt) antalet shards som ska skapas för den nya distribuerade tabellen. När du anger shard_count kan du inte ange något annat värde colocate_with än inget. Om du vill ändra shardantalet för en befintlig tabell eller samlokaliseringsgrupp använder du funktionen alter_distributed_table .

Möjliga värden för shard_count är mellan 1 och 64000. Information om hur du väljer det optimala värdet finns i Shard Count(Shard Count).

Returvärde

Inte tillgängligt

Exempel

Det här exemplet informerar databasen om att den github_events tabellen ska distribueras med hash i kolumnen 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

Den här funktionen har samma gränssnitt och syfte som create_distributed_function, men blockerar inte skrivningar under tabelldistributionen.

Har dock create_distributed_table_concurrently några begränsningar:

Du kan inte använda funktionen i ett transaktionsblock, vilket innebär att du bara kan distribuera en tabell i taget. (Du kan dock använda funktionen i tidspartitionerade tabeller.)
Du kan inte använda create_distributed_table_concurrently när tabellen refereras till av en sekundärnyckel eller refererar till en annan lokal tabell. Sekundärnycklar till referenstabeller fungerar dock och du kan skapa sekundärnycklar till andra distribuerade tabeller när tabelldistributionen är klar.
Om du inte har någon primärnyckel eller replikidentitet i tabellen misslyckas kommandona för uppdatering och borttagning under tabelldistributionen på grund av begränsningar i den logiska replikeringen.

truncate_local_data_after_distributing_table

Trunkera alla lokala rader när du har distribuerat en tabell och förhindra att begränsningar misslyckas på grund av inaktuella lokala poster. Trunkeringen kaskader till tabeller som har en sekundärnyckel till den avsedda tabellen. Om de refererande tabellerna inte själva är distribuerade är trunkering förbjuden tills de är det, för att skydda referensintegriteten:

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

Trunkering av lokala koordinatornodtabelldata är säkert för distribuerade tabeller eftersom deras rader, om några, kopieras till arbetsnoder under distributionen.

Argument

table_name: Namnet på den distribuerade tabellen vars lokala motsvarighet på koordinatornoden ska trunkeras.

Returvärde

Inte tillgängligt

Exempel

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

create_reference_table

Funktionen create_reference_table() används för att definiera en liten referens- eller dimensionstabell. Den här funktionen tar in ett tabellnamn och skapar en distribuerad tabell med bara en shard som replikeras till varje arbetsnod.

Argument

table_name: Namnet på den lilla dimensionen eller referenstabellen som måste distribueras.

Returvärde

Inte tillgängligt

Exempel

Det här exemplet informerar databasen om att nationstabellen ska definieras som en referenstabell

SELECT create_reference_table('nation');

citus_add_local_table_to_metadata

Lägger till en lokal Postgres-tabell i Citus-metadata. Ett stort användningsfall för den här funktionen är att göra lokala tabeller på koordinatorn tillgängliga från valfri nod i klustret. De data som är associerade med den lokala tabellen finns kvar på koordinatorn – endast dess schema och metadata skickas till arbetarna.

Att lägga till lokala tabeller i metadata kostar något. När du lägger till tabellen måste Citus spåra den i partitionstabellen. Lokala tabeller som läggs till i metadata ärver samma begränsningar som referenstabeller.

När du inte distribuerar tabellen tar Citus bort de resulterande lokala tabellerna från metadata, vilket eliminerar sådana begränsningar för dessa tabeller.

Argument

table_name: Namnet på tabellen på koordinatorn som ska läggas till i Citus-metadata.

cascade_via_foreign_keys: (Valfritt) När det här argumentet är inställt på "true" lägger citus_add_local_table_to_metadata till andra tabeller som är i en sekundärnyckelrelation med angiven tabell i metadata automatiskt. Var försiktig med den här parametern eftersom det kan påverka många tabeller.

Returvärde

Inte tillgängligt

Exempel

Det här exemplet informerar databasen om att nationstabellen ska definieras som en koordinatorlokal tabell som är tillgänglig från valfri nod:

SELECT citus_add_local_table_to_metadata('nation');

alter_distributed_table

Funktionen alter_distributed_table() kan användas för att ändra distributionskolumnen, shardantalet eller samlokaliseringsegenskaperna för en distribuerad tabell.

Argument

table_name: Namnet på tabellen som ska ändras.

distribution_column: (Valfritt) Namn på den nya distributionskolumnen.

shard_count: (Valfritt) Det nya antalet fragment.

colocate_with: (Valfritt) Tabellen som den aktuella distribuerade tabellen kommer att samallokeras med. Möjliga värden är default, none för att starta en ny samlokaliseringsgrupp eller namnet på en annan tabell som ska samlokaliseras med. (Se tabellsamlokalisering.)

cascade_to_colocated: (Valfritt) När det här argumentet är inställt på "true" shard_count och colocate_with ändringar också tillämpas på alla tabeller som tidigare var samlokaliserade med tabellen, och samlokaliseringen bevaras. Om det är "false" kommer den aktuella samlokaliseringen av den här tabellen att brytas.

Returvärde

Inte tillgängligt

Exempel

-- 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

Funktionen update_distributed_table_colocation() används för att uppdatera samlokaliseringen av en distribuerad tabell. Den här funktionen kan också användas för att bryta samlokaliseringen av en distribuerad tabell. Azure Cosmos DB for PostgreSQL kommer implicit att samplacera två tabeller om distributionskolumnen är av samma typ, detta kan vara användbart om tabellerna är relaterade och kommer att göra några kopplingar. Om tabellerna A och B samallokeras och tabell A balanseras om balanseras även tabell B om. Om tabell B inte har någon replikidentitet misslyckas ombalanseringen. Därför kan den här funktionen vara användbar när du bryter den implicita samlokaliseringen i det fallet.

Den här funktionen flyttar inte några data fysiskt.

Argument

table_name: Namnet på tabellens samlokalisering som kommer att uppdateras.

colocate_with: Tabellen som tabellen ska samallokeras till.

Om du vill bryta samlokaliseringen av en tabell bör du ange colocate_with => 'none'.

Returvärde

Inte tillgängligt

Exempel

Det här exemplet visar att samlokaliseringen av tabell A uppdateras som samlokalisering av tabell B.

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

Anta att tabell A och tabell B är samallokerade (möjligen implicit), om du vill bryta samlokaliseringen:

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

Anta nu att tabell A, tabell B, tabell C och tabell D är samallokerade och att du vill samplacera tabell A och tabell B tillsammans och tabell C och tabell D tillsammans:

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

Om du har en hash-distribuerad tabell med namnet none och du vill uppdatera dess samlokalisering kan du göra:

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

undistribute_table

Funktionen undistribute_table() återställer åtgärden för create_distributed_table eller create_reference_table. Om du inte distribuerar flyttas alla data från shards tillbaka till en lokal tabell på koordinatornoden (förutsatt att data får plats) och tar sedan bort fragmenten.

Azure Cosmos DB for PostgreSQL distribuerar inte tabeller som har eller refereras till av sekundärnycklar, såvida inte argumentet cascade_via_foreign_keys är inställt på sant. Om det här argumentet är falskt (eller utelämnat) måste du manuellt ta bort de felaktiga begränsningarna för sekundärnyckeln innan du inte distribuerar.

Argument

table_name: Namnet på den distribuerade tabellen eller referenstabellen som ska distribueras utan distribution.

cascade_via_foreign_keys: (Valfritt) När det här argumentet är inställt på "sant" undistribute_table även icke-distribuerar alla tabeller som är relaterade till table_name via sekundärnycklar. Var försiktig med den här parametern eftersom det kan påverka många tabeller.

Returvärde

Inte tillgängligt

Exempel

Det här exemplet distribuerar en github_events tabell och distribuerar den sedan.

-- 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

Sprider en funktion från koordinatornoden till arbetare och markerar den för distribuerad körning. När en distribuerad funktion anropas på koordinatorn använder Azure Cosmos DB for PostgreSQL värdet för "distributionsargumentet" för att välja en arbetsnod för att köra funktionen. Körningen av funktionen på arbetare ökar parallelliteten och kan föra koden närmare data i shards för kortare svarstider.

Sökvägen Postgres sprids inte från koordinatorn till arbetare under distribuerad funktionskörning, så distribuerad funktionskod bör fullständigt kvalificera namnen på databasobjekt. Meddelanden som genereras av funktionerna visas inte heller för användaren.

Argument

function_name: Namnet på den funktion som ska distribueras. Namnet måste innehålla funktionens parametertyper inom parenteser, eftersom flera funktioner kan ha samma namn i PostgreSQL. Till exempel 'foo(int)' skiljer sig från 'foo(int, text)'.

distribution_arg_name: (Valfritt) Argumentnamnet som ska distribueras. För enkelhetens skull (eller om funktionsargumenten inte har namn) tillåts en positionsplatshållare, till exempel '$1'. Om den här parametern inte anges skapas funktionen med namnet av function_name bara för arbetarna. Om arbetsnoder läggs till i framtiden skapas funktionen automatiskt även där.

colocate_with: (Valfritt) När den distribuerade funktionen läser eller skriver till en distribuerad tabell (eller, mer allmänt, samlokaliseringsgrupp), måste du namnge tabellen med hjälp av parametern colocate_with . Sedan körs varje anrop av funktionen på arbetsnoden som innehåller relevanta shards.

Returvärde

Inte tillgängligt

Exempel

-- 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

Funktionen alter_columnar_table_set() ändrar inställningarna i en kolumntabell. Att anropa den här funktionen i en tabell som inte är kolumnbaserad ger ett fel. Alla argument utom tabellnamnet är valfria.

Om du vill visa aktuella alternativ för alla kolumntabeller läser du den här tabellen:

SELECT * FROM columnar.options;

Standardvärdena för kolumninställningar för nyligen skapade tabeller kan åsidosättas med följande GUC:er:

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

Argument

table_name: Namnet på kolumntabellen.

chunk_row_count: (Valfritt) Det maximala antalet rader per segment för nyligen infogade data. Befintliga datasegment ändras inte och kan ha fler rader än det här maximala värdet. Standardvärdet är 10000.

stripe_row_count: (Valfritt) Det maximala antalet rader per rand för nyligen infogade data. Befintliga dataränder ändras inte och kan ha fler rader än det här maximala värdet. Standardvärdet är 150000.

komprimering: (valfritt) [none|pglz|zstd|lz4|lz4hc] Komprimeringstypen för nyligen infogade data. Befintliga data kommer inte att komprimeras eller dekomprimeras. Standardvärdet och det föreslagna värdet är zstd (om supporten har kompilerats i).

compression_level: (Valfritt) Giltiga inställningar är mellan 1 och 19. Om komprimeringsmetoden inte stöder den valda nivån väljs den närmaste nivån i stället.

Returvärde

Inte tillgängligt

Exempel

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

alter_table_set_access_method

Funktionen alter_table_set_access_method() ändrar åtkomstmetoden för en tabell (till exempel heap eller columnar).

Argument

table_name: Namnet på tabellen vars åtkomstmetod ändras.

access_method: Namnet på den nya åtkomstmetoden.

Returvärde

Inte tillgängligt

Exempel

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

create_time_partitions

Funktionen create_time_partitions() skapar partitioner med ett visst intervall för att täcka ett angivet tidsintervall.

Argument

table_name: (regclass) tabell som du vill skapa nya partitioner för. Tabellen måste partitioneras i en kolumn, av typen datum, tidsstämpel eller tidsstämpel.

partition_interval: ett tidsintervall, till exempel , eller '1 month', som '2 hours'ska användas vid inställning av intervall på nya partitioner.

end_at: (tidsstämpel) skapar partitioner fram till den här tiden. Den sista partitionen innehåller punkten end_at och inga senare partitioner skapas.

start_from: (tidsstämpel, valfritt) väljer du den första partitionen så att den innehåller punkten start_from. Standardvärdet är now().

Returvärde

Sant om det behövs för att skapa nya partitioner, falskt om alla redan fanns.

Exempel

-- 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

Funktionen drop_old_time_partitions() tar bort alla partitioner vars intervall faller före en viss tidsstämpel. Förutom att använda den här funktionen kan du överväga alter_old_partitions_set_access_method för att komprimera de gamla partitionerna med columnar Storage.

Argument

table_name: (regclass) tabell för vilken partitioner ska tas bort. Tabellen måste partitioneras i en kolumn, av typen datum, tidsstämpel eller tidsstämpel.

older_than: (tidsstämpel) släpper partitioner vars övre intervall är mindre än eller lika med older_than.

Returvärde

Inte tillgängligt

Exempel

-- drop partitions that are over a year old

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

alter_old_partitions_set_access_method

I ett användningsfall för tidsserier partitioneras tabeller ofta efter tid och gamla partitioner komprimeras till skrivskyddad kolumnlagring.

Argument

parent_table_name: (regclass) tabell som partitioner ska ändras för. Tabellen måste partitioneras i en kolumn, av typen datum, tidsstämpel eller tidsstämpel.

older_than: (tidsstämpel) ändrar partitioner vars övre intervall är mindre än eller lika med older_than.

new_access_method: (namn) antingen "heap" för radbaserad lagring eller "columnar" för columnar Storage.

Returvärde

Inte tillgängligt

Exempel

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

Metadata/konfigurationsinformation

get_shard_id_for_distribution_column

Azure Cosmos DB for PostgreSQL tilldelar varje rad i en distribuerad tabell till en shard baserat på värdet för radens distributionskolumn och tabellens distributionsmetod. I de flesta fall är den exakta mappningen en lågnivåinformation som databasadministratören kan ignorera. Det kan dock vara användbart att fastställa en rads fragment, antingen för manuella databasunderhållsuppgifter eller bara för att tillfredsställa nyfikenhet. Funktionen get_shard_id_for_distribution_column tillhandahåller den här informationen för hash-distribuerade, intervall-distribuerade och referenstabeller. Det fungerar inte för tilläggsdistributionen.

Argument

table_name: Den distribuerade tabellen.

distribution_value: Värdet för distributionskolumnen.

Returvärde

Shard-ID:t Azure Cosmos DB for PostgreSQL associerar med distributionskolumnvärdet för den angivna tabellen.

Exempel

SELECT get_shard_id_for_distribution_column('my_table', 4);

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

column_to_column_name

Översätter kolumnen pg_dist_partition i partkey till ett textkolumnnamn. Översättningen är användbar för att fastställa distributionskolumnen i en distribuerad tabell.

En mer detaljerad diskussion finns i välja en distributionskolumn.

Argument

table_name: Den distribuerade tabellen.

column_var_text: Värdet partkey för pg_dist_partition i tabellen.

Returvärde

Namnet på table_namedistributionskolumnen.

Exempel

-- 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;

Utdata:

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

citus_relation_size

Hämta diskutrymmet som används av alla shards i den angivna distribuerade tabellen. Diskutrymmet innehåller storleken på "huvudförgreningen", men undantar synlighetskartan och den lediga utrymmeskartan för fragmenten.

Argument

logicalrelid: namnet på en distribuerad tabell.

Returvärde

Storlek i byte som en bigint.

Exempel

SELECT pg_size_pretty(citus_relation_size('github_events'));

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

citus_table_size

Hämta diskutrymmet som används av alla shards i den angivna distribuerade tabellen, exklusive index (men inklusive TOAST, fri utrymmeskarta och synlighetskarta).

Argument

logicalrelid: namnet på en distribuerad tabell.

Returvärde

Storlek i byte som en bigint.

Exempel

SELECT pg_size_pretty(citus_table_size('github_events'));

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

citus_total_relation_size

Hämta det totala diskutrymme som används av alla shards i den angivna distribuerade tabellen, inklusive alla index och TOAST-data.

Argument

logicalrelid: namnet på en distribuerad tabell.

Returvärde

Storlek i byte som en bigint.

Exempel

SELECT pg_size_pretty(citus_total_relation_size('github_events'));

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

citus_stat_statements_reset

Tar bort alla rader från citus_stat_statements. Den här funktionen fungerar oberoende av pg_stat_statements_reset(). Om du vill återställa all statistik anropar du båda funktionerna.

Argument

Inte tillgängligt

Returvärde

Inga

citus_get_active_worker_nodes

Funktionen citus_get_active_worker_nodes() returnerar en lista över aktiva arbetsvärdnamn och portnummer.

Argument

Inte tillgängligt

Returvärde

Lista över tupplar där varje tupplar innehåller följande information:

node_name: DNS-namnet på arbetsnoden

node_port: Port på arbetsnoden där databasservern lyssnar

Exempel

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

(3 rows)

Klusterhantering och reparation

master_copy_shard_placement

Om en shardplacering inte uppdateras under ett ändringskommando eller en DDL-åtgärd markeras den som inaktiv. Funktionen master_copy_shard_placement kan sedan anropas för att reparera en inaktiv shardplacering med hjälp av data från en felfri placering.

För att reparera en shard släpper funktionen först den felaktiga fragmentplaceringen och återskapar den med hjälp av schemat på koordinatorn. När shardplaceringen har skapats kopierar funktionen data från den felfria placeringen och uppdaterar metadata för att markera den nya shardplaceringen som felfri. Den här funktionen säkerställer att fragmentet skyddas från eventuella samtidiga ändringar under reparationen.

Argument

shard_id: ID för fragmentet som ska repareras.

source_node_name: DNS-namnet på noden där den felfria shardplaceringen finns ("källnoden").

source_node_port: Porten på källarbetsnoden som databasservern lyssnar på.

target_node_name: DNS-namnet på noden där den ogiltiga shardplaceringen finns ("målnoden").

target_node_port: Porten på målarbetsnoden som databasservern lyssnar på.

Returvärde

Inte tillgängligt

Exempel

Exemplet nedan reparerar en inaktiv shardplacering av shard 12345, som finns på databasservern som körs på "bad_host" på port 5432. För att reparera den använder den data från en felfri shardplacering som finns på servern som körs på "good_host" på port 5432.

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

master_move_shard_placement

Den här funktionen flyttar en viss shard (och shards som är samlokaliserade med den) från en nod till en annan. Den används vanligtvis indirekt under horisontell ombalansering i stället för att anropas direkt av en databasadministratör.

Det finns två sätt att flytta data: blockering eller icke-blockering. Blockeringsmetoden innebär att alla ändringar av shard pausas under flytten. Det andra sättet, som undviker blockering av fragmentskrivningar, förlitar sig på logisk postgres 10-replikering.

Efter en lyckad flyttåtgärd tas shards i källnoden bort. Om flytten misslyckas vid något tillfälle utlöser den här funktionen ett fel och lämnar käll- och målnoderna oförändrade.

Argument

shard_id: ID för shard som ska flyttas.

source_node_name: DNS-namnet på noden där den felfria shardplaceringen finns ("källnoden").

source_node_port: Porten på källarbetsnoden som databasservern lyssnar på.

target_node_name: DNS-namnet på noden där den ogiltiga shardplaceringen finns ("målnoden").

target_node_port: Porten på målarbetsnoden som databasservern lyssnar på.

shard_transfer_mode: (Valfritt) Ange replikeringsmetod, om du vill använda logisk PostgreSQL-replikering eller ett copy-kommando mellan arbetare. Möjliga värden är:

auto: Kräv replikidentitet om logisk replikering är möjlig, annars använd äldre beteende (t.ex. för fragmentreparation, PostgreSQL 9.6). Detta är standardvärdet.

force_logical: Använd logisk replikering även om tabellen inte har någon replikidentitet. Alla samtidiga uppdaterings-/borttagningsinstruktioner till tabellen misslyckas under replikeringen.

block_writes: Använd COPY (blockeringsskrivningar) för tabeller som saknar primärnyckel eller replikidentitet.

Returvärde

Inte tillgängligt

Exempel

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

rebalance_table_shards

Funktionen rebalance_table_shards() flyttar shards i den angivna tabellen för att fördela dem jämnt mellan arbetarna. Funktionen beräknar först listan över flyttningar som den behöver göra för att säkerställa att klustret balanseras inom det angivna tröskelvärdet. Sedan flyttas shardplaceringar en i taget från källnoden till målnoden och uppdaterar motsvarande shardmetadata för att återspegla flytten.

Varje shard tilldelas en kostnad när du avgör om shards är "jämnt fördelade". Som standard har varje shard samma kostnad (ett värde på 1), så att distribuera för att utjämna kostnaden mellan arbetare är detsamma som att utjämna antalet shards på var och en. Den ständiga kostnadsstrategin kallas "by_shard_count" och är standardstrategin för ombalansering.

Strategin "by_shard_count" är lämplig under dessa omständigheter:

Fragmenten har ungefär samma storlek
Fragmenten får ungefär samma mängd trafik
Arbetsnoder har samma storlek/typ
Shards har inte fästs på vissa arbetare

Om något av dessa antaganden inte gäller kan ombalansering av "by_shard_count" resultera i en felaktig plan.

Standardstrategin för ombalansering är "by_disk_size". Du kan alltid anpassa strategin med hjälp av parametern rebalance_strategy .

Vi rekommenderar att du anropar get_rebalance_table_shards_plan innan du kör rebalance_table_shards för att se och verifiera de åtgärder som ska utföras.

Argument

table_name: (Valfritt) Namnet på tabellen vars shards måste balanseras om. Om värdet är NULL balanserar du om alla befintliga samlokaliseringsgrupper.

tröskelvärde: (Valfritt) Ett flyttalnummer mellan 0,0 och 1,0 som anger den maximala skillnaden mellan nodanvändning och genomsnittlig användning. Om du till exempel anger 0.1 kommer shard-ombalanseraren att försöka balansera alla noder så att den innehåller samma antal shards ±10 %. Mer specifikt försöker shard-ombalanseraren konvergera användningen av alla arbetsnoder till (1 – tröskelvärdet) * average_utilization ... (1

tröskelvärde) * average_utilization intervall.

max_shard_moves: (Valfritt) Det maximala antalet shards som ska flyttas.

excluded_shard_list: (Valfritt) Identifierare för shards som inte ska flyttas under ombalanseringsåtgärden.

shard_transfer_mode: (Valfritt) Ange replikeringsmetod, om du vill använda logisk PostgreSQL-replikering eller ett copy-kommando mellan arbetare. Möjliga värden är:

auto: Kräv replikidentitet om logisk replikering är möjlig, annars använd äldre beteende (t.ex. för fragmentreparation, PostgreSQL 9.6). Detta är standardvärdet.

force_logical: Använd logisk replikering även om tabellen inte har någon replikidentitet. Alla samtidiga uppdaterings-/borttagningsinstruktioner till tabellen misslyckas under replikeringen.

block_writes: Använd COPY (blockeringsskrivningar) för tabeller som saknar primärnyckel eller replikidentitet.

drain_only: (Valfritt) När det är sant flyttar du shards från arbetsnoder som har shouldhaveshards angetts till false i pg_dist_node. Flytta inga andra shards.

rebalance_strategy: (Valfritt) namnet på en strategi i pg_dist_rebalance_strategy. Om det här argumentet utelämnas väljer funktionen standardstrategin, som anges i tabellen.

Returvärde

Inte tillgängligt

Exempel

Exemplet nedan försöker balansera om shards i github_events-tabellen inom standardtröskelvärdet.

SELECT rebalance_table_shards('github_events');

Den här exempelanvändningen försöker balansera om tabellen github_events utan att flytta shards med ID 1 och 2.

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

get_rebalance_table_shards_plan

Mata ut de planerade fragmentförflyttningarna för rebalance_table_shards utan att utföra dem. Även om det är osannolikt kan get_rebalance_table_shards_plan mata ut en något annorlunda plan än vad ett rebalance_table_shards-anrop med samma argument kommer att göra. De körs inte samtidigt, så fakta om klustret , till exempel diskutrymme, kan skilja sig mellan anropen.

Argument

Samma argument som rebalance_table_shards: relation, tröskelvärde, max_shard_moves, excluded_shard_list och drain_only. Se dokumentationen för den funktionen för argumentens betydelse.

Returvärde

Tupplar som innehåller dessa kolumner:

table_name: Tabellen vars fragment skulle flyttas
shardid: Fragmentet i fråga
shard_size: Storlek i byte
sourcename: Källnodens värdnamn
sourceport: Port för källnoden
targetname: Värdnamn för målnoden
targetport: Port för målnoden

get_rebalance_progress

När en shard-ombalansering börjar get_rebalance_progress() visar funktionen förloppet för varje shard som ingår. Den övervakar de flyttningar som planeras och körs av rebalance_table_shards().

Argument

Inte tillgängligt

Returvärde

Tupplar som innehåller dessa kolumner:

sessionid: Postgres PID för ombalanseringsövervakaren
table_name: Tabellen vars shards flyttas
shardid: Fragmentet i fråga
shard_size: Storlek i byte
sourcename: Källnodens värdnamn
sourceport: Port för källnoden
targetname: Värdnamn för målnoden
targetport: Port för målnoden
progress: 0 = waiting to be moved; 1 = moving; 2 = complete

Exempel

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

Lägg till en rad i pg_dist_rebalance_strategy .

Argument

Mer information om dessa argument finns i motsvarande kolumnvärden i pg_dist_rebalance_strategy.

name: identifier för den nya strategin

shard_cost_function: identifierar den funktion som används för att fastställa kostnaden för varje shard

node_capacity_function: identifierar funktionen för att mäta nodkapacitet

shard_allowed_on_node_function: identifierar funktionen som avgör vilka shards som kan placeras på vilka noder

default_threshold: ett tröskelvärde för flyttalser som justerar exakt hur den kumulativa shardkostnaden ska balanseras mellan noder

minimum_threshold: (Valfritt) en skyddskolumn som innehåller det minsta värde som tillåts för tröskelvärdet för rebalance_table_shards(). Standardvärdet är 0

Returvärde

Inte tillgängligt

citus_set_default_rebalance_strategy

Uppdatera tabellen pg_dist_rebalance_strategy och ändra den strategi som heter med argumentet till standardvärdet som väljs vid ombalansering av shards.

Argument

name: namnet på strategin i pg_dist_rebalance_strategy

Returvärde

Inte tillgängligt

Exempel

SELECT citus_set_default_rebalance_strategy('by_disk_size');

citus_remote_connection_stats

Funktionen citus_remote_connection_stats() visar antalet aktiva anslutningar till varje fjärrnod.

Argument

Inte tillgängligt

Exempel

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

Den här funktionen skapar en ny shard för att lagra rader med ett specifikt enskilt värde i distributionskolumnen. Det är särskilt praktiskt för användningsfallet för flera klienter, där en stor klientorganisation kan placeras ensam på sin egen shard och i slutändan sin egen fysiska nod.

Argument

table_name: Namnet på tabellen för att hämta en ny shard.

tenant_id: Värdet för den distributionskolumn som ska tilldelas till det nya fragmentet.

cascade_option: (Valfritt) När värdet är "CASCADE" isolerar även en fragment från alla tabeller i den aktuella tabellens samlokaliseringsgrupp.

Returvärde

shard_id: Funktionen returnerar det unika ID som tilldelats den nyligen skapade fragmentet.

Exempel

Skapa en ny shard för att lagra lineitems för klientorganisation 135:

SELECT isolate_tenant_to_new_shard('lineitem', 135);

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

Nästa steg

Många av funktionerna i den här artikeln ändrar systemmetadatatabeller
Serverparametrar anpassar beteendet för vissa funktioner

Share via

Azure Cosmos DB for PostgreSQL-funktioner

Tabell och Shard DDL

citus_schema_distribute

Argument

Returvärde

Exempel

citus_schema_undistribute

Argument

Returvärde

Exempel

create_distributed_table

Argument

Returvärde

Exempel

create_distributed_table_concurrently

truncate_local_data_after_distributing_table

Argument

Returvärde

Exempel

create_reference_table

Argument

Returvärde

Exempel

citus_add_local_table_to_metadata

Argument

Returvärde

Exempel

alter_distributed_table

Argument

Returvärde

Exempel

update_distributed_table_colocation

Argument

Returvärde

Exempel

undistribute_table

Argument

Returvärde

Exempel

create_distributed_function

Argument

Returvärde

Exempel

alter_columnar_table_set

Argument

Returvärde

Exempel

alter_table_set_access_method

Argument

Returvärde

Exempel

create_time_partitions

Argument

Returvärde

Exempel

drop_old_time_partitions

Argument

Returvärde

Exempel

alter_old_partitions_set_access_method

Argument

Returvärde

Exempel

Metadata/konfigurationsinformation

get_shard_id_for_distribution_column

Argument

Returvärde

Exempel

column_to_column_name

Argument

Returvärde

Exempel

citus_relation_size

Argument

Returvärde

Exempel

citus_table_size

Argument

Returvärde