Exercício - Explore como o Citus distribui tabelas

  • 10 minutos

Neste exercício, você cria um banco de dados do Azure Cosmos DB para PostgreSQL com vários nós. Em seguida, você criará algumas tabelas antes de executar algumas consultas em seu banco de dados para saber mais sobre a arquitetura distribuída fornecida pela extensão Citus para PostgreSQL.

Criar um banco de dados do Azure Cosmos DB para PostgreSQL

Para concluir este exercício, você deve criar um Azure Cosmos DB para o cluster PostgreSQL. Seu cluster terá:

  • Um nó coordenador, com 4 vCores, RAM de 16 GiB e 512 GiBM de armazenamento
  • Dois nós de trabalho, cada um com 4 vCores, RAM de 32 GiB e 512 GiBM de armazenamento

  1. Navegue até o portal do Azure em um navegador da Web.

  2. No portal do Azure, selecione Criar um recurso, Bancos de Dados e Azure Cosmos DB. Você também pode usar a funcionalidade Pesquisar para localizar o recurso.

    Screenshot of the Azure portal's create a resource screen where Databases and Azure Cosmos DB are highlighted.

  3. Na tela de opção Selecionar API, selecione Criar no bloco do Azure Cosmos DB para PostgreSQL .

    Screenshot of the Azure Cosmos DB for PostgreSQL tile that is highlighted on the Azure Cosmos DB Select API option dialog.

    Nota

    Depois de selecionar Criar, o portal exibirá uma tela de configuração do banco de dados.

  4. No separador Informações Básicas, introduza as seguintes informações:

    Parâmetro Valor
    Detalhes do projeto
    Subscrição Escolha a sua subscrição do Azure.
    Grupo de recursos Selecione Criar novo e nomeie seu grupo learn-cosmosdb-postgresqlde recursos .
    Detalhes do cluster
    Nome do cluster Insira um nome globalmente exclusivo, como learn-cosmosdb-postgresql.
    Localização Deixe o padrão ou use uma região próxima a você.
    Escala Consulte as definições de configuração na próxima etapa.
    Versão do PostgreSQL Deixe a versão padrão (15) selecionada.
    Conta de administrador
    Nome de utilizador de administrador Este nome de utilizador está definido como citus e não pode ser editado.
    Password Introduza e confirme uma palavra-passe forte.

    Screenshot of the Basics tab of the Create an Azure Cosmos DB - PostgreSQL cluster dialog. The fields are populated with the values specified in the exercise.

    Anote a senha para uso posterior.

  5. Para a configuração Dimensionar , selecione Configurar e, na página de configuração do nó, defina o seguinte:

    Parâmetro Valor
    Nós
    Contagens de nós Escolha 2 nós.
    Computação por nó Selecione 4 vCores, 32 GiB RAM.
    Armazenamento por nó Selecione 512 GiBM.
    Coordenador (Talvez seja necessário expandir esta seção)
    Coordenador de computação Selecione 4 vCores, 16 GiB RAM.
    Coordenador de armazenamento Selecione 512 GiBM.

    Os recursos de alta disponibilidade e failover automático estão fora do escopo deste exercício, portanto, deixe a caixa de seleção Alta disponibilidade desmarcada.

    Screenshot of the Create an Azure Cosmos DB - PostgreSQL cluster configuration dialog.

  6. Selecione Salvar na página de escala para retornar à configuração do cluster.

  7. Selecione o botão Next : Networking > para ir para a guia Rede da caixa de diálogo de configuração.

  8. Na guia Rede, defina o método Conectividade como Acesso público (endereços IP permitidos) e marque a caixa Permitir acesso público dos serviços e recursos do Azure no Azure para este cluster.

    Screenshot of the Create an Azure Cosmos DB - PostgreSQL cluster Networking tab. The settings specified in the exercise are highlighted.

  9. Selecione o botão Rever + criar e, em seguida, selecione Criar no ecrã de revisão para criar o cluster.

Conectar-se ao banco de dados usando psql no Azure Cloud Shell

  1. Depois que o cluster do Azure Cosmos DB para PostgreSQL concluir o provisionamento, navegue até o recurso no portal do Azure.

  2. No menu de navegação à esquerda, selecione Cadeias de conexão em Configurações e copie a cadeia de conexão rotulada psql.

    Screenshot of the Connection strings page of the Azure Cosmos DB Cluster resource.

  3. Cole a cadeia de conexão em um editor de texto, como o Bloco de Notas, e substitua o token pela senha atribuída ao usuário ao criar o {your_password}citus cluster. Copie a cadeia de conexão atualizada para uso abaixo.

  4. Abra o Azure Cloud Shell em um navegador da Web.

  5. Selecione Bash como o ambiente.

    Screenshot of the welcome page of Azure Cloud Shell with a prompt to choose an environment between Bash or PowerShell. Bash is highlighted.

  6. Se solicitado, selecione a assinatura usada para sua conta do Azure Cosmos DB para PostgreSQL. Em seguida, selecione Criar armazenamento.

    Screenshot of the Azure Cloud Shell wizard showing no storage mounted is displayed. Azure Subscription is showing in the Subscription dropdown.

  7. Agora, use o utilitário de linha de comando psql para se conectar ao seu banco de dados. Cole sua cadeia de conexão atualizada (aquela que contém sua senha correta) no prompt no Cloud Shell e execute o comando, que deve ser semelhante ao seguinte comando:

    psql "host=c.learn-cosmosdb-postgresql.postgres.database.azure.com port=5432 dbname=citus user=citus password=P@ssword.123! sslmode=require"

Descubra informações sobre os nós em seu cluster

As tabelas de metadados do coordenador contêm informações sobre nós de trabalho no cluster.

  1. Execute a seguinte consulta na tabela pg_dist_node do nó de trabalho para exibir informações sobre os nós no cluster:

    -- Turn on expanded display to pivot the results 
\x

    -- Retrieve node details
SELECT * FROM pg_dist_node;

  2. Analise a saída da consulta para obter detalhes, incluindo a ID, o nome e a porta associados a cada nó. Além disso, você pode ver se o nó está ativo e deve conter fragmentos, entre outros bits de informação.

    -[ RECORD 1 ]----+-----------------------------------------------------------------
nodeid           | 2
groupid          | 2
nodename         | private-w1.learn-cosmosdb-postgresql.postgres.database.azure.com
nodeport         | 5432
noderack         | default
hasmetadata      | t
isactive         | t
noderole         | primary
nodecluster      | default
metadatasynced   | t
shouldhaveshards | t
-[ RECORD 2 ]----+-----------------------------------------------------------------
nodeid           | 3
groupid          | 3
nodename         | private-w0.learn-cosmosdb-postgresql.postgres.database.azure.com
nodeport         | 5432
noderack         | default
hasmetadata      | t
isactive         | t
noderole         | primary
nodecluster      | default
metadatasynced   | t
shouldhaveshards | t
-[ RECORD 3 ]----+-----------------------------------------------------------------
nodeid           | 4
groupid          | 0
nodename         | private-c.learn-cosmosdb-postgresql.postgres.database.azure.com
nodeport         | 5432
noderack         | default
hasmetadata      | t
isactive         | t
noderole         | primary
nodecluster      | default
metadatasynced   | t
shouldhaveshards | f

    Você pode usar os nomes de nó e os números de porta fornecidos na saída para se conectar diretamente aos trabalhadores, o que é uma prática comum ao ajustar o desempenho da consulta. Conectar-se diretamente a nós de trabalho requer que a caixa de seleção Habilitar acesso aos nós de trabalho seja marcada na página Rede do seu recurso Azure Cosmos DB para PostgreSQL no portal do Azure.

    Screenshot of the enable access to the worker nodes option in the Networking section. Networking is highlighted and selected in the left-hand navigation menu.

Criar tabelas distribuídas

Agora que você está conectado ao seu banco de dados, você pode começar a preencher o banco de dados. Você usará psql para:

  • Crie usuários e tabelas de pagamento.
  • Instrua o Citus a distribuir ambas as tabelas, fragmentando-as pelos nós de trabalho.

As tabelas distribuídas são particionadas horizontalmente entre os nós de trabalho disponíveis. Essa distribuição significa que as linhas da tabela são armazenadas em nós diferentes em tabelas de fragmentos chamadas fragmentos.

  1. No Cloud Shell, execute a seguinte consulta para criar as payment_users tabelas e payment_events :

    CREATE TABLE payment_users
(
    user_id bigint PRIMARY KEY,
    url text,
    login text,
    avatar_url text
);

CREATE TABLE payment_events
(
    event_id bigint,
    event_type text,
    user_id bigint,
    merchant_id bigint,
    event_details jsonb,
    created_at timestamp,
    -- Create a compound primary key so that user_id can be set as the distribution column
    PRIMARY KEY (event_id, user_id)
);

    A PRIMARY KEY atribuição para a payment_events tabela é uma chave composta, permitindo que o user_id campo seja atribuído como a coluna de distribuição.

  2. Quando os CREATE TABLE comandos são executados, tabelas locais são criadas no nó coordenador. Para distribuir as tabelas para os nós de trabalho, você deve executar a create_distributed_table função para cada tabela, especificando qual coluna de distribuição usar ao fragmentá-las. No Cloud Shell, execute a seguinte consulta para distribuir suas payment_events tabelas e payment_users pelos nós de trabalho:

    SELECT create_distributed_table('payment_users', 'user_id');
SELECT create_distributed_table('payment_events', 'user_id');

    payment_events As tabelas e payment_users receberam a mesma coluna de distribuição, resultando em dados relacionados para ambas as tabelas sendo colocalizados no mesmo nó. Os detalhes sobre a seleção da coluna de distribuição correta estão fora do escopo deste módulo de aprendizagem. Ainda assim, você pode saber mais sobre isso lendo o artigo Escolher colunas de distribuição no Azure Cosmos DB para PostgreSQL nos documentos da Microsoft.

Criar uma tabela de referência

Em seguida, você usará psql para:

  • Crie a tabela de comerciantes.
  • Instrua o Citus a distribuir a tabela inteira como uma tabela de referência em cada nó de trabalho.

Uma tabela de referência é uma tabela distribuída cujo conteúdo inteiro está concentrado em um único fragmento replicado em cada trabalhador. As consultas em qualquer trabalhador podem acessar as informações de referência localmente sem a sobrecarga de rede de solicitar linhas de outro nó. As tabelas de referência não exigem a especificação de uma coluna de distribuição, porque não há necessidade de distinguir fragmentos diferentes por linha. As tabelas de referência geralmente são pequenas e usadas para armazenar dados relevantes para consultas em execução em qualquer nó de trabalho.

  1. No Cloud Shell, execute a seguinte consulta para criar a payment_merchants tabela:

    CREATE TABLE payment_merchants
(
    merchant_id bigint PRIMARY KEY,
    name text,
    url text
);

  2. Em seguida, use a função para distribuir a create_reference_table() tabela para cada nó de trabalho.

    SELECT create_reference_table('payment_merchants');

Carregar dados na tabela de eventos

O Woodgrove Bank forneceu seus dados históricos de eventos em um arquivo CSV, para que você tenha alguns dados para trabalhar durante a instalação e teste das extensões solicitadas. Eles fornecerão dados do usuário por meio de uma conta segura de armazenamento de blob do Azure para que você preencha a payment_users tabela no próximo exercício. O events.csv ficheiro está disponível através de um URL acessível publicamente.

Você pode usar o COPY comando para executar uma carga em massa única desses dados na payment_events tabela.

  1. Execute o seguinte comando para baixar arquivos CSV contendo informações de usuário e pagamento e, em seguida, use o COPY comando para carregar dados dos arquivos CSV baixados nas tabelas distribuídas e payment_events: payment_users

    SET CLIENT_ENCODING TO 'utf8';

\COPY payment_events FROM PROGRAM 'curl https://raw.githubusercontent.com/MicrosoftDocs/mslearn-create-connect-postgresHyperscale/main/events.csv' WITH CSV

    COPY No comando emitido, a FROM PROGRAM cláusula informa o coordenador para recuperar os arquivos de dados de um aplicativo em execução no coordenador, neste caso, curl. A WITH CSV opção fornece informações sobre o formato do arquivo que está sendo ingerido.

  2. Execute os seguintes comandos para verificar se os dados foram carregados na payment_events tabela usando o COPY comando.

    SELECT COUNT(*) FROM payment_events;

Ver detalhes sobre as tabelas distribuídas

Agora que você criou algumas tabelas distribuídas, vamos usar a citus_tables exibição para inspecionar essas tabelas.

  1. Execute a seguinte consulta para exibir os detalhes de suas tabelas distribuídas:

    SELECT table_name, citus_table_type, distribution_column, table_size, shard_count FROM citus_tables;

  2. Observe a saída da consulta e os detalhes que ela fornece.

    table_name        | citus_table_type | distribution_column | table_size | shard_count 
------------------+------------------+---------------------+------------+-------------
payment_events    | distributed      | user_id             | 26 MB      |          32
payment_merchants | reference        | <none>              | 48 kB      |           1
payment_users     | distributed      | user_id             | 512 kB     |          32

    Nota

    Observe a e a shard_count diferença entre quantos fragmentos são usados para tabelas distribuídas versus tabelas de referência. Essa distinção fornece algumas informações sobre como o Citus lida com a distribuição de dados internamente. A citus_table vista também inclui informações sobre o tamanho das suas tabelas.

Examinar fragmentação de tabela

Em seguida, veja os fragmentos que o Citus criou para distribuir os dados de cada tabela:

  1. A pg_dist_shard tabela de metadados contém os detalhes dos fragmentos no cluster. Execute a seguinte consulta para visualizar os fragmentos criados para cada uma das tabelas:

    SELECT * from pg_dist_shard;

  2. Analise a saída da consulta acima. Lembre-se que a tabela existe em um único fragmento payment_merchants . Compare isso com as payment_events tabelas e payment_users , cada uma contendo 32 fragmentos.

  3. Para ver como o Citus lida com tabelas de referência de fragmentação, você pode usar a exibição para exibir a citus_shards localização dos fragmentos nos nós de trabalho. Execute a seguinte consulta:

    SELECT table_name, shardid, citus_table_type, nodename FROM citus_shards WHERE table_name = 'payment_merchants'::regclass;

    Na saída, o fragmento payment_merchants único da tabela é distribuído em todos os nós do cluster.

    table_name        | shardid | citus_table_type |                             nodename                             
------------------+---------+------------------+-----------------------------------------------------------------
payment_merchants |  102072 | reference        | private-w0.learn-cosmosdb-postgresql.postgres.database.azure.com
payment_merchants |  102072 | reference        | private-w1.learn-cosmosdb-postgresql.postgres.database.azure.com
payment_merchants |  102072 | reference        | private-c.learn-cosmosdb-postgresql.postgres.database.azure.com

  4. Para comparar, execute a seguinte consulta para exibir a distribuição de fragmentos para a payment_events tabela:

    SELECT table_name, shardid, citus_table_type, nodename FROM citus_shards WHERE table_name = 'payment_events'::regclass;

    Para distributed tabelas, cada uma aparece apenas uma vez nos resultados, e cada shardid fragmento só existe em um único nó.

    table_name     | shardid | citus_table_type |                             nodename                             
---------------+---------+------------------+-----------------------------------------------------------------
payment_events |  102040 | distributed      | private-w0.learn-cosmosdb-postgresql.postgres.database.azure.com
payment_events |  102041 | distributed      | private-w1.learn-cosmosdb-postgresql.postgres.database.azure.com
payment_events |  102042 | distributed      | private-w0.learn-cosmosdb-postgresql.postgres.database.azure.com
payment_events |  102043 | distributed      | private-w1.learn-cosmosdb-postgresql.postgres.database.azure.com
payment_events |  102044 | distributed      | private-w0.learn-cosmosdb-postgresql.postgres.database.azure.com
payment_events |  102045 | distributed      | private-w1.learn-cosmosdb-postgresql.postgres.database.azure.com
payment_events |  102046 | distributed      | private-w0.learn-cosmosdb-postgresql.postgres.database.azure.com
payment_events |  102047 | distributed      | private-w1.learn-cosmosdb-postgresql.postgres.database.azure.com
payment_events |  102048 | distributed      | private-w0.learn-cosmosdb-postgresql.postgres.database.azure.com
payment_events |  102049 | distributed      | private-w1.learn-cosmosdb-postgresql.postgres.database.azure.com
payment_events |  102050 | distributed      | private-w0.learn-cosmosdb-postgresql.postgres.database.azure.com
payment_events |  102051 | distributed      | private-w1.learn-cosmosdb-postgresql.postgres.database.azure.com
payment_events |  102052 | distributed      | private-w0.learn-cosmosdb-postgresql.postgres.database.azure.com
payment_events |  102053 | distributed      | private-w1.learn-cosmosdb-postgresql.postgres.database.azure.com
payment_events |  102054 | distributed      | private-w0.learn-cosmosdb-postgresql.postgres.database.azure.com
payment_events |  102055 | distributed      | private-w1.learn-cosmosdb-postgresql.postgres.database.azure.com
payment_events |  102056 | distributed      | private-w0.learn-cosmosdb-postgresql.postgres.database.azure.com
payment_events |  102057 | distributed      | private-w1.learn-cosmosdb-postgresql.postgres.database.azure.com
payment_events |  102058 | distributed      | private-w0.learn-cosmosdb-postgresql.postgres.database.azure.com
payment_events |  102059 | distributed      | private-w1.learn-cosmosdb-postgresql.postgres.database.azure.com
payment_events |  102060 | distributed      | private-w0.learn-cosmosdb-postgresql.postgres.database.azure.com
payment_events |  102061 | distributed      | private-w1.learn-cosmosdb-postgresql.postgres.database.azure.com
payment_events |  102062 | distributed      | private-w0.learn-cosmosdb-postgresql.postgres.database.azure.com
payment_events |  102063 | distributed      | private-w1.learn-cosmosdb-postgresql.postgres.database.azure.com
payment_events |  102064 | distributed      | private-w0.learn-cosmosdb-postgresql.postgres.database.azure.com
payment_events |  102065 | distributed      | private-w1.learn-cosmosdb-postgresql.postgres.database.azure.com
payment_events |  102066 | distributed      | private-w0.learn-cosmosdb-postgresql.postgres.database.azure.com
payment_events |  102067 | distributed      | private-w1.learn-cosmosdb-postgresql.postgres.database.azure.com
payment_events |  102068 | distributed      | private-w0.learn-cosmosdb-postgresql.postgres.database.azure.com
payment_events |  102069 | distributed      | private-w1.learn-cosmosdb-postgresql.postgres.database.azure.com
payment_events |  102070 | distributed      | private-w0.learn-cosmosdb-postgresql.postgres.database.azure.com
payment_events |  102071 | distributed      | private-w1.learn-cosmosdb-postgresql.postgres.database.azure.com

    Parabéns! Você criou com êxito um banco de dados distribuído de vários nós usando o Azure Cosmos DB para PostgreSQL. Usando tabelas e exibições de metadados, você explorou como a extensão Citus distribui dados e fornece recursos adicionais ao PostgreSQL.

  5. No Cloud Shell, execute o seguinte comando para se desconectar do banco de dados:

    \q

    Você pode manter o Cloud Shell aberto e passar para a próxima unidade.