Referência das funções do rds_tools

A extensão rds_tools fornece um conjunto de funções utilitárias para gerenciar e monitorar a instância de banco de dados do RDS para PostgreSQL. Com essas funções, é possível diagnosticar problemas de replicação, vacuum e configuração diretamente por meio de SQL, sem ferramentas de monitoramento separadas. Essas funções complementam as funções padrão do PostgreSQL. Consulte mais informações sobre as funções padrão do PostgreSQL em Functions e Operators na documentação do PostgreSQL.

Esta seção descreve as funções rds_tools disponíveis no RDS para PostgreSQL. A descrição de cada função indica a versão da extensão rds_tools a partir da qual ela ficou disponível.

Para criar a extensão, execute o seguinte comando.

postgres=> CREATE EXTENSION rds_tools;
CREATE EXTENSION

rds_tools.role_password_encryption_type

Retorna o método de criptografia de senha usado para cada perfil do banco de dados. Essa função que retorna um conjunto de linhas exclui da saída os perfis de sistema protegidos pelo RDS. Disponível a partir da versão 1.0 da extensão rds_tools.

Consulte um exemplo de uso dessa função para verificar a criptografia de senhas antes de migrar usuários do banco de dados para SCRAM em Usar criptografia de senha SCRAM para PostgreSQL.

Protótipo de função

rds_tools.role_password_encryption_type()

Argumentos

Nenhum.

Output

Exemplo de uso

=> SELECT * FROM rds_tools.role_password_encryption_type();
    rolname    | encryption_type
---------------+-----------------
 postgres      | md5
 app_user      | md5
 readonly_user | scram-sha-256
(3 rows)

rds_tools.blue_green_get_status

Verifica se comandos restritos foram executados durante as operações de implantação azul/verde. Durante implantações azul/verde que usam replicação lógica, não é possível replicar comandos de linguagem de definição de dados (DDL) nem operações com objetos grandes (LO) entre os ambientes azul e verde. Se um comando restrito for detectado, reinicie a implantação azul/verde, pois os dados não podem ser replicados corretamente para o ambiente verde. Disponível a partir da versão 1.3 da extensão rds_tools.

Protótipo de função

rds_tools.blue_green_get_status(command_type)

Argumentos

Output

Um valor boolean. Retorna true se um comando restrito do tipo especificado tiver sido executado durante a implantação ou false se nenhum comando desse tipo tiver sido detectado.

Exemplo de uso

=> SELECT rds_tools.blue_green_get_status('DDL');
 blue_green_get_status
-----------------------
 f
(1 row)

rds_tools.postgres_get_av_diag

Recupera informações de diagnóstico sobre processos de autovacuum que estão bloqueando outros processos ou apresentando atrasos, além de sugestões para resolver cada problema. Para obter resultados precisos, execute essa função que retorna um conjunto de linhas no banco de dados com o ID de transação mais antigo. Consulte mais informações em Identificar e resolver bloqueadores agressivos de vacuum.

Disponível a partir da versão 1.9 da extensão rds_tools.

Protótipo de função

rds_tools.postgres_get_av_diag()

Argumentos

Nenhum.

Output

Exemplo de uso

=> SELECT *
   FROM rds_tools.postgres_get_av_diag()
   ORDER BY autovacuum_lagging_by DESC;

blocker               | Active statement
database              | my_database
blocker_identifier    | SELECT pg_sleep(20000);
wait_event            | Timeout:PgSleep
autovacuum_lagging_by | 568600871
suggestion            | Connect to database "my_database", review carefully, and consider terminating the process using suggested_action.
suggested_action      | {"SELECT pg_terminate_backend(29621);"}

rds_tools.rds_version

Exibe a versão do mecanismo do RDS para PostgreSQL da instância de banco de dados. Essa função lê as informações de versão nos arquivos de configuração da instância. Disponível a partir da versão 1.1 da extensão rds_tools.

Protótipo de função

rds_tools.rds_version()

Argumentos

Nenhum.

Output

Uma string de caracteres que contém a versão do mecanismo.

Exemplo de uso

=> SELECT rds_tools.rds_version();
 rds_version
-------------
 18.1.R1
(1 row)

rds_tools.logical_seed_lsn

Retorna o número de sequência de log (LSN) de seed lógico que representa o ponto em que a replicação lógica diverge da instância de origem. Use essa função para gerenciar configurações de replicação lógica e entender os pontos de consistência da replicação. Disponível a partir da versão 1.2 da extensão rds_tools.

Protótipo de função

rds_tools.logical_seed_lsn()

Argumentos

Nenhum.

Output

Um valor pg_lsn.

Exemplo de uso

=> SELECT rds_tools.logical_seed_lsn();
 logical_seed_lsn
------------------
 0/1677B68
(1 row)

rds_tools.db_instance_identifier

Exibe o identificador da instância de banco de dados. Esse identificador é especificado ao criar a instância de banco de dados e é usado pelos serviços da AWS para identificar o banco de dados. Disponível a partir da versão 1.2 da extensão rds_tools.

Protótipo de função

rds_tools.db_instance_identifier()

Argumentos

Nenhum.

Output

Uma string de caracteres que contém o identificador da instância de banco de dados.

Exemplo de uso

=> SELECT rds_tools.db_instance_identifier();
 db_instance_identifier
------------------------
 my-postgres-instance
(1 row)

rds_tools.dbi_resource_id

Exibe o ID de recurso da instância de banco de dados (ID de recurso da DBI). O ID de recurso da DBI é um identificador exclusivo e imutável gerado pela AWS para a instância de banco de dados. Ele permanece constante durante todo o ciclo de vida da instância, mesmo que ela seja renomeada. Use esse valor para correlacionar a atividade do banco de dados com os logs do AWS CloudTrail ou com outros serviços de monitoramento da AWS. Esse valor corresponde ao campo DbiResourceId retornado pelo comando de API DBInstance do RDS. Disponível a partir da versão 1.4 da extensão rds_tools.

Protótipo de função

rds_tools.dbi_resource_id()

Argumentos

Nenhum.

Output

Uma string de caracteres que contém o ID de recurso da DBI.

Exemplo de uso

=> SELECT rds_tools.dbi_resource_id();
          dbi_resource_id
-----------------------------------
 db-ABC123DEF456GHI789JKL012MNO345P
(1 row)

rds_tools.multi_az_db_cluster_source_dbi_resource_id

Exibe o ID de recurso da DBI da instância de origem de uma implantação de cluster de banco de dados multi-AZ. Use essa função para entender a relação entre as instâncias em uma configuração multi-AZ e solucionar problemas de replicação ou cenários de failover. Disponível a partir da versão 1.4 da extensão rds_tools.

Protótipo de função

rds_tools.multi_az_db_cluster_source_dbi_resource_id()

Argumentos

Nenhum.

Output

Uma string de caracteres que contém o ID de recurso da DBI de origem. Retorna NULL se a instância não fizer parte de um cluster de banco de dados Multi-AZ, se o arquivo de configuração não existir ou se o campo dbi_resource_id não existir na configuração.

Exemplo de uso

=> SELECT rds_tools.multi_az_db_cluster_source_dbi_resource_id();
 multi_az_db_cluster_source_dbi_resource_id
--------------------------------------------
 db-XYZ789ABC123DEF456GHI012JKL345MNO678P
(1 row)

rds_tools.show_topology

Exibe metadados de topologia dos clusters multi-AZ do RDS, permitindo transições rápidas ao fornecer informações de conexão para todas as instâncias do cluster. Bibliotecas cliente, como o driver AWS Advanced JDBC Wrapper, usam essa função que retorna um conjunto de linhas para se conectar diretamente a todas as instâncias de um cluster multi-AZ do RDS. Para identificar o ID de recurso da instância de gravação, use essa função em conjunto com a função rds_tools.multi_az_db_cluster_source_dbi_resource_id. Disponível a partir da versão 1.4 da extensão rds_tools.

Protótipo de função

rds_tools.show_topology([client_identifier])

Argumentos

Output

Exemplo de uso

=> SELECT id, endpoint, port, role FROM rds_tools.show_topology('my-jdbc-app');
       id        |                         endpoint                          | port | role
-----------------+-----------------------------------------------------------+------+--------
 db-IDENTIFIER-1 | somedb-instance-1.aaaaaaaaaaaa.us-west-2.rds.amazonaws.com | 5432 | writer
 db-IDENTIFIER-2 | somedb-instance-2.aaaaaaaaaaaa.us-west-2.rds.amazonaws.com | 5432 | reader
 db-IDENTIFIER-3 | somedb-instance-3.aaaaaaaaaaaa.us-west-2.rds.amazonaws.com | 5432 | reader
(3 rows)

rds_tools.pg_ls_multixactdir

Lista o conteúdo do diretório pg_multixact, que armazena dados de multitransações no PostgreSQL. Use essa função que retorna um conjunto de linhas para monitorar o uso de multitransações, solucionar problemas relacionados a elas e entender os padrões de armazenamento do banco de dados. Disponível a partir da versão 1.7 da extensão rds_tools.

Protótipo de função

rds_tools.pg_ls_multixactdir()

Argumentos

Nenhum.

Output

Exemplo de uso

=> SELECT * FROM rds_tools.pg_ls_multixactdir();
           name            | size |      modification
---------------------------+------+------------------------
 pg_multixact/members/     | 4096 | 2026-10-01 19:17:29+00
 pg_multixact/members/0000 | 8192 | 2025-08-22 21:53:46+00
 pg_multixact/offsets/     | 4096 | 2026-10-01 19:17:29+00
 pg_multixact/offsets/0000 | 8192 | 2026-10-01 19:22:38+00
(4 rows)