Azure Cosmos DB para funções PostgreSQL

Artigo
08/15/2024

APLICA-SE A: Azure Cosmos DB para PostgreSQL (alimentado pela extensão de banco de dados Citus para PostgreSQL)

Esta seção contém informações de referência para as funções definidas pelo usuário fornecidas pelo Azure Cosmos DB para PostgreSQL. Essas funções ajudam a fornecer funcionalidade distribuída ao Azure Cosmos DB para PostgreSQL.

Nota

clusters que executam versões mais antigas do Citus Engine podem não oferecer todas as funções listadas nesta página.

DDL de mesa e estilhaço

citus_schema_distribute

Converte esquemas regulares existentes em esquemas distribuídos. Os esquemas distribuídos são associados automaticamente a grupos de colocation individuais. As tabelas criadas nesses esquemas são convertidas em tabelas distribuídas colocalizadas sem uma chave de estilhaço. O processo de distribuição do esquema atribui-o automaticamente e move-o para um nó existente no cluster.

Argumentos

schemaname: Nome do esquema, que precisa ser distribuído.

Valor devolvido

N/A

Exemplo

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

Para obter mais exemplos, consulte Como projetar para microsserviços.

citus_schema_undistribute

Converte um esquema distribuído existente novamente em um esquema regular. O processo resulta em tabelas e dados sendo movidos do nó atual de volta para o nó coordenador no cluster.

Argumentos

schemaname: Nome do esquema, que precisa ser distribuído.

Valor devolvido

N/A

Exemplo

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

Para obter mais exemplos, consulte Como projetar para microsserviços.

create_distributed_table

A função create_distributed_table() é usada para definir uma tabela distribuída e criar seus fragmentos se for uma tabela distribuída por hash. Esta função inclui um nome de tabela, a coluna de distribuição e um método de distribuição opcional e insere metadados apropriados para marcar a tabela como distribuída. A função será predefinida para a distribuição “hash” se não for especificado nenhum método de distribuição. Se a tabela for distribuída por hash, a função também criará extensões de trabalho com base nos valores de configuração de fator de replicação de extensões e contagem de extensões. Se a tabela contiver linhas, elas serão distribuídas automaticamente para os nós de trabalho.

Esta função substitui o uso de master_create_distributed_table() seguido por master_create_worker_shards().

Argumentos

table_name: Nome da tabela que precisa ser distribuída.

distribution_column: A coluna na qual a tabela deve ser distribuída.

distribution_type: (Opcional) O método segundo o qual o quadro deve ser distribuído. Os valores admissíveis são acrescentar ou hash, com um valor predefinido de “hash”.

colocate_with: (Opcional) incluir tabela atual no grupo de colocation de outra tabela. Por padrão, as tabelas são colocalizadas quando são distribuídas por colunas do mesmo tipo, têm a mesma contagem de estilhaços e têm o mesmo fator de replicação. Os valores possíveis para colocate_with são default, none para iniciar um novo grupo de colocation ou o nome de outra tabela para colocalizar com essa tabela. (Consulte a colocalização da tabela.)

Tenha em mente que o valor padrão de colocate_with faz colocation implícito. O colocation pode ser uma ótima coisa quando as mesas estão relacionadas ou serão unidas. No entanto, quando duas tabelas não estão relacionadas, mas usam o mesmo tipo de dados para suas colunas de distribuição, colocá-las acidentalmente pode diminuir o desempenho durante o reequilíbrio de estilhaços. Os fragmentos de mesa serão movidos juntos desnecessariamente em uma "cascata".

Se uma nova tabela distribuída não estiver relacionada a outras tabelas, é melhor especificar colocate_with => 'none'.

shard_count: (Opcional) o número de fragmentos a serem criados para a nova tabela distribuída. Ao especificar shard_count , você não pode especificar um valor diferente de colocate_with nenhum. Para alterar a contagem de estilhaços de uma tabela ou grupo de colocation existente, use a função alter_distributed_table .

Os valores possíveis para shard_count estão entre 1 e 64000. Para obter orientação sobre como escolher o valor ideal, consulte Contagem de estilhaços.

Valor devolvido

N/A

Exemplo

Este exemplo informa ao banco de dados que a tabela github_events deve ser distribuída por hash na coluna 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

Esta função tem a mesma interface e finalidade que create_distributed_function, mas não bloqueia gravações durante a distribuição de tabelas.

No entanto, create_distributed_table_concurrently tem algumas limitações:

Você não pode usar a função em um bloco de transação, o que significa que você só pode distribuir uma tabela de cada vez. (No entanto, você pode usar a função em tabelas particionadas por tempo.)
Não é possível usar create_distributed_table_concurrently quando a tabela é referenciada por uma chave estrangeira ou faz referência a outra tabela local. No entanto, as chaves estrangeiras para tabelas de referência funcionam e você pode criar chaves estrangeiras para outras tabelas distribuídas após a conclusão da distribuição da tabela.
Se você não tiver uma chave primária ou identidade de réplica em sua tabela, os comandos de atualização e exclusão falharão durante a distribuição da tabela devido a limitações na replicação lógica.

truncate_local_data_after_distributing_table

Truncar todas as linhas locais depois de distribuir uma tabela e evitar que as restrições falhem devido a registros locais desatualizados. O truncamento cascata para tabelas com uma chave estrangeira para a tabela designada. Se as tabelas de referência não forem distribuídas, então o truncamento é proibido até que o sejam, para proteger a integridade referencial:

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

Truncar dados de tabela de nó coordenador local é seguro para tabelas distribuídas porque suas linhas, se houver, são copiadas para nós de trabalho durante a distribuição.

Argumentos

table_name: Nome da tabela distribuída cuja contraparte local no nó coordenador deve ser truncada.

Valor devolvido

N/A

Exemplo

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

create_reference_table

A função create_reference_table() é usada para definir uma pequena tabela de referência ou dimensão. Essa função recebe um nome de tabela e cria uma tabela distribuída com apenas um fragmento, replicada para cada nó de trabalho.

Argumentos

table_name: Nome da pequena dimensão ou tabela de referência que precisa ser distribuída.

Valor devolvido

N/A

Exemplo

Este exemplo informa ao banco de dados que a tabela de nação deve ser definida como uma tabela de referência

SELECT create_reference_table('nation');

citus_add_local_table_to_metadata

Adiciona uma tabela Postgres local aos metadados do Citus. Um caso de uso importante para essa função é tornar as tabelas locais no coordenador acessíveis a partir de qualquer nó no cluster. Os dados associados à tabela local permanecem no coordenador – apenas seu esquema e metadados são enviados aos trabalhadores.

Adicionar tabelas locais aos metadados tem um pequeno custo. Quando você adiciona a tabela, o Citus deve rastreá-la na tabela de partição. As tabelas locais adicionadas aos metadados herdam as mesmas limitações que as tabelas de referência.

Quando você desdistribui a tabela, o Citus remove as tabelas locais resultantes dos metadados, o que elimina essas limitações nessas tabelas.

Argumentos

table_name: Nome da tabela no coordenador a ser adicionado aos metadados do Citus.

cascade_via_foreign_keys: (Opcional) Quando esse argumento é definido como "true", citus_add_local_table_to_metadata adiciona outras tabelas que estão em uma relação de chave estrangeira com determinada tabela aos metadados automaticamente. Tenha cuidado com esse parâmetro, pois ele pode afetar muitas tabelas.

Valor devolvido

N/A

Exemplo

Este exemplo informa ao banco de dados que a tabela nation deve ser definida como uma tabela coordenador-local, acessível a partir de qualquer nó:

SELECT citus_add_local_table_to_metadata('nation');

alter_distributed_table

A função alter_distributed_table() pode ser usada para alterar a coluna de distribuição, a contagem de estilhaços ou as propriedades de colocation de uma tabela distribuída.

Argumentos

table_name: Nome da tabela que será alterada.

distribution_column: (Opcional) Nome da nova coluna de distribuição.

shard_count: (Opcional) A nova contagem de estilhaços.

colocate_with: (Opcional) A tabela com a qual a tabela distribuída atual será colocalizada. Os valores possíveis são default, none para iniciar um novo grupo de colocation ou o nome de outra tabela com a qual colocar. (Consulte a colocalização da tabela.)

cascade_to_colocated: (Opcional) Quando esse argumento é definido como "true", shard_count e colocate_with as alterações também serão aplicadas a todas as tabelas que foram anteriormente colocalizadas com a tabela, e a colocation será preservada. Se for "falso", a colocalização atual desta tabela será quebrada.

Valor devolvido

N/A

Exemplo

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

A função update_distributed_table_colocation() é usada para atualizar a colocalização de uma tabela distribuída. Esta função também pode ser usada para quebrar a colocalização de uma tabela distribuída. O Azure Cosmos DB para PostgreSQL colocará implicitamente duas tabelas se a coluna de distribuição for do mesmo tipo, isso pode ser útil se as tabelas estiverem relacionadas e fizer algumas junções. Se os quadros A e B forem cocolocados e o quadro A for reequilibrado, o quadro B também será reequilibrado. Se a tabela B não tiver uma identidade de réplica, o reequilíbrio falhará. Portanto, esta função pode ser útil quebrando a colocation implícita nesse caso.

Esta função não move nenhum dado fisicamente.

Argumentos

table_name: Nome da tabela cuja colocation será atualizada.

colocate_with: A tabela à qual a tabela deve ser colocalizada.

Se você quiser quebrar a cocolocação de uma tabela, você deve especificar colocate_with => 'none'.

Valor devolvido

N/A

Exemplo

Este exemplo mostra que a colocalização da tabela A é atualizada como colocation da tabela B.

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

Suponha que a tabela A e a tabela B estão colocalizadas (possivelmente implicitamente), se você quiser quebrar a colocalização:

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

Agora, suponha que a tabela A, a tabela B, a tabela C e a tabela D estão colocalizadas e você deseja colocalizar a tabela A e a tabela B juntas, e a tabela C e a tabela D juntas:

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

Se você tiver uma tabela distribuída por hash chamada none e quiser atualizar sua colocation, poderá fazer:

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

undistribute_table

A função undistribute_table() desfaz a ação de create_distributed_table ou create_reference_table. A desdistribuição move todos os dados dos fragmentos de volta para uma tabela local no nó do coordenador (supondo que os dados possam ajustar) e, em seguida, exclui os fragmentos.

O Azure Cosmos DB para PostgreSQL não desdistribuirá tabelas que tenham ou sejam referenciadas por chaves estrangeiras, a menos que o argumento cascade_via_foreign_keys esteja definido como true. Se esse argumento for falso (ou omitido), você deverá descartar manualmente as restrições de chave estrangeira ofensivas antes de cancelar a distribuição.

Argumentos

table_name: Nome da tabela distribuída ou de referência a ser desdistribuída.

cascade_via_foreign_keys: (Opcional) Quando esse argumento é definido como "true", undistribute_table também desdistribui todas as tabelas relacionadas a table_name por meio de chaves estrangeiras. Tenha cuidado com esse parâmetro, pois ele pode afetar muitas tabelas.

Valor devolvido

N/A

Exemplo

Este exemplo distribui uma github_events tabela e, em seguida, a desdistribui.

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

Propaga uma função do nó coordenador para os trabalhadores e a marca para execução distribuída. Quando uma função distribuída é chamada no coordenador, o Azure Cosmos DB para PostgreSQL usa o valor do "argumento de distribuição" para escolher um nó de trabalho para executar a função. A execução da função em trabalhadores aumenta o paralelismo e pode aproximar o código dos dados em fragmentos para menor latência.

O caminho de pesquisa do Postgres não é propagado do coordenador para os trabalhadores durante a execução da função distribuída, portanto, o código da função distribuída deve qualificar totalmente os nomes dos objetos de banco de dados. Além disso, os avisos emitidos pelas funções não serão exibidos para o usuário.

Argumentos

function_name: Nome da função a ser distribuída. O nome deve incluir os tipos de parâmetros da função entre parênteses, porque várias funções podem ter o mesmo nome no PostgreSQL. Por exemplo, 'foo(int)' é diferente de 'foo(int, text)'.

distribution_arg_name: (Opcional) O nome do argumento pelo qual distribuir. Por conveniência (ou se os argumentos da função não tiverem nomes), um espaço reservado posicional é permitido, como '$1'. Se esse parâmetro não for especificado, a função nomeada por function_name será meramente criada nos trabalhadores. Se nós de trabalho forem adicionados no futuro, a função será criada automaticamente lá também.

colocate_with: (Opcional) Quando a função distribuída lê ou grava em uma tabela distribuída (ou, mais geralmente, grupo de colocation), certifique-se de nomear essa tabela usando o colocate_with parâmetro. Em seguida, cada invocação da função será executada no nó de trabalho contendo fragmentos relevantes.

Valor devolvido

N/A

Exemplo

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

A função alter_columnar_table_set() altera as configurações em uma tabela colunar. Chamar essa função em uma tabela não colunar gera um erro. Todos os argumentos, exceto o nome da tabela, são opcionais.

Para visualizar as opções atuais de todas as tabelas colunares, consulte esta tabela:

SELECT * FROM columnar.options;

Os valores padrão para configurações colunares para tabelas recém-criadas podem ser substituídos por estes GUCs:

columnar.compressão
columnar.compression_level
columnar.stripe_row_count
columnar.chunk_row_count

Argumentos

table_name: Nome da tabela colunar.

chunk_row_count: (Opcional) O número máximo de linhas por bloco para dados recém-inseridos. Os blocos de dados existentes não serão alterados e podem ter mais linhas do que esse valor máximo. O valor padrão é 10000.

stripe_row_count: (Opcional) O número máximo de linhas por faixa para dados recém-inseridos. As faixas de dados existentes não serão alteradas e podem ter mais linhas do que esse valor máximo. O valor padrão é 150000.

compressão: (Opcional) [none|pglz|zstd|lz4|lz4hc] O tipo de compressão para dados recém-inseridos. Os dados existentes não serão recompactados ou descompactados. O valor padrão e sugerido é zstd (se o suporte tiver sido compilado em).

compression_level: (Opcional) As configurações válidas são de 1 a 19. Se o método de compressão não suportar o nível escolhido, será selecionado o nível mais próximo.

Valor devolvido

N/A

Exemplo

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

alter_table_set_access_method

A função alter_table_set_access_method() altera o método de acesso de uma tabela (por exemplo, heap ou colunar).

Argumentos

table_name: Nome da tabela cujo método de acesso será alterado.

access_method: Nome do novo método de acesso.

Valor devolvido

N/A

Exemplo

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

create_time_partitions

A função create_time_partitions() cria partições de um determinado intervalo para cobrir um determinado intervalo de tempo.

Argumentos

table_name: Tabela (regclass) para a qual criar novas partições. A tabela deve ser particionada em uma coluna, do tipo date, timestamp ou timestamptz.

partition_interval: um intervalo de tempo, como '2 hours', ou '1 month', para usar ao definir intervalos em novas partições.

end_at: (timestamptz) Crie partições até este momento. A última partição conterá o ponto end_at, e nenhuma partição posterior será criada.

start_from: (timestamptz, opcional) Escolha a primeira partição para que ela contenha o ponto start_from. O valor predefinido é now().

Valor devolvido

True se precisava criar novas partições, false se todas elas já existiam.

Exemplo

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

A função drop_old_time_partitions() remove todas as partições cujos intervalos caem antes de um determinado carimbo de data/hora. Além de usar essa função, você pode considerar alter_old_partitions_set_access_method compactar as partições antigas com armazenamento colunar.

Argumentos

table_name: (regclass) tabela para a qual remover partições. A tabela deve ser particionada em uma coluna, do tipo date, timestamp ou timestamptz.

older_than: (timestamptz) soltam partições cujo intervalo superior é menor ou igual a older_than.

Valor devolvido

N/A

Exemplo

-- drop partitions that are over a year old

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

alter_old_partitions_set_access_method

Em um caso de uso de séries temporais, as tabelas geralmente são particionadas pelo tempo e as partições antigas são compactadas em armazenamento colunar somente leitura.

Argumentos

parent_table_name: Tabela (regclass) para a qual alterar partições. A tabela deve ser particionada em uma coluna, do tipo date, timestamp ou timestamptz.

older_than: (timestamptz) alterar partições cujo intervalo superior é menor ou igual a older_than.

new_access_method: (nome) «heap» para armazenamento baseado em linha ou «columnar» para armazenamento colunar.

Valor devolvido

N/A

Exemplo

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

Metadados / Informações de configuração

get_shard_id_for_distribution_column

O Azure Cosmos DB para PostgreSQL atribui cada linha de uma tabela distribuída a um fragmento com base no valor da coluna de distribuição da linha e no método de distribuição da tabela. Na maioria dos casos, o mapeamento preciso é um detalhe de baixo nível que o administrador do banco de dados pode ignorar. No entanto, pode ser útil determinar o fragmento de uma linha, seja para tarefas manuais de manutenção de banco de dados ou apenas para satisfazer a curiosidade. A função get_shard_id_for_distribution_column proporciona estas informações para as tabelas de referência, distribuídas por intervalo e distribuídas por hash. Não funciona para a distribuição de acréscimo.

Argumentos

table_name: A tabela distribuída.

distribution_value: O valor da coluna de distribuição.

Valor devolvido

O ID de estilhaço do Azure Cosmos DB para PostgreSQL associa-se ao valor da coluna de distribuição para uma determinada tabela.

Exemplo

SELECT get_shard_id_for_distribution_column('my_table', 4);

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

column_to_column_name

Traduz a partkey coluna de em um nome de pg_dist_partition coluna textual. A tradução é útil para determinar a coluna de distribuição de uma tabela distribuída.

Para uma discussão mais detalhada, consulte a escolha de uma coluna de distribuição.

Argumentos

table_name: A tabela distribuída.

column_var_text: O valor de partkey na pg_dist_partition tabela.

Valor devolvido

O nome da coluna de table_namedistribuição do .

Exemplo

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

Saída:

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

citus_relation_size

Obtenha o espaço em disco usado por todos os fragmentos da tabela distribuída especificada. O espaço em disco inclui o tamanho da "bifurcação principal", mas exclui o mapa de visibilidade e o mapa de espaço livre para os fragmentos.

Argumentos

LogicalRelid: O nome de uma tabela distribuída.

Valor devolvido

Tamanho em bytes como um bigint.

Exemplo

SELECT pg_size_pretty(citus_relation_size('github_events'));

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

citus_table_size

Obtenha o espaço em disco usado por todos os fragmentos da tabela distribuída especificada, excluindo índices (mas incluindo TOAST, mapa de espaço livre e mapa de visibilidade).

Argumentos

LogicalRelid: O nome de uma tabela distribuída.

Valor devolvido

Tamanho em bytes como um bigint.

Exemplo

SELECT pg_size_pretty(citus_table_size('github_events'));

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

citus_total_relation_size

Obtenha o espaço total em disco usado por todos os fragmentos da tabela distribuída especificada, incluindo todos os índices e dados do sistema.

Argumentos

LogicalRelid: O nome de uma tabela distribuída.

Valor devolvido

Tamanho em bytes como um bigint.

Exemplo

SELECT pg_size_pretty(citus_total_relation_size('github_events'));

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

citus_stat_statements_reset

Remove todas as linhas do citus_stat_statements. Esta função funciona independentemente do pg_stat_statements_reset(). Para redefinir todas as estatísticas, chame ambas as funções.

Argumentos

N/A

Valor devolvido

Nenhuma

citus_get_active_worker_nodes

A função citus_get_ative_worker_nodes() retorna uma lista de nomes de host de trabalhador ativo e números de porta.

Argumentos

N/A

Valor devolvido

Lista de tuplas em que cada tupla contém as seguintes informações:

node_name: Nome DNS do nó de trabalho

node_port: Porta no nó de trabalho no qual o servidor de banco de dados está escutando

Exemplo

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

(3 rows)

Gerenciamento e reparo de cluster

master_copy_shard_placement

Se um posicionamento de estilhaço não for atualizado durante um comando de modificação ou uma operação DDL, ele será marcado como inativo. A função master_copy_shard_placement pode então ser chamada para reparar um posicionamento de fragmento inativo usando dados de um posicionamento saudável.

Para reparar um fragmento, a função primeiro descarta o posicionamento do fragmento não íntegro e o recria usando o esquema no coordenador. Depois que o posicionamento do estilhaço é criado, a função copia os dados do posicionamento íntegro e atualiza os metadados para marcar o novo posicionamento do estilhaço como íntegro. Esta função garante que o estilhaço estará protegido de quaisquer modificações simultâneas durante a reparação.

Argumentos

shard_id: ID do fragmento a ser reparado.

source_node_name: Nome DNS do nó no qual o posicionamento do estilhaço íntegro está presente (nó "origem").

source_node_port: A porta no nó de trabalho de origem no qual o servidor de banco de dados está escutando.

target_node_name: Nome DNS do nó no qual o posicionamento do estilhaço inválido está presente (nó "destino").

target_node_port: A porta no nó de trabalho de destino no qual o servidor de banco de dados está escutando.

Valor devolvido

N/A

Exemplo

O exemplo abaixo irá reparar um posicionamento de fragmento inativo do fragmento 12345, que está presente no servidor de banco de dados em execução em 'bad_host' na porta 5432. Para repará-lo, ele usará dados de um posicionamento de fragmento saudável presente no servidor em execução em 'good_host' na porta 5432.

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

master_move_shard_placement

Esta função move um determinado fragmento (e fragmentos colocalizados com ele) de um nó para outro. Normalmente é usado indiretamente durante o rebalanceamento de estilhaços, em vez de ser chamado diretamente por um administrador de banco de dados.

Há duas maneiras de mover os dados: bloqueando ou não bloqueando. A abordagem de bloqueio significa que, durante a movimentação, todas as modificações no estilhaço são pausadas. A segunda maneira, que evita o bloqueio de gravações em estilhaços, depende da replicação lógica do Postgres 10.

Após uma operação de movimentação bem-sucedida, os fragmentos no nó de origem são excluídos. Se a movimentação falhar em algum momento, essa função lançará um erro e deixará os nós de origem e de destino inalterados.

Argumentos

shard_id: ID do fragmento a ser movido.

source_node_name: Nome DNS do nó no qual o posicionamento do estilhaço íntegro está presente (nó "origem").

source_node_port: A porta no nó de trabalho de origem no qual o servidor de banco de dados está escutando.

target_node_name: Nome DNS do nó no qual o posicionamento do estilhaço inválido está presente (nó "destino").

target_node_port: A porta no nó de trabalho de destino no qual o servidor de banco de dados está escutando.

shard_transfer_mode: (Opcional) Especifique o método de replicação, se deseja usar a replicação lógica PostgreSQL ou um comando COPY entre trabalhadores. Os valores possíveis são:

auto: Requer identidade de réplica se a replicação lógica for possível, caso contrário, use um comportamento herdado (por exemplo, para reparo de estilhaços, PostgreSQL 9.6). Este é o valor predefinido.

force_logical: use a replicação lógica mesmo que a tabela não tenha uma identidade de réplica. Qualquer instrução simultânea de atualização/exclusão na tabela falhará durante a replicação.

block_writes: Use COPY (bloqueando gravações) para tabelas sem chave primária ou identidade de réplica.

Valor devolvido

N/A

Exemplo

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

rebalance_table_shards

A função rebalance_table_shards() move fragmentos da tabela dada para distribuí-los uniformemente entre os trabalhadores. A função primeiro calcula a lista de movimentos que precisa fazer para garantir que o cluster esteja equilibrado dentro do limite determinado. Em seguida, ele move os posicionamentos de estilhaços um a um do nó de origem para o nó de destino e atualiza os metadados de fragmento correspondentes para refletir a movimentação.

A cada fragmento é atribuído um custo ao determinar se os fragmentos são "uniformemente distribuídos". Por padrão, cada fragmento tem o mesmo custo (um valor de 1), portanto, distribuir para equalizar o custo entre os trabalhadores é o mesmo que equalizar o número de fragmentos em cada um. A estratégia de custo constante é chamada de "by_shard_count" e é a estratégia de reequilíbrio padrão.

A estratégia "by_shard_count" é adequada nestas circunstâncias:

Os estilhaços têm aproximadamente o mesmo tamanho
Os estilhaços recebem aproximadamente a mesma quantidade de tráfego
Os nós de trabalho são todos do mesmo tamanho/tipo
Os estilhaços não foram fixados a trabalhadores específicos

Se qualquer uma dessas suposições não se sustentar, então reequilibrar "by_shard_count" pode resultar em um plano ruim.

A estratégia de reequilíbrio padrão é "by_disk_size". Você sempre pode personalizar a estratégia, usando o rebalance_strategy parâmetro.

É aconselhável ligar para get_rebalance_table_shards_plan antes de executar rebalance_table_shards, para ver e verificar as ações a serem executadas.

Argumentos

table_name: (Opcional) O nome da tabela cujos estilhaços precisam ser rebalanceados. Se NULL, reequilibre todos os grupos de colocation existentes.

limite: (Opcional) Um número flutuante entre 0,0 e 1,0 que indica a razão de diferença máxima da utilização do nó em relação à utilização média. Por exemplo, especificar 0.1 fará com que o rebalanceador de estilhaços tente equilibrar todos os nós para manter o mesmo número de fragmentos ±10%. Especificamente, o rebalanceador de estilhaços tentará convergir a utilização de todos os nós de trabalho para o (1 - limite) * average_utilization ... (1

limiar) * average_utilization intervalo.

max_shard_moves: (Opcional) O número máximo de fragmentos para mover.

excluded_shard_list: (Opcional) Identificadores de fragmentos que não devem ser movidos durante a operação de reequilíbrio.

shard_transfer_mode: (Opcional) Especifique o método de replicação, se deseja usar a replicação lógica PostgreSQL ou um comando COPY entre trabalhadores. Os valores possíveis são:

auto: Requer identidade de réplica se a replicação lógica for possível, caso contrário, use um comportamento herdado (por exemplo, para reparo de estilhaços, PostgreSQL 9.6). Este é o valor predefinido.

force_logical: use a replicação lógica mesmo que a tabela não tenha uma identidade de réplica. Qualquer instrução simultânea de atualização/exclusão na tabela falhará durante a replicação.

block_writes: Use COPY (bloqueando gravações) para tabelas sem chave primária ou identidade de réplica.

drain_only: (Opcional) Quando verdadeiro, mova fragmentos dos nós de trabalho que definiram shouldhaveshards como falso em pg_dist_node; não mova nenhum outro fragmento.

rebalance_strategy: (Opcional) o nome de uma estratégia no pg_dist_rebalance_strategy. Se esse argumento for omitido, a função escolhe a estratégia padrão, conforme indicado na tabela.

Valor devolvido

N/A

Exemplo

O exemplo abaixo tentará reequilibrar os fragmentos da tabela github_events dentro do limite padrão.

SELECT rebalance_table_shards('github_events');

Este exemplo de uso tentará reequilibrar a tabela github_events sem mover fragmentos com ID 1 e 2.

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

get_rebalance_table_shards_plan

Produza os movimentos de estilhaços planejados de rebalance_table_shards sem executá-los. Embora seja improvável, get_rebalance_table_shards_plan pode produzir um plano ligeiramente diferente do que uma chamada de rebalance_table_shards com os mesmos argumentos fará. Eles não são executados ao mesmo tempo, então os fatos sobre o cluster -- por exemplo, espaço em disco -- podem diferir entre as chamadas.

Argumentos

Os mesmos argumentos que rebalance_table_shards: relação, limiar, max_shard_moves, excluded_shard_list e drain_only. Ver documentação dessa função para o significado dos argumentos.

Valor devolvido

Tuplas contendo estas colunas:

table_name: A mesa cujos estilhaços se moveriam
shardid: O fragmento em questão
shard_size: Tamanho em bytes
sourcename: Nome do host do nó de origem
sourceport: Porta do nó de origem
targetname: Nome do host do nó de destino
targetport: porta do nó de destino

get_rebalance_progress

Uma vez que um reequilíbrio de estilhaço começa, a get_rebalance_progress() função lista o progresso de cada fragmento envolvido. Ele monitora os movimentos planejados e executados pela rebalance_table_shards().

Argumentos

N/A

Valor devolvido

Tuplas contendo estas colunas:

sessionid: Postgres PID do monitor de reequilíbrio
table_name: A mesa cujos estilhaços estão se movendo
shardid: O fragmento em questão
shard_size: Tamanho em bytes
sourcename: Nome do host do nó de origem
sourceport: Porta do nó de origem
targetname: Nome do host do nó de destino
targetport: porta do nó de destino
progresso: 0 = à espera de ser movido; 1 = em movimento; 2 = completo

Exemplo

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

Acrescentar uma linha a pg_dist_rebalance_strategy .

Argumentos

Para obter mais informações sobre esses argumentos, consulte os valores de coluna correspondentes em pg_dist_rebalance_strategy.

nome: identificador da nova estratégia

shard_cost_function: identifica a função usada para determinar o "custo" de cada fragmento

node_capacity_function: identifica a função para medir a capacidade do nó

shard_allowed_on_node_function: identifica a função que determina quais fragmentos podem ser colocados em quais nós

default_threshold: um limite de ponto flutuante que ajusta com que precisão o custo acumulado do estilhaço deve ser balanceado entre nós

minimum_threshold: (Opcional) uma coluna de salvaguarda que contém o valor mínimo permitido para o argumento limiar de rebalance_table_shards(). Seu valor padrão é 0

Valor devolvido

N/A

citus_set_default_rebalance_strategy

Atualize a tabela pg_dist_rebalance_strategy , alterando a estratégia nomeada por seu argumento para ser o padrão escolhido ao reequilibrar fragmentos.

Argumentos

nome: o nome da estratégia em pg_dist_rebalance_strategy

Valor devolvido

N/A

Exemplo

SELECT citus_set_default_rebalance_strategy('by_disk_size');

citus_remote_connection_stats

A função citus_remote_connection_stats() mostra o número de conexões ativas para cada nó remoto.

Argumentos

N/A

Exemplo

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

Esta função cria um novo fragmento para manter linhas com um único valor específico na coluna de distribuição. É especialmente útil para o caso de uso multilocatário, onde um grande locatário pode ser colocado sozinho em seu próprio fragmento e, finalmente, em seu próprio nó físico.

Argumentos

table_name: O nome da tabela para obter um novo fragmento.

tenant_id: O valor da coluna de distribuição que será atribuída ao novo fragmento.

cascade_option: (Opcional) Quando definido como "CASCADE", também isola um fragmento de todas as tabelas no grupo de colocation da tabela atual.

Valor devolvido

shard_id: A função retorna a ID exclusiva atribuída ao fragmento recém-criado.

Exemplos

Crie um novo fragmento para manter os itens de linha para o locatário 135:

SELECT isolate_tenant_to_new_shard('lineitem', 135);

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

Próximos passos

Muitas das funções neste artigo modificam tabelas de metadados do sistema
Os parâmetros do servidor personalizam o comportamento de algumas funções

Partilhar via

Azure Cosmos DB para funções PostgreSQL

DDL de mesa e estilhaço

citus_schema_distribute

Argumentos

Valor devolvido

Exemplo

citus_schema_undistribute

Argumentos

Valor devolvido

Exemplo

create_distributed_table

Argumentos

Valor devolvido

Exemplo

create_distributed_table_concurrently

truncate_local_data_after_distributing_table

Argumentos

Valor devolvido

Exemplo

create_reference_table

Argumentos

Valor devolvido

Exemplo

citus_add_local_table_to_metadata

Argumentos

Valor devolvido

Exemplo

alter_distributed_table

Argumentos

Valor devolvido

Exemplo

update_distributed_table_colocation

Argumentos

Valor devolvido

Exemplo

undistribute_table

Argumentos

Valor devolvido

Exemplo

create_distributed_function

Argumentos

Valor devolvido

Exemplo

alter_columnar_table_set

Argumentos

Valor devolvido

Exemplo

alter_table_set_access_method

Argumentos

Valor devolvido

Exemplo

create_time_partitions

Argumentos

Valor devolvido

Exemplo

drop_old_time_partitions

Argumentos

Valor devolvido

Exemplo

alter_old_partitions_set_access_method

Argumentos

Valor devolvido

Exemplo

Metadados / Informações de configuração

get_shard_id_for_distribution_column

Argumentos

Valor devolvido

Exemplo

column_to_column_name

Argumentos

Valor devolvido

Exemplo

citus_relation_size

Argumentos

Valor devolvido

Exemplo

citus_table_size

Argumentos

Valor devolvido