Funkce Azure Cosmos DB for PostgreSQL

Článek
08/15/2024

PLATÍ PRO: Azure Cosmos DB for PostgreSQL (využívající rozšíření databáze Citus do PostgreSQL)

Tato část obsahuje referenční informace pro uživatelem definované funkce poskytované službou Azure Cosmos DB for PostgreSQL. Tyto funkce pomáhají poskytovat distribuované funkce službě Azure Cosmos DB for PostgreSQL.

Poznámka:

clustery se staršími verzemi modulu Citus Nemusí nabízet všechny funkce uvedené na této stránce.

DDL tabulky a horizontálního dělení

citus_schema_distribute

Převede existující běžná schémata na distribuovaná schémata. Distribuovaná schémata se automaticky přidružují k jednotlivým skupinám kolokace. Tabulky vytvořené v těchto schématech se převedou na společné distribuované tabulky bez klíče horizontálního dělení. Proces distribuce schématu se automaticky přiřadí a přesune do existujícího uzlu v clusteru.

Argumenty

schemaname: Název schématu, které je potřeba distribuovat.

Vrácená hodnota

–

Příklad

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

Další příklady najdete v tématu Návrh mikroslužeb.

citus_schema_undistribute

Převede existující distribuované schéma zpět na běžné schéma. Výsledkem procesu jsou tabulky a data přesunutá z aktuálního uzlu zpět do koordinačního uzlu v clusteru.

Argumenty

schemaname: Název schématu, které je potřeba distribuovat.

Vrácená hodnota

–

Příklad

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

Další příklady najdete v tématu Návrh mikroslužeb.

create_distributed_table

Funkce create_distributed_table() slouží k definování distribuované tabulky a vytvoření jejích horizontálních oddílů, pokud se jedná o tabulku distribuovanou hodnotou hash. Tato funkce přebírá název tabulky, distribuční sloupec a volitelnou metodu distribuce a vloží příslušná metadata pro označení tabulky jako distribuované. Pokud není zadána žádná metoda distribuce, funkce je ve výchozím nastavení nastavená na hodnotu hash. Pokud je tabulka distribuovaná hodnotou hash, funkce také vytvoří horizontální oddíly pracovních procesů na základě počtu horizontálních oddílů a hodnot konfigurace faktoru replikace horizontálních oddílů. Pokud tabulka obsahuje nějaké řádky, automaticky se distribuují do pracovních uzlů.

Tato funkce nahrazuje použití master_create_distributed_table() následované master_create_worker_shards().

Argumenty

table_name: Název tabulky, kterou je potřeba distribuovat.

distribution_column: Sloupec, na kterém má být tabulka distribuována.

distribution_type: (Volitelné) Metoda, podle které se má tabulka distribuovat. Přípustné hodnoty jsou připojení nebo hodnota hash s výchozí hodnotou hash.

colocate_with: (Volitelné) zahrnout aktuální tabulku do skupiny kolokací jiné tabulky. Ve výchozím nastavení se tabulky společně přidělují podle sloupců stejného typu, mají stejný počet horizontálních oddílů a mají stejný faktor replikace. Možné hodnoty jsou colocate_with default, none aby se spustila nová skupina kolokace nebo název jiné tabulky, která se má s danou tabulkou uvolnit. (Viz kolokace tabulky.)

Mějte na paměti, že výchozí hodnota colocate_with implicitní kolokace. Kolokace může být skvělá věc, když jsou tabulky související nebo budou spojené. Pokud jsou ale dvě tabulky nesouvisející, ale při použití stejného datového typu pro distribuční sloupce je náhodné společné přidělení může snížit výkon během vyrovnávání horizontálních oddílů. Horizontální oddíly tabulky se zbytečně přesunou do "kaskády".

Pokud nová distribuovaná tabulka nesouvisí s jinými tabulkami, je nejlepší zadat colocate_with => 'none'.

shard_count: (Volitelné) počet horizontálních oddílů, které se mají vytvořit pro novou distribuovanou tabulku. Při zadávání shard_count nemůžete zadat jinou hodnotu colocate_with než žádnou. Pokud chcete změnit počet horizontálních oddílů existující tabulky nebo skupiny kolokace, použijte funkci alter_distributed_table .

Možné hodnoty jsou shard_count v rozmezí od 1 do 64000. Pokyny k výběru optimální hodnoty najdete v tématu Počet horizontálních oddílů.

Vrácená hodnota

–

Příklad

Tento příklad informuje databázi, že tabulka github_events by měla být distribuována hodnotou hash ve sloupci 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

Tato funkce má stejné rozhraní a účel jako create_distributed_function, ale neblokuje zápisy během distribuce tabulky.

Má create_distributed_table_concurrently však několik omezení:

Funkci nemůžete použít v bloku transakcí, což znamená, že můžete distribuovat pouze jednu tabulku najednou. (Funkci můžete použít v tabulkách rozdělených podle času.)
Nelze použít create_distributed_table_concurrently , pokud je tabulka odkazována cizím klíčem nebo odkazuje na jinou místní tabulku. Cizí klíče pro odkazy na tabulky ale fungují a po dokončení distribuce tabulek můžete vytvořit cizí klíče do jiných distribuovaných tabulek.
Pokud ve vaší tabulce nemáte primární klíč nebo identitu repliky, příkazy aktualizace a odstranění se během distribuce tabulky nezdaří kvůli omezením logické replikace.

truncate_local_data_after_distributing_table

Zkracte všechny místní řádky po distribuci tabulky a zabraňte selhání omezení kvůli zastaralým místním záznamům. Zkrácení se kaskáduje k tabulkám, které mají cizí klíč k určené tabulce. Pokud se odkazující tabulky nedistribuují, pak je zkrácení zakázáno, dokud nebudou, aby se chránily referenční integrity:

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

Zkrácení dat tabulky místních koordinačních uzlů je bezpečné pro distribuované tabulky, protože jejich řádky (pokud existují) se během distribuce zkopírují do pracovních uzlů.

Argumenty

table_name: Název distribuované tabulky, jejíž místní protějšk na koordinačním uzlu by měl být zkrácen.

Vrácená hodnota

–

Příklad

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

create_reference_table

Funkce create_reference_table() slouží k definování malé referenční tabulky nebo tabulky dimenzí. Tato funkce přebírá název tabulky a vytvoří distribuovanou tabulku s jedním horizontálním oddílem, který se replikuje do každého pracovního uzlu.

Argumenty

table_name: Název malé dimenze nebo referenční tabulky, kterou je potřeba distribuovat.

Vrácená hodnota

–

Příklad

Tento příklad informuje databázi, že tabulka národ by měla být definována jako referenční tabulka.

SELECT create_reference_table('nation');

citus_add_local_table_to_metadata

Přidá místní tabulku Postgres do metadat Citus. Hlavním případem použití této funkce je vytvoření místních tabulek v koordinátoru přístupném z libovolného uzlu v clusteru. Data přidružená k místní tabulce zůstávají v koordinátoru – do pracovních procesů se odesílají pouze její schéma a metadata.

Přidání místních tabulek do metadat je mírně nákladné. Když přidáte tabulku, citus ji musí sledovat v tabulce oddílů. Místní tabulky přidané do metadat dědí stejná omezení jako referenční tabulky.

Když zrušíte přiřazení tabulky, Citus odebere výsledné místní tabulky z metadat, což eliminuje taková omezení těchto tabulek.

Argumenty

table_name: Název tabulky koordinátoru, který se má přidat do metadat Citus.

cascade_via_foreign_keys: (Volitelné) Pokud je tento argument nastavený na hodnotu true, citus_add_local_table_to_metadata přidá další tabulky, které jsou v relaci cizího klíče s danou tabulkou, do metadat automaticky. U tohoto parametru buďte opatrní, protože může potenciálně ovlivnit mnoho tabulek.

Vrácená hodnota

–

Příklad

Tento příklad informuje databázi, že tabulka národ by měla být definována jako tabulka koordinátor-místní, přístupná z libovolného uzlu:

SELECT citus_add_local_table_to_metadata('nation');

alter_distributed_table

Funkci alter_distributed_table() lze použít ke změně distribučního sloupce, počtu horizontálních oddílů nebo vlastností kolokace distribuované tabulky.

Argumenty

table_name: Název tabulky, která se změní.

distribution_column: (Volitelné) Název nového distribučního sloupce.

shard_count: (Volitelné) Počet nových horizontálních oddílů.

colocate_with: (Volitelné) Tabulka, se kterou bude aktuální distribuovaná tabulka společně přidělena. Možné hodnoty jsou default, none aby se spustila nová skupina kolokace nebo název jiné tabulky, se kterou chcete colokovat. (Viz kolokace tabulky.)

cascade_to_colocated: (Volitelné) Pokud je tento argument nastavený na hodnotu true a shard_count colocate_with změny se použijí také u všech tabulek, které byly dříve společně s tabulkou společné, a kolokace se zachová. Pokud se jedná o hodnotu false, aktuální kolokace této tabulky bude přerušena.

Vrácená hodnota

–

Příklad

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

Funkce update_distributed_table_colocation() slouží k aktualizaci kolokace distribuované tabulky. Tuto funkci lze také použít k přerušení kolokace distribuované tabulky. Azure Cosmos DB for PostgreSQL implicitně rozdělí dvě tabulky, pokud je distribuční sloupec stejného typu, může to být užitečné, pokud spolu tabulky souvisejí a budou provádět některá spojení. Pokud jsou tabulky A a B společné a tabulka A se znovu vyrovná, tabulka B bude také znovu vyvážena. Pokud tabulka B nemá identitu repliky, vyvážení selže. Proto může být tato funkce užitečná k porušení implicitního kolokace v takovém případě.

Tato funkce nepřesouvají žádná data fyzicky.

Argumenty

table_name: Název kolokace tabulky, která se aktualizuje.

colocate_with: Tabulka, do které má být tabulka společně přidělena.

Pokud chcete přerušit kolokaci tabulky, měli byste zadat colocate_with => 'none'.

Vrácená hodnota

–

Příklad

Tento příklad ukazuje, že umístění tabulky A se aktualizuje jako kolokace tabulky B.

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

Předpokládejme, že tabulka A a tabulka B jsou společně přiděleny (pravděpodobně implicitně), pokud chcete přerušit kolokaci:

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

Nyní předpokládejme, že tabulka A, tabulka B, tabulka C a tabulka D jsou společné a chcete společně přidělit tabulku A a tabulku B a tabulku C a D dohromady:

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

Pokud máte distribuovanou tabulku hash s názvem none a chcete aktualizovat její kolokaci, můžete provést následující kroky:

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

undistribute_table

Funkce undistribute_table() vrátí zpět akci create_distributed_table nebo create_reference_table. Zrušením přiřazení se přesunou všechna data z horizontálních oddílů zpět do místní tabulky na koordinačním uzlu (za předpokladu, že se data dají přizpůsobit) a pak odstraní horizontální oddíly.

Azure Cosmos DB for PostgreSQL nerozpozná tabulky, které mají hodnotu cizích klíčů nebo na ně odkazují, pokud není argument cascade_via_foreign_keys nastaven na hodnotu true. Pokud je tento argument nepravda (nebo vynechán), musíte před zrušením přiřazení ručně vypnout omezení cizího klíče.

Argumenty

table_name: Název distribuované nebo referenční tabulky pro zrušení přiřazení.

cascade_via_foreign_keys: (Volitelné) Pokud je tento argument nastavený na hodnotu true, undistribute_table také zruší přiřazení všech tabulek, které souvisejí s table_name prostřednictvím cizích klíčů. U tohoto parametru buďte opatrní, protože může potenciálně ovlivnit mnoho tabulek.

Vrácená hodnota

–

Příklad

Tento příklad distribuuje github_events tabulku a potom ji zruší.

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

Rozšíří funkci z koordinačního uzlu do pracovních procesů a označí ji pro distribuované spuštění. Když je v koordinátoru volána distribuovaná funkce, Azure Cosmos DB for PostgreSQL použije hodnotu "distribučního argumentu" k výběru pracovního uzlu ke spuštění funkce. Provádění funkce u pracovních procesů zvyšuje paralelismus a může kód přiblížit k datům v horizontálních oddílech, aby se snížila latence.

Cesta hledání Postgres se během provádění distribuovaných funkcí nerozšířuje z koordinátoru na pracovní procesy, takže kód distribuované funkce by měl plně kvalifikovat názvy databázových objektů. Všimněte si také, že funkce se uživateli nezobrazí.

Argumenty

function_name: Název funkce, která se má distribuovat. Název musí obsahovat typy parametrů funkce v závorkách, protože více funkcí může mít stejný název v PostgreSQL. Například 'foo(int)' se liší od 'foo(int, text)'.

distribution_arg_name: (Volitelné) Název argumentu, podle kterého se má distribuovat. Pro usnadnění (nebo pokud argumenty funkce nemají názvy), je povolený poziční zástupný symbol, například '$1'. Pokud tento parametr není zadaný, funkce pojmenovaná function_name pomocí je pouze vytvořena u pracovních procesů. Pokud se pracovní uzly přidají v budoucnu, funkce se tam také automaticky vytvoří.

colocate_with: (Volitelné) Pokud distribuovaná funkce čte nebo zapisuje do distribuované tabulky (obecněji skupinu kolokací), nezapomeňte tuto tabulku pojmenovat pomocí parametru colocate_with . Každé vyvolání funkce se pak spustí na pracovním uzlu, který obsahuje relevantní horizontální oddíly.

Vrácená hodnota

–

Příklad

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

Funkce alter_columnar_table_set() změní nastavení sloupcové tabulky. Voláním této funkce v tabulce, která není sloupcová, se zobrazí chyba. Všechny argumenty kromě názvu tabulky jsou volitelné.

Pokud chcete zobrazit aktuální možnosti pro všechny sloupcové tabulky, projděte si tuto tabulku:

SELECT * FROM columnar.options;

Výchozí hodnoty pro nastavení sloupců pro nově vytvořené tabulky je možné přepsat pomocí těchto guc:

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

Argumenty

table_name: Název sloupcové tabulky.

chunk_row_count: (Volitelné) Maximální počet řádků na blok dat pro nově vložená data. Existující bloky dat nebudou změněny a mohou mít více řádků, než je tato maximální hodnota. Výchozí hodnota je 1 0000.

stripe_row_count: (Volitelné) Maximální počet řádků na pruh pro nově vložená data. Stávající pruhy dat se nezmění a můžou mít více řádků, než je tato maximální hodnota. Výchozí hodnota je 150000.

compression: (Volitelné) [none|pglz|zstd|lz4|lz4hc] Typ komprese pro nově vložená data. Existující data nebudou rekomprimována ani dekomprimována. Výchozí a navrhovaná hodnota je zstd (pokud byla podpora zkompilována).

compression_level: (Volitelné) Platné nastavení je od 1 do 19. Pokud metoda komprese nepodporuje zvolenou úroveň, vybere se místo toho nejbližší úroveň.

Vrácená hodnota

–

Příklad

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

alter_table_set_access_method

Funkce alter_table_set_access_method() změní metodu přístupu tabulky (například haldu nebo sloupec).

Argumenty

table_name: Název tabulky, jejíž přístupová metoda se změní.

access_method: Název nové metody přístupu.

Vrácená hodnota

–

Příklad

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

create_time_partitions

Funkce create_time_partitions() vytvoří oddíly daného intervalu pro pokrytí daného rozsahu času.

Argumenty

table_name: (regclass), pro kterou chcete vytvořit nové oddíly. Tabulka musí být rozdělena do jednoho sloupce, typu data, časového razítka nebo časového razítka.

partition_interval: interval času, například '2 hours'nebo '1 month', který se má použít při nastavování rozsahů na nových oddílech.

end_at: (timestamptz) vytvoří oddíly až do této doby. Poslední oddíl bude obsahovat bod end_at a nebudou vytvořeny žádné pozdější oddíly.

start_from: (časové razítko, volitelné) vyberte první oddíl, aby obsahoval bod start_from. Výchozí hodnota je now().

Vrácená hodnota

Hodnota True, pokud je potřeba vytvořit nové oddíly, false, pokud už všechny existovaly.

Příklad

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

Funkce drop_old_time_partitions() odebere všechny oddíly, jejichž intervaly spadají před dané časové razítko. Kromě použití této funkce můžete zvážit alter_old_partitions_set_access_method komprimovat staré oddíly se sloupcovým úložištěm.

Argumenty

table_name: (regclass) tabulka, pro kterou chcete odebrat oddíly. Tabulka musí být rozdělena do jednoho sloupce, typu data, časového razítka nebo časového razítka.

older_than: (timestamptz) drop partitions, jejichž horní rozsah je menší nebo roven older_than.

Vrácená hodnota

–

Příklad

-- drop partitions that are over a year old

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

alter_old_partitions_set_access_method

V případě použití časových období se tabulky často rozdělují podle času a staré oddíly se komprimují do sloupcového úložiště jen pro čtení.

Argumenty

parent_table_name: (regclass), pro kterou chcete změnit oddíly. Tabulka musí být rozdělena do jednoho sloupce, typu data, časového razítka nebo časového razítka.

older_than: (timestamptz) změňte oddíly, jejichž horní oblast je menší nebo rovna older_than.

new_access_method: (název) haldy pro úložiště založené na řádcích nebo columnar pro sloupcové úložiště.

Vrácená hodnota

–

Příklad

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

Metadata / informace o konfiguraci

get_shard_id_for_distribution_column

Azure Cosmos DB for PostgreSQL přiřadí každý řádek distribuované tabulky horizontálnímu oddílu na základě hodnoty distribučního sloupce řádku a metody distribuce tabulky. Ve většině případů je přesné mapování podrobností nízké úrovně, které může správce databáze ignorovat. Může ale být užitečné určit horizontální oddíl řádku, a to buď pro ruční úlohy údržby databáze, nebo jen tak, aby uspokojila zvědavost. Tato get_shard_id_for_distribution_column funkce poskytuje tyto informace pro tabulky distribuované pomocí hodnot hash, distribuovaných oblastí a referenčních tabulek. Nefunguje pro distribuci připojení.

Argumenty

table_name: Distribuovaná tabulka.

distribution_value: Hodnota distribučního sloupce.

Vrácená hodnota

ID horizontálního oddílu Azure Cosmos DB for PostgreSQL přidruží hodnotu distribučního sloupce pro danou tabulku.

Příklad

SELECT get_shard_id_for_distribution_column('my_table', 4);

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

column_to_column_name

partkey Převede sloupec pg_dist_partition na textový název sloupce. Překlad je užitečný k určení distribučního sloupce distribuované tabulky.

Podrobnější diskuzi najdete v tématu volba distribučního sloupce.

Argumenty

table_name: Distribuovaná tabulka.

column_var_text: Hodnota partkey v pg_dist_partition tabulce.

Vrácená hodnota

Název distribučního table_namesloupce.

Příklad

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

Výstup:

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

citus_relation_size

Získejte místo na disku používané všemi horizontálními oddíly zadané distribuované tabulky. Místo na disku zahrnuje velikost hlavního forku, ale vyloučí mapu viditelnosti a mapu volného místa pro horizontální oddíly.

Argumenty

logicalrelid: název distribuované tabulky.

Vrácená hodnota

Velikost vbajch

Příklad

SELECT pg_size_pretty(citus_relation_size('github_events'));

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

citus_table_size

Získejte místo na disku používané všemi horizontálními oddíly zadané distribuované tabulky, s výjimkou indexů (ale včetně toAST, volného místa na mapě a mapy viditelnosti).

Argumenty

logicalrelid: název distribuované tabulky.

Vrácená hodnota

Velikost vbajch

Příklad

SELECT pg_size_pretty(citus_table_size('github_events'));

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

citus_total_relation_size

Získejte celkové místo na disku využité všemi horizontálními oddíly zadané distribuované tabulky, včetně všech indexů a dat TOAST.

Argumenty

logicalrelid: název distribuované tabulky.

Vrácená hodnota

Velikost vbajch

Příklad

SELECT pg_size_pretty(citus_total_relation_size('github_events'));

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

citus_stat_statements_reset

Odebere všechny řádky z citus_stat_statements. Tato funkce funguje nezávisle na pg_stat_statements_reset(). Pokud chcete resetovat všechny statistiky, volejte obě funkce.

Argumenty

–

Vrácená hodnota

Nic

citus_get_active_worker_nodes

Funkce citus_get_active_worker_nodes() vrátí seznam názvů hostitelů aktivních pracovních procesů a čísel portů.

Argumenty

–

Vrácená hodnota

Seznam řazených kolekcí členů, kde každá řazená kolekce členů obsahuje následující informace:

node_name: Název DNS pracovního uzlu

node_port: Port na pracovním uzlu, na kterém databázový server naslouchá

Příklad

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

(3 rows)

Správa a oprava clusteru

master_copy_shard_placement

Pokud se během příkazu pro úpravy nebo operace DDL nepodaří aktualizovat umístění horizontálního oddílu, označí se jako neaktivní. Funkci master_copy_shard_placement pak lze volat k opravě neaktivního umístění horizontálního oddílu pomocí dat z umístění, které je v pořádku.

Pokud chcete opravit horizontální oddíl, funkce nejprve zahodí umístění horizontálních oddílů, které není v pořádku, a znovu ji vytvoří pomocí schématu v koordinátoru. Po vytvoření umístění horizontálního oddílu funkce zkopíruje data z umístění, které je v pořádku, a aktualizuje metadata, aby nové umístění horizontálních oddílů označilo jako v pořádku. Tato funkce zajistí, že horizontální oddíl bude během opravy chráněn před všemi souběžnými úpravami.

Argumenty

shard_id: ID horizontálního oddílu, který se má opravit.

source_node_name: Název DNS uzlu, na kterém je umístění horizontálních oddílů v pořádku (zdrojový uzel).

source_node_port: Port na zdrojovém pracovním uzlu, na kterém databázový server naslouchá.

target_node_name: Název DNS uzlu, na kterém je k dispozici neplatné umístění horizontálního oddílu (cílový uzel).

target_node_port: Port na cílovém pracovním uzlu, na kterém databázový server naslouchá.

Vrácená hodnota

–

Příklad

Následující příklad opraví neaktivní umístění horizontálního oddílu 12345, které je přítomné na databázovém serveru běžícím na bad_host na portu 5432. K jeho opravě se použijí data z umístění horizontálních oddílů, které je v pořádku, které je na serveru spuštěném na good_host na portu 5432.

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

master_move_shard_placement

Tato funkce přesune daný horizontální oddíl (a horizontální oddíly se s ním společně přidělují) z jednoho uzlu do druhého. Obvykle se používá nepřímo při vyrovnávání horizontálních oddílů místo přímého vyvolání správcem databáze.

Data můžete přesunout dvěma způsoby: blokování nebo odblokování. Blokující přístup znamená, že během přesunu se pozastaví všechny změny horizontálního oddílu. Druhý způsob, který zabraňuje blokování zápisů horizontálních oddílů, spoléhá na logickou replikaci Postgres 10.

Po úspěšné operaci přesunutí se odstraní horizontální oddíly ve zdrojovém uzlu. Pokud přesunutí v libovolném okamžiku selže, tato funkce vyvolá chybu a ponechá zdrojové a cílové uzly beze změny.

Argumenty

shard_id: ID horizontálního oddílu, který se má přesunout.

source_node_name: Název DNS uzlu, na kterém je umístění horizontálních oddílů v pořádku (zdrojový uzel).

source_node_port: Port na zdrojovém pracovním uzlu, na kterém databázový server naslouchá.

target_node_name: Název DNS uzlu, na kterém je k dispozici neplatné umístění horizontálního oddílu (cílový uzel).

target_node_port: Port na cílovém pracovním uzlu, na kterém databázový server naslouchá.

shard_transfer_mode: (Volitelné) Určete metodu replikace, ať už se má použít logická replikace PostgreSQL, nebo příkaz COPY mezi pracovními pracovníky. Možné hodnoty:

auto: Vyžadovat identitu repliky, pokud je možná logická replikace, jinak použijte starší chování (např. pro opravu horizontálních oddílů, PostgreSQL 9.6). Tato hodnota je výchozí.

force_logical: Použijte logickou replikaci i v případě, že tabulka nemá identitu repliky. Všechny souběžné příkazy update/delete do tabulky se během replikace nezdaří.

block_writes: Pro tabulky, které nemají primární klíč nebo identitu repliky, použijte funkci COPY (blokující zápisy).

Vrácená hodnota

–

Příklad

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

rebalance_table_shards

Funkce rebalance_table_shards() přesune horizontální oddíly dané tabulky a rozdělí je rovnoměrně mezi pracovní procesy. Funkce nejprve vypočítá seznam přesunů, které musí provést, aby se zajistilo, že cluster bude vyrovnán v rámci dané prahové hodnoty. Pak přesune umístění horizontálních oddílů o jeden po druhém ze zdrojového uzlu do cílového uzlu a aktualizuje odpovídající metadata horizontálních oddílů tak, aby odrážela přesun.

Každému horizontálnímu oddílu se přiřazují náklady při určování, jestli jsou horizontální oddíly "rovnoměrně distribuované". Ve výchozím nastavení má každý horizontální oddíl stejné náklady (hodnota 1), takže rozdělení na vyrovnání nákladů napříč pracovními procesy je stejné jako vyrovnání počtu horizontálních oddílů v každém oddílu. Konstantní nákladová strategie se nazývá "by_shard_count" a jedná se o výchozí strategii vyrovnávání.

Strategie "by_shard_count" je vhodná za těchto okolností:

Horizontální oddíly mají přibližně stejnou velikost.
Horizontální oddíly získají přibližně stejný objem provozu.
Pracovní uzly mají stejnou velikost nebo typ.
Horizontální oddíly nebyly připnuty ke konkrétním pracovníkům.

Pokud se některý z těchto předpokladů neudrží, může vyrovnání "by_shard_count" vést ke špatnému plánu.

Výchozí strategie vyrovnávání je "by_disk_size". Strategii můžete vždy přizpůsobit pomocí parametru rebalance_strategy .

Před spuštěním rebalance_table_shards doporučujeme volat get_rebalance_table_shards_plan , abyste viděli a ověřili akce, které se mají provést.

Argumenty

table_name: (Volitelné) Název tabulky, jejíž horizontální oddíly je potřeba znovu vyvážit. Pokud je hodnota NULL, znovu vyrovnejte všechny existující skupiny kolokace.

prahová hodnota: (Volitelné) Číslo s plovoucí hodnotou mezi 0,0 a 1,0, které označuje maximální poměr rozdílu využití uzlu od průměrného využití. Například zadání 0,1 způsobí, že se nástroj pro vyrovnávání horizontálních oddílů pokusí vyvážit všechny uzly, aby držel stejný počet horizontálních oddílů ±10 %. Konkrétně se shard rebalancer pokusí konvergovat využití všech pracovních uzlů k (1 – prahová hodnota) * average_utilization ... (1

prahová hodnota) * rozsah average_utilization.

max_shard_moves: (Volitelné) Maximální počet horizontálních oddílů, které se mají přesunout.

excluded_shard_list: (volitelné) Identifikátory horizontálních oddílů, které by se neměly přesouvat během operace vyrovnávání.

shard_transfer_mode: (Volitelné) Určete metodu replikace, ať už se má použít logická replikace PostgreSQL, nebo příkaz COPY mezi pracovními pracovníky. Možné hodnoty:

auto: Vyžadovat identitu repliky, pokud je možná logická replikace, jinak použijte starší chování (např. pro opravu horizontálních oddílů, PostgreSQL 9.6). Tato hodnota je výchozí.

force_logical: Použijte logickou replikaci i v případě, že tabulka nemá identitu repliky. Všechny souběžné příkazy update/delete do tabulky se během replikace nezdaří.

block_writes: Pro tabulky, které nemají primární klíč nebo identitu repliky, použijte funkci COPY (blokující zápisy).

drain_only: (Volitelné) Pokud je hodnota true, přesuňte horizontální oddíly mimo pracovní uzly, které mají shouldhaveshards v pg_dist_node nastavenou hodnotu false; nepřesouvejte žádné jiné horizontální oddíly.

rebalance_strategy: (volitelné) název strategie v pg_dist_rebalance_strategy. Pokud tento argument vynecháte, funkce zvolí výchozí strategii, jak je uvedeno v tabulce.

Vrácená hodnota

–

Příklad

Následující příklad se pokusí obnovit rovnováhu horizontálních oddílů tabulky github_events v rámci výchozí prahové hodnoty.

SELECT rebalance_table_shards('github_events');

Toto ukázkové použití se pokusí znovu vyvážit tabulku github_events bez přesunutí horizontálních oddílů s ID 1 a 2.

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

get_rebalance_table_shards_plan

Vypíše plánované pohyby horizontálních oddílů rebalance_table_shards bez jejich provedení. I když je nepravděpodobné, get_rebalance_table_shards_plan může výstupem trochu jiného plánu, než jaký bude rebalance_table_shards volání se stejnými argumenty dělat. Nespustí se současně, takže fakta o clusteru – například místo na disku – se můžou mezi voláními lišit.

Argumenty

Stejné argumenty jako rebalance_table_shards: relační, prahová hodnota, max_shard_moves, excluded_shard_list a drain_only. Viz dokumentace této funkce pro význam argumentů.

Vrácená hodnota

Řazené kolekce členů obsahující tyto sloupce:

table_name: Tabulka, jejíž horizontální oddíly by se přesunuly.
shardid: Dotyčný horizontální oddíl
shard_size: Velikost v bajtech
sourcename: Název hostitele zdrojového uzlu
sourceport: Port zdrojového uzlu
targetname: Název hostitele cílového uzlu
targetport: Port cílového uzlu

get_rebalance_progress

Jakmile začne vyrovnávání horizontálního oddílu, get_rebalance_progress() funkce uvádí průběh každého zahrnutého horizontálního oddílu. Monitoruje přesuny plánované a spuštěné rebalance_table_shards().

Argumenty

–

Vrácená hodnota

Řazené kolekce členů obsahující tyto sloupce:

sessionid: Postgres PID monitorování rovnováhy
table_name: Tabulka, jejíž horizontální oddíly se přesouvají
shardid: Dotyčný horizontální oddíl
shard_size: Velikost v bajtech
sourcename: Název hostitele zdrojového uzlu
sourceport: Port zdrojového uzlu
targetname: Název hostitele cílového uzlu
targetport: Port cílového uzlu
průběh: 0 = čekání na přesunutí; 1 = přesunutí; 2 = dokončeno

Příklad

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

Připojte řádek k pg_dist_rebalance_strategy .

Argumenty

Další informace otěchtoch pg_dist_rebalance_strategy

name: identifier for the new strategy

shard_cost_function: identifikuje funkci použitou k určení "nákladů" jednotlivých horizontálních oddílů.

node_capacity_function: identifikuje funkci pro měření kapacity uzlu.

shard_allowed_on_node_function: identifikuje funkci, která určuje, které horizontální oddíly lze umístit do kterých uzlů.

default_threshold: prahová hodnota s plovoucí desetinou čárkou, která naladí, jak přesně by měly být náklady na kumulativní horizontální oddíly vyváženy mezi uzly

minimum_threshold: (Volitelné) bezpečnostní sloupec, který obsahuje minimální hodnotu povolenou pro prahový argument rebalance_table_shards(). Výchozí hodnota je 0.

Vrácená hodnota

–

citus_set_default_rebalance_strategy

Aktualizujte tabulku pg_dist_rebalance_strategy a změňte strategii pojmenovanou podle argumentu tak, aby byla při vyrovnávání horizontálních oddílů zvolena jako výchozí.

Argumenty

name: název strategie v pg_dist_rebalance_strategy

Vrácená hodnota

–

Příklad

SELECT citus_set_default_rebalance_strategy('by_disk_size');

citus_remote_connection_stats

Funkce citus_remote_connection_stats() zobrazuje počet aktivních připojení ke každému vzdálenému uzlu.

Argumenty

–

Příklad

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

Tato funkce vytvoří nový horizontální oddíl pro uložení řádků s konkrétní jednou hodnotou v distribučním sloupci. Je to užitečné zejména pro případ použití s více tenanty, kdy velký tenant může být umístěn samostatně na vlastním horizontálním oddílu a nakonec vlastní fyzický uzel.

Argumenty

table_name: Název tabulky pro získání nového horizontálního oddílu.

tenant_id: Hodnota distribučního sloupce, který bude přiřazen k novému horizontálnímu oddílu.

cascade_option: (Volitelné) Pokud je nastavená hodnota CASCADE, izoluje horizontální oddíl také od všech tabulek ve skupině kolokace aktuální tabulky.

Vrácená hodnota

shard_id: Funkce vrátí jedinečné ID přiřazené nově vytvořenému horizontálnímu oddílu.

Příklady

Vytvořte nový horizontální oddíl, který bude obsahovat řádky pro tenanta 135:

SELECT isolate_tenant_to_new_shard('lineitem', 135);

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

Další kroky

Mnoho funkcí v tomto článku upravuje tabulky systémových metadat.
Parametry serveru přizpůsobí chování některých funkcí.

Sdílet prostřednictvím

Funkce Azure Cosmos DB for PostgreSQL

DDL tabulky a horizontálního dělení

citus_schema_distribute

Argumenty

Vrácená hodnota

Příklad

citus_schema_undistribute

Argumenty

Vrácená hodnota

Příklad

create_distributed_table

Argumenty

Vrácená hodnota

Příklad

create_distributed_table_concurrently

truncate_local_data_after_distributing_table

Argumenty

Vrácená hodnota

Příklad

create_reference_table

Argumenty

Vrácená hodnota

Příklad

citus_add_local_table_to_metadata

Argumenty

Vrácená hodnota

Příklad

alter_distributed_table

Argumenty

Vrácená hodnota

Příklad

update_distributed_table_colocation

Argumenty

Vrácená hodnota

Příklad

undistribute_table

Argumenty

Vrácená hodnota

Příklad

create_distributed_function

Argumenty

Vrácená hodnota

Příklad

alter_columnar_table_set

Argumenty

Vrácená hodnota

Příklad

alter_table_set_access_method

Argumenty

Vrácená hodnota

Příklad

create_time_partitions

Argumenty

Vrácená hodnota

Příklad

drop_old_time_partitions

Argumenty

Vrácená hodnota

Příklad

alter_old_partitions_set_access_method

Argumenty

Vrácená hodnota

Příklad

Metadata / informace o konfiguraci

get_shard_id_for_distribution_column

Argumenty

Vrácená hodnota

Příklad

column_to_column_name

Argumenty

Vrácená hodnota

Příklad

citus_relation_size

Argumenty

Vrácená hodnota

Příklad

citus_table_size

Argumenty

Vrácená hodnota