Compartilhar via

Funções do Azure Cosmos DB for PostgreSQL

  • Artigo

APLICA-SE AO: Azure Cosmos DB for PostgreSQL (da plataforma da extensão de dados Citus para PostgreSQL)

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

Observação

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

DDL de fragmento e tabela

citus_schema_distribute

Converte esquemas regulares existentes em esquemas distribuídos. Esquemas distribuídos são autoassociados com grupos de colocação individuais. As tabelas criadas nesses esquemas são convertidas em tabelas distribuídas colocadas sem uma chave de fragmento. O processo de distribuição do esquema o atribui e move automaticamente para um nó existente no cluster.

Argumentos

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

Retornar valor

N/D

Exemplo

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

Para obter mais exemplos, confira as instruções de design para microsserviços.

citus_schema_undistribute

Converte um esquema distribuído existente novamente em um esquema regular. O processo faz com que as tabelas e os dados sejam movidos do nó atual novamente para o nó coordenador no cluster.

Argumentos

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

Retornar valor

N/D

Exemplo

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

Para obter mais exemplos, confira as instruções de design para microsserviços.

create_distributed_table

A função create_distributed_table() é usada para definir uma tabela distribuída e criar os fragmentos, caso ela seja uma tabela distribuída por hash. Essa função usa um nome de tabela, a coluna de distribuição e um método de distribuição opcional e insere os metadados apropriados para marcar a tabela como distribuída. A função usa como padrão a distribuição 'hash' se nenhum método de distribuição for especificado. Se a tabela for distribuída por hash, a função também criará fragmentos de trabalho com base nos valores de configuração de fator de replicação de fragmento e contagem de fragmentos. Se a tabela contiver linhas, elas serão distribuídas automaticamente aos nós de trabalho.

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

Argumentos

table_name: o 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 de acordo com o qual a tabela deve ser distribuída. Os valores permitidos são append ou hash, com um valor padrão de 'hash'.

colocate_with: (opcional) inclui a tabela atual no grupo de colocação de outra tabela. Por padrão, as tabelas são colocadas quando são distribuídas por colunas do mesmo tipo, têm a mesma contagem de fragmentos e o mesmo fator de replicação. Os valores possíveis para colocate_with são default, none, que inicia um novo grupo de colocação, ou o nome de outra tabela a ser colocada com essa tabela. (Confira colocação de tabela.)

Tenha em mente que o valor padrão de colocate_with realiza a colocação implícita. A colocação pode ser positiva quando as tabelas estão relacionadas ou serão unidas. No entanto, quando duas tabelas não são relacionadas, mas usam o mesmo tipo de dados nas colunas de distribuição, a colocação acidental delas pode diminuir o desempenho durante o rebalanceamento de fragmento. Os fragmentos de tabela serão movidos conjuntamente sob efeito cascata, desnecessariamente.

Se uma nova tabela distribuída não está 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 de colocate_with diferente de nenhum. Para alterar a contagem de fragmentos de uma tabela ou grupo de colocação existente, use a função alter_distributed_table.

Os valores possíveis de shard_count estão entre 1 e 64000. Para obter diretrizes sobre como escolher o valor ideal, consulte Contagem de fragmentos.

Retornar valor

N/D

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

Essa função tem a mesma interface e finalidade da create_distributed_function, mas não bloqueia gravações durante a distribuição da tabela.

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 por vez. (No entanto, você pode usar a função em tabelas particionadas por tempo.)
  • Você não pode 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 atualizar e excluir falharão durante a distribuição da tabela devido a limitações na replicação lógica.

truncate_local_data_after_distributing_table

Trunque todas as linhas locais depois de distribuir uma tabela e impeça que as restrições falhem devido a registros locais desatualizados. O truncamento em cascata resulta nas tabelas terem uma chave estrangeira para a tabela designada. Se as tabelas de referência não forem distribuídas, o truncamento será proibido até que elas o sejam, a fim de proteger a integridade referencial:

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

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

Argumentos

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

Retornar valor

N/D

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 referência ou tabela de dimensões. Essa função usa um nome de tabela e cria uma tabela distribuída com apenas um fragmento, replicado para cada nó de trabalho.

Argumentos

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

Retornar valor

N/D

Exemplo

Este exemplo informa ao banco de dados que a tabela nation deve ser definida como uma tabela de referência

SELECT create_reference_table('nation');

citus_add_local_table_to_metadata

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

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ê não distribui 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 em metadados automaticamente. Tenha cuidado com esse parâmetro, pois ele tem o potencial de afetar muitas tabelas.

Retornar valor

N/D

Exemplo

Este exemplo informa ao banco de dados que a tabela nation deve ser definida como uma tabela local do coordenador, acessível em 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 fragmentos ou as propriedades de colocação de uma tabela distribuída.

Argumentos

table_name: corresponde ao nome da tabela que será alterada.

distribution_column: (opcional) corresponde ao nome da nova coluna de distribuição.

shard_count: (opcional) corresponde à nova contagem de fragmentos.

colocate_with: (opcional) corresponde à tabela com a qual a tabela distribuída atual será colocada. Os valores possíveis são default, none para iniciar um novo grupo de colocação ou o nome de outra tabela com a qual colocar. (Confira colocação de tabela.)

cascade_to_colocated: (opcional) quando esse argumento é definido como "true", as alterações shard_count e colocate_with também serão aplicadas a todas as tabelas que foram previamente colocadas com a tabela e a colocação será preservada. Se for "false", a colocação atual desta tabela será quebrada.

Retornar valor

N/D

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 colocação de uma tabela distribuída. Essa função também pode ser usada para quebrar a colocação de uma tabela distribuída. O Azure Cosmos DB for PostgreSQL colocará implicitamente duas tabelas se a coluna de distribuição for do mesmo tipo; isso poderá ser útil se as tabelas estiverem relacionadas e fizerem algumas junções. Se as tabelas A e B estiverem colocadas e a tabela A for rebalanceada, a tabela B também será rebalanceada. Se a tabela B não tiver uma identidade de réplica, o rebalanceamento falhará. Portanto, essa função pode ser útil para quebrar a colocação implícita nesse caso.

Essa função não move nenhum dados fisicamente.

Argumentos

table_name: corresponde ao nome da colocação da tabela da qual será atualizada.

colocate_with: corresponde à tabela com a qual a tabela deve ser colocada.

Se você quiser interromper a colocação de uma tabela, deverá especificar colocate_with => 'none'.

Retornar valor

N/D

Exemplo

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

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

Suponha que a tabela A e a tabela B estejam colocadas (possivelmente de modo implícito) e você deseja quebrar a colocaçã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 estejam colocadas e você queira colocar 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 colocação, você poderá:

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

undistribute_table

A função undistribute_table() desfaz a ação do comando create_distributed_table ou do comando create_reference_table. O cancelamento da distribuição move todos os dados dos fragmentos de volta para uma tabela local no nó coordenador (supondo que os dados caibam), depois exclui os fragmentos.

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

Argumentos

table_name: nome da tabela distribuída ou de referência a cancelar a distribuição.

cascade_via_foreign_keys: (opcional) quando esse argumento for definido como "true", o undistribute_table também cancelará a distribuição de todas as tabelas relacionadas ao table_name por meio de chaves estrangeiras. Tenha cuidado com esse parâmetro, pois ele tem o potencial de afetar muitas tabelas.

Retornar valor

N/D

Exemplo

Este exemplo distribui uma tabela github_events, depois cancela a distribuição dela.

-- 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 trabalhos e marca-a para execução distribuída. Quando uma função distribuída é chamada no coordenador, o Azure Cosmos DB for 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 nos trabalhos aumenta o paralelismo e pode trazer o código mais próximo aos dados em fragmentos para uma latência mais baixa.

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

Argumentos

function_name: o nome da função a ser distribuída. O nome precisa incluir os tipos de parâmetro da função entre parênteses, pois 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. Para maior conveniência (ou se os argumentos de função não tiverem nomes), um espaço reservado posicional pode ser usado, tal como '$1'. Se esse parâmetro não for especificado, a função nomeada por function_name será simplesmente criada nos trabalhos. Se os nós de trabalho forem adicionados no futuro, a função será automaticamente criada neles.

colocate_with: (opcional) quando a função distribuída lê ou grava em uma tabela distribuída (ou, mais comumente, no grupo de colocação), nomeie essa tabela usando o parâmetro colocate_with. Em seguida, cada invocação da função será executada no nó de trabalho que contém os fragmentos relevantes.

Retornar valor

N/D

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 na tabela em coluna. Chamar essa função em uma tabela sem coluna gera um erro. Todos os argumentos, exceto o nome da tabela, são opcionais.

Para exibir as opções atuais de todas as tabelas em coluna, confira esta tabela:

SELECT * FROM columnar.options;

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

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

Argumentos

table_name: nome da tabela em coluna.

chunk_row_count: (opcional) o número máximo de linhas por parte para dados recém-inseridos. As partes de dados existentes não serão alteradas e poderão 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 faixas para dados recém-inseridos. As faixas de dados existentes não serão alteradas e poderão ter mais linhas do que esse valor máximo. O valor padrão é 150000.

compression: (opcional) [none|pglz|zstd|lz4|lz4hc] o tipo de compactação para dados recém-inseridos. Os dados existentes não serão compactados nem descompactados. O valor padrão e sugerido é zstd (se o suporte tiver sido compilado).

compression_level: (opcional) as configurações válidas são de 1 a 19. Se o método de compactação não dá suporte ao nível escolhido, o nível mais próximo será selecionado.

Retornar valor

N/D

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, por heap ou colunas).

Argumentos

table_name: corresponde ao nome da tabela cujo método de acesso será alterado.

access_method: corresponde ao nome do novo método de acesso.

Retornar valor

N/D

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 abranger um determinado intervalo de tempo.

Argumentos

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

partition_interval: corresponde a um intervalo de tempo, tal como '2 hours' ou '1 month', a ser usado ao definir intervalos nas novas partições.

end_at: (timestamptz) crie partições até este horário. 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 padrão é now().

Retornar valor

True se for necessário criar novas partições, false se todas elas já existirem.

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 se enquadram antes de um determinado carimbo de data/hora. Além de usar essa função, você pode considerar usar o método alter_old_partitions_set_access_method para compactar as partições antigas com o armazenamento por colunas.

Argumentos

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

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

Retornar valor

N/D

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 por tempo e as partições antigas são compactadas no armazenamento somente leitura por colunas.

Argumentos

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

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

new_access_method: (nome) 'heap' para armazenamento baseado em linhas ou 'columnar' para armazenamento para colunas.

Retornar valor

N/D

Exemplo

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

Informações de metadados/configuração

get_shard_id_for_distribution_column

O Azure Cosmos DB for PostgreSQL atribui todas as linhas 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 de banco de dados pode ignorar. No entanto, pode ser útil determinar o fragmento de uma linha para tarefas manuais de manutenção de banco de dados ou apenas por curiosidade. A função get_shard_id_for_distribution_column fornece essas informações de tabelas distribuídas por hash e por intervalo e tabelas de referência. Isso 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.

Retornar valor

O Azure Cosmos DB for PostgreSQL de ID de fragmento se associa ao valor da coluna de distribuição da tabela especificada.

Exemplo

SELECT get_shard_id_for_distribution_column('my_table', 4);

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

column_to_column_name

Move a coluna partkey de pg_dist_partition para um nome de coluna textual. Essa movimentação é útil para determinar a coluna de distribuição de uma tabela distribuída.

Para ver uma discussão mais aprofundada, confira como escolher uma coluna de distribuição.

Argumentos

table_name: a tabela distribuída.

column_var_text: o valor de partkey na tabela pg_dist_partition.

Retornar valor

O nome da coluna de distribuição de table_name.

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 do "fork principal", mas exclui o mapa de visibilidade e o mapa de espaço livre dos fragmentos.

Argumentos

logicalrelid: o nome de uma tabela distribuída.

Retornar valor

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 os índices (mas incluindo a notificação do sistema, o mapa de espaço livre e o mapa de visibilidade).

Argumentos

logicalrelid: o nome de uma tabela distribuída.

Retornar valor

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 em disco total usado por todos os fragmentos da tabela distribuída especificada, incluindo todos os índices e dados de notificação do sistema.

Argumentos

logicalrelid: o nome de uma tabela distribuída.

Retornar valor

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 de citus_stat_statements. Essa função funciona independentemente do pg_stat_statements_reset(). Para redefinir todas as estatísticas, chame ambas as funções.

Argumentos

N/D

Retornar valor

Nenhum

citus_get_active_worker_nodes

A função citus_get_active_worker_nodes() retorna uma lista de nomes de host de trabalho ativos e números de porta.

Argumentos

N/D

Retornar valor

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 em que 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 fragmento não for atualizado durante um comando de modificação ou em uma operação de DDL, ele será marcado como inativo. A função master_copy_shard_placement pode ser chamada para reparar um posicionamento de fragmento inativo usando dados de um posicionamento íntegro.

Para reparar um fragmento, primeiro a função remove o posicionamento do fragmento não íntegro e o recria usando o esquema no coordenador. Depois que o posicionamento do fragmento é criado, a função copia dados do posicionamento íntegro e atualiza os metadados para marcar o novo posicionamento do fragmento como íntegro. Essa função garante que o fragmento será protegido contra qualquer modificação simultânea durante o reparo.

Argumentos

shard_id: a ID do fragmento que será reparado.

source_node_name: o nome DNS do nó no qual o posicionamento do fragmento íntegro está presente (nó de "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: o nome DNS do nó no qual o posicionamento de fragmento inválido está presente (nó de "destino").

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

Retornar valor

N/D

Exemplo

O exemplo a seguir repara um posicionamento de fragmento inativo do fragmento 12345, que está presente no servidor de banco de dados que está sendo executado em 'bad_host' na porta 5432. Para repará-lo, ele usará dados de um posicionamento de fragmento íntegro presente no servidor que está sendo executado no 'good_host' na porta 5432.

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

master_move_shard_placement

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

Há duas maneiras de mover os dados: com bloqueio ou sem bloqueio. A abordagem com bloqueio significa que, durante a movimentação, todas as modificações no fragmento são colocadas em pausa. A segunda maneira, que evita o bloqueio de gravações de fragmento, 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 tem uma falha a qualquer momento, essa função gera um erro e deixa os nós de origem e de destino inalterados.

Argumentos

shard_id: a ID do fragmento que será movido.

source_node_name: o nome DNS do nó no qual o posicionamento do fragmento íntegro está presente (nó de "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: o nome DNS do nó no qual o posicionamento de fragmento inválido está presente (nó de "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 a ser usado, definindo se deseja usar a replicação lógica do PostgreSQL ou um comando COPY entre trabalhos. Os valores possíveis são:

  • auto: exigirá a identidade de réplica se a replicação lógica for possível; caso contrário, usará o comportamento herdado (por exemplo, para reparo de fragmentos no PostgreSQL 9.6). Esse é o valor padrão.
  • force_logical: use a replicação lógica, mesmo que a tabela não tenha uma identidade de réplica. Todas as instruções de atualização/exclusão simultâneas para a tabela falharão durante a replicação.
  • block_writes: use COPY (bloqueio de gravações) em tabelas que não têm a chave primária ou a identidade de réplica.

Retornar valor

N/D

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 determinada para distribuí-los de maneira uniforme entre os trabalhos. Primeiro a função calcula a lista de movimentações que precisa fazer para garantir que o cluster seja balanceado dentro do limite fornecido. Em seguida, ele move os posicionamentos de fragmentos um de cada vez do nó de origem para o nó de destino e atualiza os metadados de fragmento correspondentes para refletir essa movimentação.

Cada fragmento recebe um custo ao determinar se os fragmentos são "distribuídos uniformemente". Por padrão, cada fragmento tem o mesmo custo (um valor de 1), portanto, a distribuição para equalizar o custo nos trabalhos é igual à equalização do número de fragmentos em cada trabalho. A estratégia de custo constante é chamada de "by_shard_count" e é a estratégia de rebalanceamento padrão.

A estratégia "by_shard_count" é apropriada nas seguintes circunstâncias:

  • Os fragmentos são aproximadamente do mesmo tamanho
  • Os fragmentos recebem aproximadamente a mesma quantidade de tráfego
  • Os nós de trabalho são todos do mesmo tamanho/tipo
  • Os fragmentos não foram fixados a determinados trabalhos

Se qualquer uma dessas suposições não for verdadeira, o rebalanceamento de “by_shard_count” poderá resultar em um plano inválido.

A estratégia de rebalanceamento padrão é “by_disk_size”. Você sempre pode personalizar a estratégia usando o parâmetro rebalance_strategy.

É aconselhável chamar 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 fragmentos precisam ser rebalanceados. Se for NULL, balanceie novamente todos os grupos de colocação existentes.

threshold: (Opcional) um número flutuante entre 0,0 e 1,0 que indica a razão de diferença máxima de utilização de nó por meio da utilização média. Por exemplo, especificar 0,1 fará com que o rebalanceador de fragmentos tente balancear todos os nós para manter o mesmo número de fragmentos a ±10%. Especificamente, o rebalanceador de fragmentos tentará convergir a utilização de todos os nós de trabalho para o intervalo (1 – limite) * average_utilization ... (1

  • limite) * average_utilization.

max_shard_moves: (opcional) o número máximo de fragmentos a serem movidos.

excluded_shard_list: (opcional) identificadores de fragmentos que não devem ser movidos durante a operação de rebalanceamento.

shard_transfer_mode: (opcional) especifique o método de replicação a ser usado, definindo se deseja usar a replicação lógica do PostgreSQL ou um comando COPY entre trabalhos. Os valores possíveis são:

  • auto: exigirá a identidade de réplica se a replicação lógica for possível; caso contrário, usará o comportamento herdado (por exemplo, para reparo de fragmentos no PostgreSQL 9.6). Esse é o valor padrão.
  • force_logical: use a replicação lógica, mesmo que a tabela não tenha uma identidade de réplica. Todas as instruções de atualização/exclusão simultâneas para a tabela falharão durante a replicação.
  • block_writes: use COPY (bloqueio de gravações) em tabelas que não têm a chave primária ou a identidade de réplica.

drain_only: (opcional) quando é definido como true, ele retira os fragmentos de nós de trabalho que têm shouldhaveshards definido como false no pg_dist_node. Não mova nenhum outro fragmento.

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

Retornar valor

N/D

Exemplo

O exemplo a seguir tentará rebalancear os fragmentos da tabela github_events dentro do limite padrão.

SELECT rebalance_table_shards('github_events');

Este exemplo de uso tentará rebalancear a tabela github_events sem mover fragmentos com as IDs 1 e 2.

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

get_rebalance_table_shards_plan

Gere os movimentos do fragmento planejados de rebalance_table_shards sem executá-los. Embora seja improvável, o get_rebalance_table_shards_plan pode gerar um plano um pouco diferente do que uma chamada rebalance_table_shards com os mesmos argumentos. Elas não são executadas ao mesmo tempo, portanto, os fatos sobre o cluster – por exemplo, espaço em disco – podem ser diferentes entre as chamadas.

Argumentos

Os mesmo argumentos que rebalance_table_shards: relation, threshold, max_shard_moves, excluded_shard_list e drain_only. Confira a documentação dessa função para obter o significado dos argumentos.

Retornar valor

Tuplas que contêm estas colunas:

  • table_name: a tabela cujos fragmentos seriam movidos
  • shardid: o fragmento em questão
  • shard_size: o tamanho em bytes
  • sourcename: o nome do host do nó de origem
  • sourceport: a porta do nó de origem
  • targetname: o nome do host do nó de destino
  • targetport: a porta do nó de destino

get_rebalance_progress

Quando um rebalanceamento de fragmentos começa, a função get_rebalance_progress() lista o progresso de cada fragmento envolvido. Ele monitora as movimentações planejadas e executadas pelo rebalance_table_shards().

Argumentos

N/D

Retornar valor

Tuplas que contêm estas colunas:

  • sessionid: o PID do Postgres do monitor de rebalanceamento
  • table_name: a tabela cujos fragmentos estão sendo movidos
  • shardid: o fragmento em questão
  • shard_size: o tamanho em bytes
  • sourcename: o nome do host do nó de origem
  • sourceport: a porta do nó de origem
  • targetname: o nome do host do nó de destino
  • targetport: a porta do nó de destino
  • progress: 0 = aguardando ser movido; 1 = sendo movido; 2 = concluído

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, confira os valores de coluna correspondentes em pg_dist_rebalance_strategy.

name: o identificador para a 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 usada 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 o quão precisamente o custo de fragmento cumulativo deve ser balanceado entre os nós

minimum_threshold: (opcional) uma coluna de garantia que contém o valor mínimo permitido para o argumento de limite de rebalance_table_shards(). O valor padrão é 0

Retornar valor

N/D

citus_set_default_rebalance_strategy

Atualize a tabela pg_dist_rebalance_strategy, alterando a estratégia nomeada pelo argumento como o padrão escolhido ao rebalancear fragmentos.

Argumentos

name: o nome da estratégia em pg_dist_rebalance_strategy

Retornar valor

N/D

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

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

Essa função cria um fragmento para armazenar linhas com um valor específico na coluna de distribuição. Ela é especialmente útil para o caso de uso de multilocatário, em que um locatário maior pode ser colocado sozinho em um fragmento próprio e, em última instância, no próprio nó físico.

Argumentos

table_name: o nome da tabela na qual será obtido 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 colocação da tabela atual.

Retornar valor

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

Exemplos

Crie um fragmento para manter o lineitems do locatário 135:

SELECT isolate_tenant_to_new_shard('lineitem', 135);

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

Próximas etapas