# 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](https://www.postgresql.org/docs/current/functions.html) 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 ``` **Topics** + [rds\_tools.role\_password\_encryption\_type](#rds_tools.role_password_encryption_type) + [rds\_tools.blue\_green\_get\_status](#rds_tools.blue_green_get_status) + [rds\_tools.postgres\_get\_av\_diag](#rds_tools.postgres_get_av_diag) + [rds\_tools.rds\_version](#rds_tools.rds_version) + [rds\_tools.logical\_seed\_lsn](#rds_tools.logical_seed_lsn) + [rds\_tools.db\_instance\_identifier](#rds_tools.db_instance_identifier) + [rds\_tools.dbi\_resource\_id](#rds_tools.dbi_resource_id) + [rds\_tools.multi\_az\_db\_cluster\_source\_dbi\_resource\_id](#rds_tools.multi_az_db_cluster_source_dbi_resource_id) + [rds\_tools.show\_topology](#rds_tools.show_topology) + [rds\_tools.pg\_ls\_multixactdir](#rds_tools.pg_ls_multixactdir) ## 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](PostgreSQL_Password_Encryption_configuration.md). ### Protótipo de função ``` rds_tools.role_password_encryption_type() ``` ### Argumentos Nenhum. ### Output + `rolname`: o nome do perfil do banco de dados. + `encryption_type`: o método de criptografia de senha utilizado, como `md5` ou `scram-sha-256`. ### 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 + `command_type`: o tipo de comando restrito a ser verificado. Os valores válidos são `'DDL'` (comandos de linguagem de definição de dados) e `'LO'` (operações com objetos grandes). ### 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](Appendix.PostgreSQL.CommonDBATasks.Autovacuum_Monitoring.md). 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 + `blocker`: a categoria da atividade do banco de dados que está bloqueando o vacuum. O valor é um dos seguintes: + Instrução ativa + Ocioso na transação + Transação preparada + Slot de replicação lógica + Réplica de leitura com slot de replicação física + Réplica de leitura com replicação de streaming + Tabelas temporárias + `database`: o nome do banco de dados em que a atividade bloqueadora está ocorrendo. + `blocker_identifier`: o identificador da atividade bloqueadora. O valor depende do tipo de bloqueador: + Para uma instrução ativa ou uma sessão ociosa em uma transação, o ID do processo e a instrução SQL correspondente. + Para uma transação preparada, o nome da transação preparada. + Para uma réplica de leitura, o endereço IP da réplica. + Para um slot de replicação, o nome do slot de replicação. + `wait_event`: o evento de espera da sessão bloqueadora, quando aplicável. + `autovacuum_lagging_by`: o número de transações pelas quais o autovacuum está atrasado para a categoria. + `suggestion`: uma sugestão para resolver o bloqueio, incluindo o nome do banco de dados, o ID do processo e a ação a ser executada. + `suggested_action`: um array das ações a serem executadas para resolver o bloqueio. ### 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](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_DBInstance.html) 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 + `client_identifier` (opcional): um identificador da biblioteca cliente ou do proxy que está consultando a topologia. Esse parâmetro é opcional, mas recomendado, pois permite que o Amazon RDS monitore quais clientes estão consultando ativamente a topologia e fornece dados de telemetria para viabilizar o suporte a outros clientes. ### Output + `id`: o ID de recurso DBI de cada instância no cluster multi-AZ do RDS. + `endpoint`: o endpoint de cada nó do cluster. + `port`: o número da porta de cada instância no cluster multi-AZ do RDS. + `role`: o perfil do nó no cluster, como instância de gravação ou instância leitora. + `status`: o status do nó. + `version`: a versão do registro de topologia. ### 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 + `name`: o nome do arquivo ou diretório. + `size`: o tamanho em bytes. + `modification`: o carimbo de data/hora da última modificação. ### 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) ```