# Gerenciar planos de execução de consultas do Aurora PostgreSQL
O gerenciamento de planos de consulta do Aurora PostgreSQL é um recurso opcional que você pode usar com seu cluster de banco de dados de edição compatível com o Amazon Aurora PostgreSQL. Esse recurso é fornecido como a extensão `apg_plan_mgmt` que você pode instalar em seu cluster de banco de dados do Aurora PostgreSQL. O gerenciamento de planos de consulta permite que você gerencie os planos de execução de consultas gerados pelo otimizador para suas aplicações SQL. A extensão `apg_plan_mgmt` AWS se baseia na funcionalidade nativa de processamento de consultas do mecanismo de banco de dados do PostgreSQL.
A seguir, você encontrará informações sobre os recursos de gerenciamento de planos de consulta do Aurora PostgreSQL, como configurá-lo e como usá-lo com o cluster de banco de dados do Aurora PostgreSQL. Antes de começar, recomendamos que você revise todas as notas de lançamento da versão específica da extensão `apg_plan_mgmt` disponível para sua versão do Aurora PostgreSQL. Para obter mais informações, consulte [Aurora PostgreSQL apg\$1plan\$1mgmt extension versions](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraPostgreSQLReleaseNotes/AuroraPostgreSQL.Extensions.html#AuroraPostgreSQL.Extensions.apg_plan_mgmt) (Versões da extensão apg\$1plan\$1mgmt do Aurora PostgreSQL) nas *Release Notes for Aurora PostgreSQL* (Notas de versão do Aurora PostgreSQL).
**Topics**
+ [Visão geral do gerenciamento de planos de consulta do Aurora PostgreSQL](AuroraPostgreSQL.Optimize.overview.md)
+ [Práticas recomendadas para gerenciamento de planos de consultas do Aurora PostgreSQL](AuroraPostgreSQL.Optimize.BestPractice.md)
+ [Gerenciamento de planos de consulta do Aurora PostgreSQL](AuroraPostgreSQL.Optimize.Start.md)
+ [Capturar planos de execução do Aurora PostgreSQL](AuroraPostgreSQL.Optimize.CapturePlans.md)
+ [Usar planos gerenciados do Aurora PostgreSQL](AuroraPostgreSQL.Optimize.UsePlans.md)
+ [Examinar planos de consulta do Aurora PostgreSQL na exibição dba\$1plans](AuroraPostgreSQL.Optimize.ViewPlans.md)
+ [Melhorar os planos de consulta do Aurora PostgreSQL](AuroraPostgreSQL.Optimize.Maintenance.md)
+ [Excluir os planos de consulta do Aurora PostgreSQL](AuroraPostgreSQL.Optimize.Deleting.md)
+ [Exportar e importar planos gerenciados do Aurora PostgreSQL](AuroraPostgreSQL.Optimize.Maintenance.ExportingImporting.md)
+ [Referência de parâmetros do gerenciamento de planos de consultas do Aurora PostgreSQL](AuroraPostgreSQL.Optimize.Parameters.md)
+ [Referência de funções do gerenciamento de planos de consultas do Aurora PostgreSQL](AuroraPostgreSQL.Optimize.Functions.md)
+ [Referência da visualização apg\$1plan\$1mgmt.dba\$1plans da edição compatível do Aurora PostgreSQL](AuroraPostgreSQL.Optimize.dba_plans_view_Reference.md)
+ [Atributos avançados do gerenciamento de planos de consultas](AuroraPostgreSQL.QPM.Advanced.md)
# Visão geral do gerenciamento de planos de consulta do Aurora PostgreSQL
O gerenciamento de planos de consulta do Aurora PostgreSQL foi projetado para garantir a estabilidade do plano, independentemente das alterações no banco de dados que possam causar a regressão do plano de consulta. A *regressão do plano de consulta* ocorre quando o otimizador seleciona um plano abaixo do ideal para determinada declaração SQL após alterações no sistema ou no banco de dados. Alterações em estatísticas, restrições, configurações do ambiente, associações de parâmetros de consulta e atualizações do mecanismo de banco de dados PostgreSQL podem causar regressão do plano.
Com o gerenciamento de planos de consulta do Aurora PostgreSQL, é possível controlar como e quando planos de execução de consultas mudam. Os benefícios do gerenciamento de planos de consultas do Aurora PostgreSQL incluem o seguinte.
+ Melhorar a estabilidade do plano forçando o otimizador a escolher entre um pequeno número de planos bons e conhecidos.
+ Otimizar os planos de forma centralizada e distribuir globalmente os melhores planos.
+ Identificar índices não utilizados e avaliar o impacto da criação ou remoção de um índice.
+ Detectar automaticamente um novo plano de custo mínimo descoberto pelo otimizador.
+ Experimentar novos recursos do otimizador com menos risco, pois você pode aprovar apenas as alterações de planos que melhoram a performance.
Você pode usar as ferramentas fornecidas pelo gerenciamento de planos de consulta de forma proativa para especificar o melhor plano para determinadas consultas. Ou você pode usar o gerenciamento de planos de consulta para reagir às mudanças nas circunstâncias e evitar regressões do plano. Para obter mais informações, consulte [Práticas recomendadas para gerenciamento de planos de consultas do Aurora PostgreSQL](AuroraPostgreSQL.Optimize.BestPractice.md).
**Topics**
+ [Declarações SQL compatíveis](#AuroraPostgreSQL.Optimize.overview.features)
+ [Limitações do gerenciamento de planos de consulta](#AuroraPostgreSQL.Optimize.overview.limitations)
+ [Terminologia do gerenciamento de planos de consulta](#AuroraPostgreSQL.Optimize.Start-terminology)
+ [Versões do gerenciamento de planos de consulta do Aurora PostgreSQL](#AuroraPostgreSQL.Optimize.overview.versions)
+ [Ativar o gerenciamento de planos de consulta do Aurora PostgreSQL](#AuroraPostgreSQL.Optimize.Enable)
+ [Atualizar o gerenciamento de planos de consultas do Aurora PostgreSQL](#AuroraPostgreSQL.Optimize.Upgrade)
+ [Desativar o gerenciamento de planos de consulta do Aurora PostgreSQL](#AuroraPostgreSQL.Optimize.Enable.turnoff)
## Declarações SQL compatíveis
O gerenciamento de planos de consulta é compatível com os tipos de declaração SQL a seguir.
+ Qualquer declaração SELECT, INSERT, UPDATE ou DELETE, independentemente da complexidade.
+ Instruções preparadas. Para obter mais informações, consulte [PREPARE](https://www.postgresql.org/docs/14/sql-prepare.html) na documentação do PostgreSQL.
+ Declarações dinâmicas, como as executadas no modo imediato. Para obter mais informações, consulte [Dynamic SQL](https://www.postgresql.org/docs/current/ecpg-dynamic.html) (SQL dinâmico) e [EXECUTE IMMEDIATE](https://www.postgresql.org/docs/current/ecpg-sql-execute-immediate.html) na documentação do PostgreSQL.
+ Comandos e declarações SQL incorporados. Para obter mais informações, consulte [Embedded SQL Commands](https://www.postgresql.org/docs/current/ecpg-sql-commands.html) (Comandos SQL incorporados) na documentação do PostgreSQL.
+ Declarações dentro de funções nomeadas. Para obter mais informações, consulte [CREATE FUNCTION](https://www.postgresql.org/docs/current/sql-createfunction.html) na documentação do PostgreSQL.
+ Declarações com tabelas temporárias.
+ Declarações em procedimentos e bloqueios de DO.
Você pode usar o gerenciamento de planos de consulta com `EXPLAIN` no modo manual para capturar um plano sem realmente executá-lo. Para obter mais informações, consulte [Analisar o plano selecionado pelo otimizador](AuroraPostgreSQL.Optimize.UsePlans.md#AuroraPostgreSQL.Optimize.UsePlans.AnalyzePlans). Para saber mais sobre os modos de gerenciamento de planos de consulta (manual, automático), consulte [Capturar planos de execução do Aurora PostgreSQL](AuroraPostgreSQL.Optimize.CapturePlans.md).
O gerenciamento de planos de consulta do Aurora PostgreSQL é compatível com todos os recursos da linguagem PostgreSQL, inclusive tabelas particionadas, herança, segurança em nível de linha e Common Table Expressions (CTEs, Expressões de tabelas comuns) recursivas. Para saber mais sobre esses recursos da linguagem PostgreSQL, consulte [Table Partitioning](https://www.postgresql.org/docs/current/ddl-partitioning.html) (Particionamento de tabelas), [Row Security Policies](https://www.postgresql.org/docs/current/ddl-rowsecurity.html) (Políticas de segurança de linha) e [WITH Queries (Common Table Expressions)](https://www.postgresql.org/docs/current/queries-with.html) [Consultas WITH (expressões de tabela comuns)], bem como outros tópicos na documentação do PostgreSQL.
Para obter informações sobre diferentes versões do recurso de gerenciamento de planos de consulta do Aurora PostgreSQL, consulte [Aurora PostgreSQL apg\$1plan\$1mgmt extension versions](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraPostgreSQLReleaseNotes/AuroraPostgreSQL.Extensions.html#AuroraPostgreSQL.Extensions.apg_plan_mgmt) (Versões da extensão apg\$1plan\$1mgmt do Aurora PostgreSQL) nas *Release Notes for Aurora PostgreSQL* (Notas de versão do Aurora PostgreSQL).
## Limitações do gerenciamento de planos de consulta
A versão atual do gerenciamento de planos de consulta do Aurora PostgreSQL tem as limitações a seguir.
+ **Os planos não são capturados para declarações que fazem referência às relações do sistema**: declarações que fazem referência às relações do sistema, como `pg_class`, não são capturadas. Isso ocorre naturalmente, para evitar que um grande número de planos gerados pelo sistema que são usados internamente seja capturado. Isso também se aplica a tabelas do sistema dentro de visualizações.
+ **Pode ser necessária uma classe de instância de banco de dados maior para seu cluster de banco de dados do Aurora PostgreSQL**: dependendo da workload, o gerenciamento de planos de consulta pode precisar de uma classe de instância de banco de dados que tenha mais de duas vCPUs. O número de `max_worker_processes` é limitado pelo tamanho da classe da instância de banco de dados. O número de `max_worker_processes` fornecidos por uma classe de instância de banco de dados de duas vCPU (db.t3.medium, por exemplo) pode não ser suficiente para uma determinada workload. Recomendamos que você selecione uma classe de instância de banco de dados com mais de duas vCPUs para seu cluster de banco de dados do Aurora PostgreSQL se você usar gerenciamento de planos de consulta.
Quando a classe da instância de banco de dados não for compatível com a workload, o gerenciamento de planos de consulta gerará uma mensagem de erro como a seguinte.
```
WARNING: could not register plan insert background process
HINT: You may need to increase max_worker_processes.
```
Nesse caso, você deve aumentar a escala verticalmente de seu cluster de banco de dados do Aurora PostgreSQL para um tamanho de classe de instância de banco de dados com mais memória. Para obter mais informações, consulte [Mecanismos de banco de dados compatíveis para classes de instância de banco de dados](Concepts.DBInstanceClass.SupportAurora.md).
+ **Os planos já armazenados nas sessões não são afetados**: o gerenciamento do plano de consulta é uma forma de influenciar os planos de consulta sem alterar o código da aplicação. No entanto, quando um plano genérico já estiver armazenado em uma sessão existente e você quiser alterar o respectivo plano de consulta, primeiro defina `plan_cache_mode` como `force_custom_plan` no grupo de parâmetros do cluster de banco de dados.
+ `queryid` em `apg_plan_mgmt.dba_plans` e `pg_stat_statements` pode divergir quando:
+ Os objetos são descartados e recriados após serem armazenados em apg\$1plan\$1mgmt.dba\$1plans.
+ A tabela `apg_plan_mgmt.plans` é importada de outro cluster.
Para obter informações sobre diferentes versões do recurso de gerenciamento de planos de consulta do Aurora PostgreSQL, consulte [Aurora PostgreSQL apg\$1plan\$1mgmt extension versions](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraPostgreSQLReleaseNotes/AuroraPostgreSQL.Extensions.html#AuroraPostgreSQL.Extensions.apg_plan_mgmt) (Versões da extensão apg\$1plan\$1mgmt do Aurora PostgreSQL) nas *Release Notes for Aurora PostgreSQL* (Notas de versão do Aurora PostgreSQL).
## Terminologia do gerenciamento de planos de consulta
Os seguintes termos são utilizados neste tópico:
**declaração gerenciada**
Uma declaração SQL capturada pelo otimizador no gerenciamento de planos de consulta. Uma declaração gerenciada tem um ou mais planos de execução de consultas armazenados na visualização `apg_plan_mgmt.dba_plans`.
**linha de base do plano**
O conjunto de planos aprovados para determinada declaração gerenciada. Ou seja, todos os planos para a declaração gerenciada que têm “Aprovado” em sua coluna `status` na visualização `dba_plan`.
**histórico de planos**
O conjunto de todos os planos capturados para determinada declaração gerenciada. O histórico de planos contém todos os planos capturados para a declaração, independentemente do status.
**regressão de planos de consultas**
O caso em que o otimizador seleciona um plano abaixo do ideal do que o anterior a determinada alteração no ambiente do banco de dados, como uma nova versão do PostgreSQL ou alterações nas estatísticas.
## Versões do gerenciamento de planos de consulta do Aurora PostgreSQL
O gerenciamento de planos de consulta é compatível com todas as versões do Aurora PostgreSQL atualmente disponíveis. Para obter informações, consulte a lista de [Amazon Aurora PostgreSQL updates](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraPostgreSQLReleaseNotes/AuroraPostgreSQL.Updates.html) (Atualizações do Amazon Aurora PostgreSQL) nas *Release Notes for Aurora PostgreSQL* (Notas de versão do Aurora PostgreSQL).
A funcionalidade de gerenciamento de planos de consulta é adicionada ao seu cluster de banco de dados do Aurora PostgreSQL quando você instala a extensão `apg_plan_mgmt`. Versões diferentes do Aurora PostgreSQL são compatíveis com diferentes versões da extensão `apg_plan_mgmt`. Recomendamos que você atualize a extensão de gerenciamento de planos de consulta para a versão mais recente de sua versão do Aurora PostgreSQL.
**nota**
Para ver as notas de cada versão da extensão `apg_plan_mgmt`, consulte [Aurora PostgreSQL apg\$1plan\$1mgmt extension versions](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraPostgreSQLReleaseNotes/AuroraPostgreSQL.Extensions.html#AuroraPostgreSQL.Extensions.apg_plan_mgmt) (Versões da extensão apg\$1plan\$1mgmt do Aurora PostgreSQL) nas *Release Notes for Aurora PostgreSQL* (Notas de versão do Aurora PostgreSQL).
Você pode identificar a versão em execução em seu cluster conectando-se a uma instância com `psql` e usando o metacomando \$1dx para listar extensões, conforme mostrado a seguir.
```
labdb=> \dx
List of installed extensions
Name | Version | Schema | Description
---------------+---------+---------------+-------------------------------------------------------------------
apg_plan_mgmt | 1.0 | apg_plan_mgmt | Amazon Aurora with PostgreSQL compatibility Query Plan Management
plpgsql | 1.0 | pg_catalog | PL/pgSQL procedural language
(2 rows)
```
A saída mostra que esse cluster está usando a versão 1.0 da extensão. Somente determinadas versões de `apg_plan_mgmt` estão disponíveis para determinada versão do Aurora PostgreSQL. Em alguns casos, talvez seja necessário atualizar o cluster de banco de dados do Aurora PostgreSQL para uma nova versão secundária ou aplicar um patch para poder realizar a atualização para a versão mais recente do gerenciamento de planos de consulta. O `apg_plan_mgmt` versão 1.0 mostrado na saída é de um cluster de banco de dados do Aurora PostgreSQL versão 10.17, que não tem uma versão mais recente do `apg_plan_mgmt` disponível. Nesse caso, o cluster de banco de dados do Aurora PostgreSQL deve ser atualizado para uma versão mais recente do PostgreSQL.
Para obter mais informações sobre a atualização de um cluster de banco de dados do Aurora PostgreSQL para uma nova versão do PostgreSQL, consulte [Atualizações do mecanismo de banco de dados do Amazon Aurora PostgreSQL](AuroraPostgreSQL.Updates.md).
Para saber como atualizar a extensão `apg_plan_mgmt`, consulte [Atualizar o gerenciamento de planos de consultas do Aurora PostgreSQL](#AuroraPostgreSQL.Optimize.Upgrade).
## Ativar o gerenciamento de planos de consulta do Aurora PostgreSQL
Configurar o gerenciamento de planos de consulta para seu cluster de banco de dados do Aurora PostgreSQL envolve a instalação de uma extensão e a alteração de várias configurações de parâmetros do cluster de banco de dados. Você precisa de permissões `rds_superuser` para instalar a extensão `apg_plan_mgmt` e ativar o recurso para o cluster de banco de dados do Aurora PostgreSQL.
A instalação da extensão cria uma função, `apg_plan_mgmt`. Essa função permite que os usuários do banco de dados visualizem, gerenciem e mantenham planos de consulta. Como administrador com privilégios `rds_superuser`, não deixe de conceder a função `apg_plan_mgmt` aos usuários do banco de dados conforme necessário.
Somente os usuários com a função `rds_superuser` podem concluir o seguinte procedimento. `rds_superuser` é necessário para criar a extensão `apg_plan_mgmt` e sua função `apg_plan_mgmt`. Os usuários devem receber a função `apg_plan_mgmt` para administrar a extensão `apg_plan_mgmt`.
**Como ativar o gerenciamento de planos de consulta para o cluster de banco de dados do Aurora PostgreSQL**
As etapas a seguir ativam o gerenciamento de planos de consulta para todas as declarações SQL enviadas ao cluster de banco de dados do Aurora PostgreSQL. Isso é conhecido como modo *automático*. Para saber mais sobre a diferença entre os modos, consulte [Capturar planos de execução do Aurora PostgreSQL](AuroraPostgreSQL.Optimize.CapturePlans.md).
1. Abra o console do Amazon RDS em [https://console.aws.amazon.com/rds/](https://console.aws.amazon.com/rds/).
1. Crie um grupo de parâmetros de cluster de banco de dados personalizado para o cluster de bancos de dados do Aurora PostgreSQL. Você precisa alterar determinados parâmetros para ativar o gerenciamento de planos de consulta e definir seu comportamento. Para obter mais informações, consulte [Criar um grupo de parâmetros de banco de dados no Amazon Aurora](USER_WorkingWithParamGroups.Creating.md).
1. Abra o grupo de parâmetros de cluster de banco de dados personalizado e defina o parâmetro `rds.enable_plan_management` como `1`, como mostrado na imagem a seguir.
![\[Imagem do grupo de parâmetros de um cluster de banco de dados.\]](http://docs.aws.amazon.com/pt_br/AmazonRDS/latest/AuroraUserGuide/images/aurora-qpm-custom-db-cluster-param-change-1.png)
Para obter mais informações, consulte [Modificar parâmetros em um grupo de parâmetros de cluster de banco de dadosno Amazon Aurora](USER_WorkingWithParamGroups.ModifyingCluster.md).
1. Crie um grupo de parâmetros de banco de dados personalizado que você possa usar para definir os parâmetros do plano de consulta em nível de instância. Para obter mais informações, consulte [Criar um grupo de parâmetros de cluster de banco de dadosno Amazon Aurora](USER_WorkingWithParamGroups.CreatingCluster.md).
1. Modifique a instância do gravador do cluster de banco de dados do Aurora PostgreSQL para usar o grupo de parâmetros de banco de dados personalizado. Para obter mais informações, consulte [Modificar uma instância de banco de dados em um cluster de banco de dados](Aurora.Modifying.md#Aurora.Modifying.Instance).
1. Modifique o cluster de banco de dados do Aurora PostgreSQL para usar o grupo de parâmetros de cluster de banco de dados personalizado. Para obter mais informações, consulte [Modificar o cluster de banco de dados usando o console, a CLI e a API](Aurora.Modifying.md#Aurora.Modifying.Cluster).
1. Reinicialize a instância de banco de dados para habilitar as configurações do grupo de parâmetros personalizado.
1. Conecte-se ao endpoint da instância de banco de dados de seu cluster de banco de dados do Aurora PostgreSQL usando `psql` ou `pgAdmin`. O exemplo a seguir usa a conta `postgres` padrão para a função `rds_superuser`.
```
psql --host=cluster-instance-1.111122223333.aws-region.rds.amazonaws.com --port=5432 --username=postgres --password --dbname=my-db
```
1. Crie a extensão `apg_plan_mgmt` para a instância de banco de dados, conforme mostrado a seguir.
```
labdb=> CREATE EXTENSION apg_plan_mgmt;
CREATE EXTENSION
```
**dica**
Instale a extensão `apg_plan_mgmt` no banco de dados de modelo de sua aplicação. O banco de dados de modelo padrão é chamado de `template1`. Para saber mais, consulte [Template Databases](https://www.postgresql.org/docs/current/manage-ag-templatedbs.html) (Bancos de dados de modelos) na documentação do PostgreSQL.
1. Altere o parâmetro `apg_plan_mgmt.capture_plan_baselines` para `automatic`. Essa configuração faz com que o otimizador gere planos para cada declaração SQL planejada ou executada duas ou mais vezes.
**nota**
O gerenciamento de planos de consulta também tem um modo *manual* que você pode usar para declarações SQL específicas. Para saber mais, consulte [Capturar planos de execução do Aurora PostgreSQL](AuroraPostgreSQL.Optimize.CapturePlans.md).
1. Altere o valor do parâmetro `apg_plan_mgmt.use_plan_baselines` para “on” (ativado). Esse parâmetro faz com que o otimizador selecione um plano para a declaração na linha de base do plano. Para saber mais, consulte [Usar planos gerenciados do Aurora PostgreSQL](AuroraPostgreSQL.Optimize.UsePlans.md).
**nota**
Você pode modificar o valor de qualquer um desses parâmetros dinâmicos para a sessão sem precisar reinicializar a instância.
Quando a configuração do gerenciamento de planos de consulta estiver concluída, conceda a função `apg_plan_mgmt` a todos os usuários do banco de dados que precisem visualizar, gerenciar ou manter planos de consulta.
## Atualizar o gerenciamento de planos de consultas do Aurora PostgreSQL
Recomendamos que você atualize a extensão de gerenciamento de planos de consulta para a versão mais recente de sua versão do Aurora PostgreSQL.
1. Conecte-se à instância do gravador de seu cluster de banco de dados do Aurora PostgreSQL como um usuário com privilégios `rds_superuser`. Se você manteve o nome padrão ao configurar a instância, se conectará como `postgres` Este exemplo mostra como usar `psql`, mas você também pode usar pgAdmin, se preferir.
```
psql --host=111122223333.aws-region.rds.amazonaws.com --port=5432 --username=postgres --password
```
1. Execute a consulta a seguir para atualizar a extensão.
```
ALTER EXTENSION apg_plan_mgmt UPDATE TO '2.1';
```
1. Use a função [apg\$1plan\$1mgmt.validate\$1plans](AuroraPostgreSQL.Optimize.Functions.md#AuroraPostgreSQL.Optimize.Functions.validate_plans) para atualizar os hashes de todos os planos. O otimizador valida todos os planos Aprovados, Não aprovados e Rejeitados para garantir que eles ainda sejam planos viáveis para a nova versão da extensão.
```
SELECT apg_plan_mgmt.validate_plans('update_plan_hash');
```
Para saber mais sobre o uso dessa função, consulte [Validar planos](AuroraPostgreSQL.Optimize.Deleting.md#AuroraPostgreSQL.Optimize.Maintenance.ValidatingPlans).
1. Use a função [apg\$1plan\$1mgmt.reload](AuroraPostgreSQL.Optimize.Functions.md#AuroraPostgreSQL.Optimize.Functions.reload) para atualizar todos os planos na memória compartilhada com os planos validados na visualização dba\$1plans.
```
SELECT apg_plan_mgmt.reload();
```
Para saber mais sobre todas as funções disponíveis para o gerenciamento de planos de consulta, consulte [Referência de funções do gerenciamento de planos de consultas do Aurora PostgreSQL](AuroraPostgreSQL.Optimize.Functions.md).
## Desativar o gerenciamento de planos de consulta do Aurora PostgreSQL
Você pode desativar o gerenciamento de planos de consulta a qualquer momento, desativando as `apg_plan_mgmt.use_plan_baselines` e as `apg_plan_mgmt.capture_plan_baselines`.
```
labdb=> SET apg_plan_mgmt.use_plan_baselines = off;
labdb=> SET apg_plan_mgmt.capture_plan_baselines = off;
```
# Práticas recomendadas para gerenciamento de planos de consultas do Aurora PostgreSQL
Com o gerenciamento de planos de consultas, você pode controlar como e quando os planos de execução de consultas mudam. Como DBA, suas principais metas ao usar o QPM incluem evitar regressões quando há alterações no banco de dados e controlar se o otimizador pode ou não usar um novo plano. A seguir, você pode encontrar algumas práticas recomendadas para o uso do gerenciamento de planos de consultas. As abordagens de gerenciamento de planos proativo e reativo diferem em relação a como e quando novos planos são aprovados para uso.
**Contents**
+ [Gerenciamento de planos proativo para ajudar a evitar a regressão de performance](#AuroraPostgreSQL.Optimize.BestPractice.Proactive)
+ [Garantir a estabilidade do plano após a atualização da versão principal](#AuroraPostgreSQL.Optimize.BestPractice.MajorVersionUpgrade)
+ [Gerenciamento de planos reativo para detectar e reparar regressões de performance](#AuroraPostgreSQL.Optimize.BestPractice.Reactive)
## Gerenciamento de planos proativo para ajudar a evitar a regressão de performance
Para evitar que ocorram regressões de performance do plano, você *evolui* as linhas de base do plano executando um procedimento que compara a performance dos planos recém-descobertos com a performance da linha de base existente dos planos aprovados e, depois, aprova automaticamente o conjunto mais rápido de planos como a nova linha de base. Dessa forma, a linha de base dos planos melhora com o tempo, à medida que planos mais rápidos são descobertos.
1. Em um ambiente de desenvolvimento, identifique as instruções SQL que tenham o maior impacto sobre a performance ou a produtividade do sistema. Em seguida, capture os planos dessas instruções conforme descrito em [Capturar manualmente planos para instruções SQL específicas](AuroraPostgreSQL.Optimize.CapturePlans.md#AuroraPostgreSQL.Optimize.CapturePlans.Manual) e [Capturar planos automaticamente](AuroraPostgreSQL.Optimize.CapturePlans.md#AuroraPostgreSQL.Optimize.CapturePlans.Automatic).
1. Exporte os planos capturados do ambiente de desenvolvimento e os importe para o ambiente de produção. Para obter mais informações, consulte [Exportar e importar planos gerenciados do Aurora PostgreSQL](AuroraPostgreSQL.Optimize.Maintenance.ExportingImporting.md).
1. Na produção, execute o aplicativo e imponha o uso de planos gerenciados aprovados. Para obter mais informações, consulte [Usar planos gerenciados do Aurora PostgreSQL](AuroraPostgreSQL.Optimize.UsePlans.md). Enquanto o aplicativo estiver em execução, adicione também novos planos enquanto o otimizador os descobre. Para obter mais informações, consulte [Capturar planos automaticamente](AuroraPostgreSQL.Optimize.CapturePlans.md#AuroraPostgreSQL.Optimize.CapturePlans.Automatic).
1. Analise os planos não aprovados e confirme os que apresentam boa performance. Para obter mais informações, consulte [Avaliar performance do plano](AuroraPostgreSQL.Optimize.Maintenance.md#AuroraPostgreSQL.Optimize.Maintenance.EvaluatingPerformance).
1. Enquanto o aplicativo continua sendo executado, o otimizador começa a usar os novos planos conforme apropriado.
### Garantir a estabilidade do plano após a atualização da versão principal
Toda versão principal do PostgreSQL inclui melhorias e alterações no otimizador de consulta projetadas para melhorar a performance. No entanto, os planos de execução de consultas gerados pelo otimizador em versões anteriores podem causar regressões de performance em versões atualizadas mais recentes. Você pode usar o gerenciador de planos de consulta para resolver esses problemas de performance e garantir a estabilidade do plano após a atualização da versão principal.
O otimizador sempre usa o plano aprovado de custo mínimo, mesmo que haja mais de um plano aprovado para a mesma instrução. Depois de uma atualização, o otimizador pode descobrir novos planos, mas eles serão salvos como planos não aprovados. Esses planos serão executados somente se aprovados usando o estilo reativo de gerenciamento do plano com o parâmetro unapproved\$1plan\$1execution\$1threshold. Você pode maximizar a estabilidade do plano usando o estilo proativo de gerenciamento do plano com o parâmetro evolve\$1plan\$1baselines. Isso compara a performance dos novos planos com os planos antigos e aprova ou rejeita planos que são pelo menos 10% mais rápidos do que o próximo melhor plano.
Após a atualização, você pode usar a função `evolve_plan_baselines` para comparar a performance do plano antes e depois da atualização usando suas associações de parâmetros de consulta. As etapas a seguir pressupõem que você tenha usado planos gerenciados aprovados em seu ambiente de produção, conforme detalhado em [Usar planos gerenciados do Aurora PostgreSQL](AuroraPostgreSQL.Optimize.UsePlans.md).
1. Antes de atualizar, execute sua aplicação com o gerenciador de planos de consulta em execução. Enquanto a aplicação estiver em execução, adicione novos planos à medida que o otimizador os descobrir. Para obter mais informações, consulte [Capturar planos automaticamente](AuroraPostgreSQL.Optimize.CapturePlans.md#AuroraPostgreSQL.Optimize.CapturePlans.Automatic).
1. Avalie a performance de cada plano. Para obter mais informações, consulte [Avaliar performance do plano](AuroraPostgreSQL.Optimize.Maintenance.md#AuroraPostgreSQL.Optimize.Maintenance.EvaluatingPerformance).
1. Após a atualização, analise seus planos aprovados novamente usando a função `evolve_plan_baselines`. Compare a performance antes e depois de usar as associações de parâmetros de consulta. Se o novo plano for rápido, você poderá adicioná-lo aos planos aprovados. Se for mais rápido do que outro plano para as mesmas associações de parâmetros, você poderá marcar o plano mais lento como Rejected (Rejeitado).
Para obter mais informações, consulte [Aprovar planos melhores](AuroraPostgreSQL.Optimize.Maintenance.md#AuroraPostgreSQL.Optimize.Maintenance.EvaluatingPerformance.Approving). Para obter informações de referência sobre essa função, consulte [apg\$1plan\$1mgmt.evolve\$1plan\$1baselines](AuroraPostgreSQL.Optimize.Functions.md#AuroraPostgreSQL.Optimize.Functions.evolve_plan_baselines).
Para obter mais informações, consulte [Garantir uma performance consistente após atualizações de versões principais com o gerenciamento de planos de consultas do Amazon Aurora edição compatível com PostgreSQL](https://aws.amazon.com/blogs/database/ensuring-consistent-performance-after-major-version-upgrades-with-amazon-aurora-postgresql-query-plan-management/).
**nota**
Ao realizar uma atualização de versão principal usando a replicação lógica ou AWS DMS, replique o esquema `apg_plan_mgmt` para garantir que os planos existentes sejam copiados na instância atualizada. Para obter mais informações sobre replicação lógica, consulte [Usar replicação lógica para realizar uma atualização de versão principal do Aurora PostgreSQL](AuroraPostgreSQL.MajorVersionUpgrade.md).
## Gerenciamento de planos reativo para detectar e reparar regressões de performance
Ao monitorar a aplicação enquanto ela é executada, é possível detectar planos que causam regressões de performance. Ao detectar regressões, rejeite ou corrija manualmente os planos inadequados seguindo estas etapas:
1. Enquanto o aplicativo estiver em execução, imponha o uso de planos gerenciados e adicione automaticamente planos recém-descobertos como não aprovados. Para obter mais informações, consulte [Usar planos gerenciados do Aurora PostgreSQL](AuroraPostgreSQL.Optimize.UsePlans.md) e [Capturar planos automaticamente](AuroraPostgreSQL.Optimize.CapturePlans.md#AuroraPostgreSQL.Optimize.CapturePlans.Automatic).
1. Monitore o aplicativo em execução em busca de regressões de performance.
1. Ao descobrir uma regressão de plano, defina o status do plano como `rejected`. Na próxima vez em que executar a instrução SQL, o otimizador vai ignorar automaticamente o plano rejeitado e usar um plano aprovado diferente. Para obter mais informações, consulte [Rejeitar ou desabilitar planos mais lentos](AuroraPostgreSQL.Optimize.Maintenance.md#AuroraPostgreSQL.Optimize.Maintenance.EvaluatingPerformance.Rejecting).
Em alguns casos, convém corrigir um plano inválido, em vez de rejeitar, desabilitar ou excluí-lo. Use a extensão `pg_hint_plan` para testar melhorando um plano. Com `pg_hint_plan`, você usa comentários especiais para informar o otimizador como ele normalmente cria um plano. Para obter mais informações, consulte [Corrigir planos usando pg\$1hint\$1plan](AuroraPostgreSQL.Optimize.Maintenance.md#AuroraPostgreSQL.Optimize.Maintenance.pg_hint_plan).
# Gerenciamento de planos de consulta do Aurora PostgreSQL
Com o gerenciamento de planos de consulta ativado para seu cluster de banco de dados do Aurora PostgreSQL, o otimizador gera e armazena planos de execução de consultas para qualquer declaração SQL processada mais de uma vez. O otimizador sempre define o status do primeiro plano gerado de uma declaração gerenciada como `Approved` e o armazena na visualização `dba_plans`.
O conjunto de planos aprovados salvos para uma declaração gerenciada é conhecido como *linha de base de planos*. Enquanto a aplicação é executada, o otimizador pode gerar planos adicionais para as declarações gerenciadas. O otimizador define planos capturados adicionais para um status de `Unapproved`.
Posteriormente, será possível decidir se os planos `Unapproved` apresentam boa performance e alterá-los para `Approved`, `Rejected` ou `Preferred`. Para fazer isso, você usa a função `apg_plan_mgmt.evolve_plan_baselines` ou `apg_plan_mgmt.set_plan_status`.
Quando o otimizador gera um plano para uma instrução SQL, o gerenciamento de planos de consulta salva o plano na tabela `apg_plan_mgmt.plans`. Os usuários do banco de dados que receberam a função `apg_plan_mgmt` podem ver os detalhes do plano consultando a visualização `apg_plan_mgmt.dba_plans`. Por exemplo, a consulta a seguir lista os detalhes dos planos atualmente na visualização de um cluster de banco de dados do Aurora PostgreSQL que não esteja em produção.
+ `sql_hash`: um identificador da instrução SQL que é o valor de hash para o texto normalizado da instrução SQL.
+ `plan_hash`: um identificador exclusivo para o plano que é uma combinação do `sql_hash` e um hash do plano.
+ `status` – O status do plano. O otimizador pode executar um plano aprovado.
+ `enabled`: indica se o plano está pronto para uso (verdadeiro) ou não (falso).
+ `plan_outline`: uma representação do plano utilizada para recriar o plano de execução real. Os operadores na estrutura em árvore são mapeados para operadores na saída EXPLAIN.
A visualização `apg_plan_mgmt.dba_plans` tem muitas outras colunas que contêm todos os detalhes do plano, como quando ele foi utilizado pela última vez. Para obter detalhes completos, consulte [Referência da visualização apg\$1plan\$1mgmt.dba\$1plans da edição compatível do Aurora PostgreSQL](AuroraPostgreSQL.Optimize.dba_plans_view_Reference.md).
## Normalização e o hash SQL
Na visualização `apg_plan_mgmt.dba_plans`, identifique uma declaração gerenciada com um valor de hash SQL. O hash SQL é calculado com base em uma representação normalizada da declaração SQL que remove algumas diferenças, como os valores literais.
O processo de *normalização* de cada declaração SQL preserva espaço e maiúsculas e minúsculas, para que você ainda possa ler e entender a essência da declaração SQL. A normalização remove ou substitui os itens a seguir.
+ Principais comentários do bloco
+ A palavra-chave EXPLAIN e as opções EXPLAIN e EXPLAIN ANALYZE
+ Espaços à direita
+ Todos os literais
Por exemplo, utilize a declaração a seguir.
```
/*Leading comment*/ EXPLAIN SELECT /* Query 1 */ * FROM t WHERE x > 7 AND y = 1;
```
O gerenciamento de planos de consulta normaliza essa declaração da seguinte maneira:
```
SELECT /* Query 1 */ * FROM t WHERE x > CONST AND y = CONST;
```
A normalização permite que o mesmo hash SQL seja utilizado para declarações SQL semelhantes que só podem ter diferenças nos valores literais ou de parâmetro. Em outras palavras, podem existir vários planos para o mesmo hash SQL, com um plano diferente que é ideal em condições diferentes.
**nota**
Uma única declaração SQL utilizada com esquemas diferentes tem planos diferentes porque está vinculada ao esquema específico em tempo de execução. O planejador usa as estatísticas para vinculação do esquema para selecionar o plano ideal.
Para saber mais sobre como o otimizador seleciona um plano, consulte [Usar planos gerenciados do Aurora PostgreSQL](AuroraPostgreSQL.Optimize.UsePlans.md). Nessa seção, você pode aprender a usar `EXPLAIN` e `EXPLAIN ANALYZE` e visualizar um plano antes que ele seja realmente utilizado. Para obter detalhes, consulte [Analisar o plano selecionado pelo otimizador](AuroraPostgreSQL.Optimize.UsePlans.md#AuroraPostgreSQL.Optimize.UsePlans.AnalyzePlans). Para obter uma imagem que descreve o processo de seleção de um plano, consulte [Como o otimizador escolhe que plano executar.](AuroraPostgreSQL.Optimize.UsePlans.md#AuroraPostgreSQL.Optimize.UsePlans.ChoosePlans).
# Capturar planos de execução do Aurora PostgreSQL
O gerenciamento de planos de consulta do Aurora PostgreSQL oferece dois modos diferentes para capturar planos de execução de consultas: automático ou manual. Você seleciona o modo definindo o valor de `apg_plan_mgmt.capture_plans_baselines` como `automatic` ou `manual`. Você pode capturar planos de execução para instruções SQL específicas usando a captura de plano manual. Como alternativa, você pode capturar todos (ou os mais lentos) os planos executados duas ou mais vezes durante as execuções do aplicativo usando a captura de plano automática.
Ao capturar planos, o otimizador define o status do primeiro plano capturado de uma instrução gerenciada como `approved`. O otimizador define o status de todos os planos adicionais capturados para uma instrução gerenciada como `unapproved`. No entanto, mais de um plano pode, ocasionalmente, ser salvo com o status de `approved`. Isso pode ocorrer quando vários planos são criados para uma instrução em paralelo e antes da confirmação do primeiro plano da instrução.
Para controlar o número máximo de planos que podem ser capturados e armazenados na visualização `dba_plans`, defina o parâmetro `apg_plan_mgmt.max_plans` no grupo de parâmetros no nível de instância de banco de dados. Uma alteração feita no parâmetro `apg_plan_mgmt.max_plans` exige a reinicialização de uma instância de banco de dados para que um novo valor entre em vigor. Para obter mais informações, consulte o parâmetro [apg\$1plan\$1mgmt.max\$1plans](AuroraPostgreSQL.Optimize.Parameters.md#AuroraPostgreSQL.Optimize.Parameters.max_plans).
## Capturar manualmente planos para instruções SQL específicas
Caso você tenha um conjunto conhecido de instruções SQL a serem gerenciadas, coloque as instruções em um arquivo SQL e capture manualmente os planos. A seguir, um exemplo de psql de como capturar planos de consulta manualmente para um conjunto de instruções SQL.
```
psql> SET apg_plan_mgmt.capture_plan_baselines = manual;
psql> \i my-statements.sql
psql> SET apg_plan_mgmt.capture_plan_baselines = off;
```
Depois de capturar um plano para cada instrução SQL, o otimizador adicionará uma nova linha à visualização `apg_plan_mgmt.dba_plans`.
Recomendamos usar instruções EXPLAIN ou EXPLAIN EXECUTE no arquivo script do SQL. Garanta a inclusão de variações suficientes em valores de parâmetros para capturar todos os planos de interesse.
Se você conhecer um plano melhor do que o plano de custo mínimo do otimizador, poderá forçar o otimizador a usar o plano melhor. Para isso, especifique uma ou mais dicas do otimizador. Para obter mais informações, consulte [Corrigir planos usando pg\$1hint\$1plan](AuroraPostgreSQL.Optimize.Maintenance.md#AuroraPostgreSQL.Optimize.Maintenance.pg_hint_plan). Para comparar a performance dos planos `unapproved` e `approved` e aprovar, rejeitar ou excluí-los, consulte [Avaliar performance do plano](AuroraPostgreSQL.Optimize.Maintenance.md#AuroraPostgreSQL.Optimize.Maintenance.EvaluatingPerformance).
## Capturar planos automaticamente
Use a captura de planos automática em situações como a seguinte:
+ Você não sabe as instruções SQL específicas que deseja gerenciar.
+ Você tem centenas ou milhares de instruções SQL a serem gerenciadas.
+ O aplicativo usa uma API cliente. Por exemplo, o JDBC usa instruções preparadas não nomeadas ou instruções de modo em lote que não podem ser expressadas em psql.
**Para capturar planos automaticamente**
1. Ative a captura de planos automática definindo `apg_plan_mgmt.capture_plan_baselines` como `automatic` no grupo de parâmetros no nível da instância de banco de dados. Para obter mais informações, consulte [Modificar parâmetros em um grupo de parâmetros de banco de dados no Amazon Aurora](USER_WorkingWithParamGroups.Modifying.md).
1. Quando o aplicativo é executado, o otimizador captura planos de todas as instruções SQL executadas pelo menos duas vezes.
Quando o aplicativo é executado com as configurações do parâmetro de gerenciamento de planos de consultas padrão, o otimizador captura planos de todas as instruções SQL executadas pelo menos duas vezes. Capturar todos os planos usando os padrões tem pouquíssimos custos indiretos no tempo de execução e pode ser habilitado na produção.
**Para desativar a captura de planos automática**
+ Defina o parâmetro `apg_plan_mgmt.capture_plan_baselines` como `off` do grupo de parâmetros no nível de instância de banco de dados.
Para avaliar a performance dos planos não aprovados e aprovar, rejeitar ou excluí-los, consulte [Avaliar performance do plano](AuroraPostgreSQL.Optimize.Maintenance.md#AuroraPostgreSQL.Optimize.Maintenance.EvaluatingPerformance).
# Usar planos gerenciados do Aurora PostgreSQL
Para fazer o otimizador usar planos capturados para as instruções gerenciadas, defina o parâmetro `apg_plan_mgmt.use_plan_baselines` como `true`. Veja uma instância local de exemplo.
```
SET apg_plan_mgmt.use_plan_baselines = true;
```
Enquanto a aplicação estiver em execução, essa configuração fará com que o otimizador use o plano de custo mínimo, preferido ou aprovado que seja válido e esteja habilitado em cada declaração gerenciada.
## Analisar o plano selecionado pelo otimizador
Quando o parâmetro `apg_plan_mgmt.use_plan_baselines` é definido como `true`, use instruções EXPLAIN ANALYZE SQL para fazer o otimizador mostrar o plano que ele usaria se fosse executar a instrução. Veja um exemplo a seguir.
```
EXPLAIN ANALYZE EXECUTE rangeQuery (1,10000);
```
```
QUERY PLAN
--------------------------------------------------------------------------
Aggregate (cost=393.29..393.30 rows=1 width=8) (actual time=7.251..7.251 rows=1 loops=1)
-> Index Only Scan using t1_pkey on t1 t (cost=0.29..368.29 rows=10000 width=0) (actual time=0.061..4.859 rows=10000 loops=1)
Index Cond: ((id >= 1) AND (id <= 10000))
Heap Fetches: 10000
Planning time: 1.408 ms
Execution time: 7.291 ms
Note: An Approved plan was used instead of the minimum cost plan.
SQL Hash: 1984047223, Plan Hash: 512153379
```
O resultado mostra o plano aprovado que seria executado a partir da linha de base. No entanto, o resultado também mostra que ele encontrou um plano de custo mais baixo. Neste caso, você captura esse novo plano de custo mínimo ativando a captura de planos automáticos conforme descrito em [Capturar planos automaticamente](AuroraPostgreSQL.Optimize.CapturePlans.md#AuroraPostgreSQL.Optimize.CapturePlans.Automatic).
Novos planos são sempre capturados pelo otimizador como `Unapproved`. Use a função `apg_plan_mgmt.evolve_plan_baselines` para comparar planos e alterá-los para aprovados, rejeitados ou desabilitados. Para obter mais informações, consulte [Avaliar performance do plano](AuroraPostgreSQL.Optimize.Maintenance.md#AuroraPostgreSQL.Optimize.Maintenance.EvaluatingPerformance).
## Como o otimizador escolhe que plano executar.
O custo de um plano de execução é uma estimativa feita pelo otimizador para comparar planos diferentes. Ao calcular o custo de um plano, o otimizador inclui fatores como operações de CPU e E/S exigidas por esse plano. Para saber mais sobre as estimativas de custo do planejador de consultas PostgreSQL, consulte [Planejamento de consultas](https://www.postgresql.org/docs/current/runtime-config-query.html) na documentação do PostgreSQL.
A imagem a seguir mostra como um plano é selecionado para determinada declaração SQL quando o gerenciamento de planos de consulta está ativo e quando não está.
![\[Fluxo de trabalho do gerenciamento de planos de consultas do Aurora PostgreSQL\]](http://docs.aws.amazon.com/pt_br/AmazonRDS/latest/AuroraUserGuide/images/aurora-query-plan-mgmt_processing-flow.png)
O fluxo é o seguinte:
1. O otimizador gera um plano de custo mínimo para a instrução SQL.
1. Se o gerenciamento do plano de consulta não estiver ativo, o plano do otimizador será executado imediatamente (A. Executar o plano do otimizador). O gerenciamento de planos de consultas está inativo quando os parâmetros `apg_plan_mgmt.capture_plan_baselines` e `apg_plan_mgmt.use_plan_baselines` estão em suas configurações padrão (“off” e “false”, respectivamente).
Caso contrário, o gerenciamento de planos de consultas estará ativo. Nesse caso, a instrução SQL e o plano do otimizador para ela são avaliados em mais detalhes antes que um plano seja escolhido.
**dica**
Usuários do banco de dados com o perfil `apg_plan_mgmt` podem comparar planos de maneira proativa, alterar o status dos planos e forçar o uso de planos específicos, conforme necessário. Para obter mais informações, consulte [Melhorar os planos de consulta do Aurora PostgreSQL](AuroraPostgreSQL.Optimize.Maintenance.md).
1. A instrução SQL pode já ter planos que foram armazenados pelo gerenciamento de planos de consultas no passado. Os planos são armazenados em `apg_plan_mgmt.dba_plans`, junto com informações sobre as instruções SQL que foram usadas para criá-los. As informações sobre um plano incluem seu status. O status de um plano pode determinar se ele é usado ou não, conforme mostrado a seguir.
1. Se o plano não estiver entre os planos armazenados para a instrução SQL, significa que é a primeira vez que esse plano específico foi gerado pelo otimizador para a instrução SQL fornecida. O plano é enviado para o processamento de captura de plano (4).
1. Se o plano estiver entre os planos armazenados e seu status for Aprovado ou Preferencial, o plano será executado (A. Executar o plano do otimizador).
Se o plano estiver entre os planos armazenados, mas não for Aprovado nem Preferencial, o plano será enviado para o processamento de captura de plano (4).
1. Quando um plano é capturado pela primeira vez para determinada instrução SQL, o status do plano é sempre definido como Aprovado (P1). Se o otimizador gerar posteriormente o mesmo plano para a mesma instrução SQL, o status desse plano será alterado para Não aprovado (P1\$1n).
Com o plano capturado e seu status atualizado, a avaliação continua na próxima etapa (5).
1. A *linha de base* de um plano consiste no histórico da instrução SQL e em seus planos em vários estados. O gerenciamento de planos de consultas pode levar em consideração a linha de base ao escolher um plano, dependendo se a opção de usar linhas de base do plano está ativada ou não, conforme mostrado a seguir.
+ A opção de usar linhas de base do plano está “off” quando o parâmetro `apg_plan_mgmt.use_plan_baselines` está definido com o valor padrão (`false`). O plano não é comparado com a linha de base antes de ser executado (A. Executar plano do otimizador).
+ A opção de usar linhas de base do plano está “on” quando o parâmetro `apg_plan_mgmt.use_plan_baselines` está definido como `true`. O plano é avaliado em mais detalhes usando a linha de base (6).
1. O plano é comparado a outros planos para a instrução na linha de base.
1. Se o plano do otimizador estiver entre os planos na linha de base, seu status será verificado (7a).
1. Se o plano do otimizador não estiver entre os planos na linha de base, o plano será adicionado aos planos da instrução como um novo plano `Unapproved`.
1. O status do plano é verificado somente para determinar se ele é Não aprovado.
1. Se o status do plano for Não aprovado, o custo estimado do plano será comparado com a estimativa de custo especificada para o limite do plano de execução não aprovado.
+ Se o custo estimado do plano estiver abaixo do limite, o otimizador o usará mesmo sendo um plano Não aprovado (A. Executar o plano do otimizador). Geralmente, o otimizador não executa um plano Não aprovado. No entanto, quando o parâmetro `apg_plan_mgmt.unapproved_plan_execution_threshold` especifica um valor de limite de custo, o otimizador compara o custo do plano Não aprovado com o limite. Se o custo estimado for menor que o limite, o otimizador executará o plano. Para obter mais informações, consulte [apg\$1plan\$1mgmt.unapproved\$1plan\$1execution\$1threshold](AuroraPostgreSQL.Optimize.Parameters.md#AuroraPostgreSQL.Optimize.Parameters.unapproved_plan_execution_threshold).
+ Se o custo estimado do plano não estiver abaixo do limite, os outros atributos do plano serão verificados (8a).
1. Se o status do plano for diferente de Não aprovado, seus outros atributos serão verificados (8a).
1. O otimizador não usará um plano desativado. Ou seja, um plano com o atributo `enable` definido como “f” (false). O otimizador também não usará um plano com status Rejeitado.
O otimizador não pode usar nenhum plano que não seja válido. Os planos podem se tornar inválidos ao longo do tempo quando os objetos dos quais dependem, como índices e partições de tabelas, são removidos ou excluídos.
1. Se a instrução tiver planos habilitados e válidos com status Preferencial, o otimizador escolherá o plano de custo mínimo dentre os planos com status Preferencial armazenados para essa instrução SQL. Depois, o otimizador executa o plano Preferencial de custo mínimo.
1. Se a instrução não tiver nenhum plano Preferencial habilitado e válido, será avaliada na próxima etapa (9).
1. Se a instrução tiver planos habilitados e válidos com status Aprovado, o otimizador escolherá o plano de custo mínimo dentre os planos com status Aprovado armazenados para essa instrução SQL. Depois, o otimizador executa o plano Aprovado de custo mínimo.
Se a instrução não tiver nenhum plano Aprovado habilitado e válido, o otimizador usará o plano de custo mínimo (A. Executar o plano do otimizador).
# Examinar planos de consulta do Aurora PostgreSQL na exibição dba\$1plans
Os usuários e os administradores do banco de dados que receberam a função `apg_plan_mgmt` podem visualizar e gerenciar os planos armazenados em `apg_plan_mgmt.dba_plans`. O administrador de um cluster de banco de dados do Aurora PostgreSQL (alguém com permissões `rds_superuser`) deve conceder explicitamente essa função aos usuários do banco de dados que precisam trabalhar com o gerenciamento de planos de consulta.
A visualização `apg_plan_mgmt` contém o histórico dos planos de todas as declarações SQL gerenciadas para cada banco de dados na instância do gravador do cluster de banco de dados do Aurora PostgreSQL. Essa visualização permite examinar os planos, seu estado, quando foram utilizados pela última vez e todos os outros detalhes relevantes.
Conforme discutido em [Normalização e o hash SQL](AuroraPostgreSQL.Optimize.Start.md#AuroraPostgreSQL.Optimize.Start.hash-and-normalization), cada plano gerenciado é identificado pela combinação de um valor de hash SQL e de um valor de hash do plano. Com esses identificadores, use ferramentas como o Amazon RDS Performance Insights para rastrear a performance do plano individual. Para obter mais informações sobre o Performance Insights, consulte [Usar o Amazon RDS Performance Insights]( https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_PerfInsights.html).
## Listar planos gerenciados
Para listar os planos gerenciados, use uma instrução SELECT na visualização `apg_plan_mgmt.dba_plans`. O exemplo a seguir exibe algumas colunas na visualização `dba_plans`, como o `status`, que identifica os planos aprovados e não aprovados.
```
SELECT sql_hash, plan_hash, status, enabled, stmt_name
FROM apg_plan_mgmt.dba_plans;
sql_hash | plan_hash | status | enabled | stmt_name
------------+-----------+------------+---------+------------
1984047223 | 512153379 | Approved | t | rangequery
1984047223 | 512284451 | Unapproved | t | rangequery
(2 rows)
```
Para facilitar a leitura, a consulta e a saída mostradas listam apenas algumas das colunas da visualização `dba_plans`. Para obter informações completas, consulte [Referência da visualização apg\$1plan\$1mgmt.dba\$1plans da edição compatível do Aurora PostgreSQL](AuroraPostgreSQL.Optimize.dba_plans_view_Reference.md).
# Melhorar os planos de consulta do Aurora PostgreSQL
Melhore o gerenciamento dos planos de consulta avaliando a performance e corrigindo os planos. Para ter mais informações sobre como melhorar planos de consulta, confira os tópicos a seguir.
**Topics**
+ [Avaliar performance do plano](#AuroraPostgreSQL.Optimize.Maintenance.EvaluatingPerformance)
+ [Corrigir planos usando pg\$1hint\$1plan](#AuroraPostgreSQL.Optimize.Maintenance.pg_hint_plan)
## Avaliar performance do plano
Depois que o otimizador capturar planos como não aprovados, use a função `apg_plan_mgmt.evolve_plan_baselines` para comparar planos com base na performance real. Dependendo do resultado dos experimentos de performance, altere o status de um plano de não aprovado para aprovado ou rejeitado. Em vez disso, opte por usar a função `apg_plan_mgmt.evolve_plan_baselines` para desabilitar temporariamente um plano caso ele não atenda aos requisitos.
### Aprovar planos melhores
O exemplo a seguir demonstra como alterar o status de planos gerenciados para aprovados usando a função `apg_plan_mgmt.evolve_plan_baselines`.
```
SELECT apg_plan_mgmt.evolve_plan_baselines (
sql_hash,
plan_hash,
min_speedup_factor := 1.0,
action := 'approve'
)
FROM apg_plan_mgmt.dba_plans WHERE status = 'Unapproved';
```
```
NOTICE: rangequery (1,10000)
NOTICE: Baseline [ Planning time 0.761 ms, Execution time 13.261 ms]
NOTICE: Baseline+1 [ Planning time 0.204 ms, Execution time 8.956 ms]
NOTICE: Total time benefit: 4.862 ms, Execution time benefit: 4.305 ms
NOTICE: Unapproved -> Approved
evolve_plan_baselines
-----------------------
0
(1 row)
```
A saída mostra um relatório de performance da instrução `rangequery` com associações de parâmetro 1 e 10.000. O novo plano não aprovado (`Baseline+1`) é melhor do que o melhor plano aprovado anteriormente (`Baseline`). Para confirmar se o novo plano já está `Approved`, verifique a visualização `apg_plan_mgmt.dba_plans`.
```
SELECT sql_hash, plan_hash, status, enabled, stmt_name
FROM apg_plan_mgmt.dba_plans;
```
```
sql_hash | plan_hash | status | enabled | stmt_name
------------+-----------+----------+---------+------------
1984047223 | 512153379 | Approved | t | rangequery
1984047223 | 512284451 | Approved | t | rangequery
(2 rows)
```
O plano gerenciado já inclui dois planos aprovados que são a linha de base do plano da instrução. Também é possível chamar a função `apg_plan_mgmt.set_plan_status` para definir diretamente o campo de status de um plano como `'Approved'`, `'Rejected'`, `'Unapproved'` ou `'Preferred'`.
### Rejeitar ou desabilitar planos mais lentos
Para rejeitar ou desabilitar planos, passe `'reject'` ou `'disable' `como o parâmetro de ação para a função `apg_plan_mgmt.evolve_plan_baselines`. Esse exemplo desativa todos os planos `Unapproved` capturados que sejam pelo menos 10% mais lentos do que o melhor plano `Approved` para a instrução.
```
SELECT apg_plan_mgmt.evolve_plan_baselines(
sql_hash, -- The managed statement ID
plan_hash, -- The plan ID
1.1, -- number of times faster the plan must be
'disable' -- The action to take. This sets the enabled field to false.
)
FROM apg_plan_mgmt.dba_plans
WHERE status = 'Unapproved' AND -- plan is Unapproved
origin = 'Automatic'; -- plan was auto-captured
```
Também defina diretamente um plano como rejeitado ou desabilitado. Para definir diretamente o campo habilitado de um plano como `true`, ou `false`, chame a função `apg_plan_mgmt.set_plan_enabled`. Para definir diretamente o campo de status de um plano como `'Approved'`, `'Rejected'`, `'Unapproved'` ou `'Preferred'`, chame a função `apg_plan_mgmt.set_plan_status`.
Para excluir planos que não são válidos e que você espera que permaneçam inválidos, use a função `apg_plan_mgmt.validate_plans`. Essa função permite excluir ou desabilitar planos inválidos. Para obter mais informações, consulte [Validar planos](AuroraPostgreSQL.Optimize.Deleting.md#AuroraPostgreSQL.Optimize.Maintenance.ValidatingPlans).
## Corrigir planos usando pg\$1hint\$1plan
O otimizador de consulta foi bem projetado para encontrar um plano ideal para todas as instruções e, na maioria dos casos, o otimizador encontra um plano bom. No entanto, às vezes, talvez você saiba que existe um plano muito melhor do que o gerado pelo otimizador. Duas maneiras recomendadas para fazer o otimizador gerar um plano desejado incluem usar a extensão `pg_hint_plan` ou definir variáveis GUC em PostgreSQL:
+ Extensão `pg_hint_plan` – especifique uma "dica" para modificar como o planejador funciona usando a extensão `pg_hint_plan` PostgreSQL. Para instalar e saber mais sobre com usar a extensão `pg_hint_plan`, consulte a [documentação pg\$1hint\$1plan](https://github.com/ossc-db/pg_hint_plan).
+ Variáveis GUC – Substitua um ou mais parâmetros de modelo de custo ou outros parâmetros de otimizador, como o `from_collapse_limit` ou o `GEQO_threshold`.
Ao usar uma dessas técnicas para forçar otimizador de consultas a usar um plano, também use o gerenciamento de planos de consultas para capturar impor o uso do novo plano.
Use a extensão `pg_hint_plan` para alterar a ordem da junção, os métodos da junção ou os caminhos de acesso de uma instrução SQL. Use um comentário SQL com sintaxe `pg_hint_plan` especial para modificar como o otimizador cria um plano. Por exemplo, suponhamos que a instrução SQL problemática tenha uma junção bidirecional.
```
SELECT *
FROM t1, t2
WHERE t1.id = t2.id;
```
Depois, suponhamos que o otimizador selecione a ordem de junção (t1, t2), embora você saiba que a ordem de junção (t2, t1) seja mais rápida. A dica a seguir força o otimizador a usar a ordem de junção mais rápida, (t2, t1). Inclua EXPLAIN, de maneira que o otimizador gere um plano para a declaração SQL, mas sem executar a declaração. (Saída não mostrada.)
```
/*+ Leading ((t2 t1)) */ EXPLAIN SELECT *
FROM t1, t2
WHERE t1.id = t2.id;
```
As etapas a seguir mostram como usar `pg_hint_plan`.
**Para modificar o plano gerado do otimizador e capturar o plano usando pg\$1hint\$1plan**
1. Ative o modo de captura manual.
```
SET apg_plan_mgmt.capture_plan_baselines = manual;
```
1. Especifique uma dica para a instrução SQL de interesse.
```
/*+ Leading ((t2 t1)) */ EXPLAIN SELECT *
FROM t1, t2
WHERE t1.id = t2.id;
```
Depois dessa execução, o otimizador captura o plano na visualização `apg_plan_mgmt.dba_plans`. O plano capturado não inclui a sintaxe do comentário especial `pg_hint_plan` porque o gerenciamento de planos de consultas normaliza a instrução removendo os principais comentários.
1. Veja os planos gerenciados usando a visualização `apg_plan_mgmt.dba_plans`.
```
SELECT sql_hash, plan_hash, status, sql_text, plan_outline
FROM apg_plan_mgmt.dba_plans;
```
1. Defina o status do plano como `Preferred`. Isso garante que o otimizador optará por executá-lo, em vez de selecioná-lo no conjunto de planos aprovados quando o plano de custo mínimo ainda não for `Approved` ou `Preferred`.
```
SELECT apg_plan_mgmt.set_plan_status(sql-hash, plan-hash, 'preferred' );
```
1. Desative a captura de plano manual e imponha o uso de planos gerenciados.
```
SET apg_plan_mgmt.capture_plan_baselines = false;
SET apg_plan_mgmt.use_plan_baselines = true;
```
Agora, quando a instrução SQL original for executada, o otimizador escolherá um plano `Approved` ou `Preferred`. Se o plano de custo mínimo não for `Approved` nem `Preferred`, o otimizador escolherá o plano `Preferred`.
# Excluir os planos de consulta do Aurora PostgreSQL
Exclua os planos de execução que você não está usando ou que não são válidos. Para ter mais informações sobre exclusão de planos, consulte as seções a seguir.
**Topics**
+ [Excluir planos](#AuroraPostgreSQL.Optimize.Maintenance.DeletingPlans)
+ [Validar planos](#AuroraPostgreSQL.Optimize.Maintenance.ValidatingPlans)
## Excluir planos
Os planos serão excluídos automaticamente se não forem utilizados em mais de um mês, especificamente, 32 dias. Essa é a configuração padrão do parâmetro `apg_plan_mgmt.plan_retention_period`. Você pode alterar o período de retenção do plano para um período mais longo ou mais curto, a partir do valor 1. A determinação do número de dias desde o último uso de um plano é calculada subtraindo a data `last_used` da data atual. A data `last_used` é a mais recente em que o otimizador selecionou um plano como plano de custo mínimo ou em que o plano foi executado. A data é armazenada para o plano na visualização `apg_plan_mgmt.dba_plans`.
Recomendamos que você exclua planos que não tiverem sido usados por muito tempo ou que não tiverem sido úteis. Cada plano tem uma data `last_used` atualizada pelo otimizador sempre que ele executa um plano ou o seleciona como o plano de custo mínimo para uma declaração. Confira as últimas datas `last_used` para identificar os planos que você pode excluir com segurança.
A consulta a seguir retorna uma tabela de três colunas com a contagem do número total de planos, dos planos que não foram excluídos e dos planos que foram excluídos. Há uma consulta aninhada que é um exemplo de como usar a função `apg_plan_mgmt.delete_plan` para excluir todos os planos que não tiverem sido selecionados como o plano de custo mínimo nos últimos 31 dias e o status não seja `Rejected`.
```
SELECT (SELECT COUNT(*) from apg_plan_mgmt.dba_plans) total_plans,
COUNT(*) FILTER (WHERE result = -1) failed_to_delete,
COUNT(*) FILTER (WHERE result = 0) successfully_deleted
FROM (
SELECT apg_plan_mgmt.delete_plan(sql_hash, plan_hash) as result
FROM apg_plan_mgmt.dba_plans
WHERE last_used < (current_date - interval '31 days')
AND status <> 'Rejected'
) as dba_plans ;
```
```
total_plans | failed_to_delete | successfully_deleted
-------------+------------------+----------------------
3 | 0 | 2
```
Para obter mais informações, consulte [apg\$1plan\$1mgmt.delete\$1plan](AuroraPostgreSQL.Optimize.Functions.md#AuroraPostgreSQL.Optimize.Functions.delete_plan).
Para excluir planos que não são válidos e que você espera que permaneçam inválidos, use a função `apg_plan_mgmt.validate_plans`. Essa função permite excluir ou desabilitar planos inválidos. Para obter mais informações, consulte [Validar planos](#AuroraPostgreSQL.Optimize.Maintenance.ValidatingPlans).
**Importante**
Caso você não exclua planos divergentes, poderá acabar ficando sem memória compartilhada separada para o gerenciamento de planos de consultas. Para controlar a memória disponível para planos gerenciados, use o parâmetro `apg_plan_mgmt.max_plans`. Defina esse parâmetro no grupo de parâmetros de banco de dados personalizado e reinicie a instância de banco de dados para que as alterações tenham efeito. Para obter mais informações, consulte o parâmetro [apg\$1plan\$1mgmt.max\$1plans](AuroraPostgreSQL.Optimize.Parameters.md#AuroraPostgreSQL.Optimize.Parameters.max_plans).
## Validar planos
Use a função `apg_plan_mgmt.validate_plans` para excluir ou desabilitar planos que sejam inválidos.
Os planos podem se tornar inválidos ou obsoletos quando objetos dependentes são removidos, como um índice ou uma tabela. No entanto, um plano só poderá ser inválido temporariamente se o objeto removido for recriado. Caso um plano inválido se torne válido depois, convém optar por desabilitar um plano inválido ou não fazer nada, em vez de excluí-lo.
Para encontrar e excluir todos os planos que sejam inválidos e que não tenham sido usados na semana passada, use a função `apg_plan_mgmt.validate_plans ` da maneira a seguir.
```
SELECT apg_plan_mgmt.validate_plans(sql_hash, plan_hash, 'delete')
FROM apg_plan_mgmt.dba_plans
WHERE last_used < (current_date - interval '7 days');
```
Para habilitar ou desabilitar diretamente um plano, use a função `apg_plan_mgmt.set_plan_enabled`.
# Exportar e importar planos gerenciados do Aurora PostgreSQL
Exporte os planos gerenciados e os importe para outra instância de banco de dados.
**Para exportar planos gerenciados**
Um usuário autorizado pode copiar qualquer subconjunto da tabela `apg_plan_mgmt.plans` para outra tabela e salvá-lo usando o comando `pg_dump`. Veja um exemplo a seguir.
```
CREATE TABLE plans_copy AS SELECT *
FROM apg_plan_mgmt.plans [ WHERE predicates ] ;
```
```
% pg_dump --table apg_plan_mgmt.plans_copy -Ft mysourcedatabase > plans_copy.tar
```
```
DROP TABLE apg_plan_mgmt.plans_copy;
```
**Para importar planos gerenciados**
1. Copie o arquivo .tar dos planos gerenciados exportados para o sistema onde os planos precisam ser restaurados.
1. Use o comando `pg_restore` a fim de copiar o arquivo tar para uma nova tabela.
```
% pg_restore --dbname mytargetdatabase -Ft plans_copy.tar
```
1. Mescle a tabela `plans_copy` com a tabela `apg_plan_mgmt.plans`, conforme mostrado no exemplo a seguir.
**nota**
Em alguns casos, você pode descarregar de uma versão da extensão `apg_plan_mgmt` e restaurar para outra versão. Nesses casos, as colunas na tabela de planos podem ser diferentes. Se for diferente, nomeie as colunas explicitamente, em vez de usar SELECT \$1.
```
INSERT INTO apg_plan_mgmt.plans SELECT * FROM plans_copy
ON CONFLICT ON CONSTRAINT plans_pkey
DO UPDATE SET
status = EXCLUDED.status,
enabled = EXCLUDED.enabled,
-- Save the most recent last_used date
--
last_used = CASE WHEN EXCLUDED.last_used > plans.last_used
THEN EXCLUDED.last_used ELSE plans.last_used END,
-- Save statistics gathered by evolve_plan_baselines, if it ran:
--
estimated_startup_cost = EXCLUDED.estimated_startup_cost,
estimated_total_cost = EXCLUDED.estimated_total_cost,
planning_time_ms = EXCLUDED.planning_time_ms,
execution_time_ms = EXCLUDED.execution_time_ms,
total_time_benefit_ms = EXCLUDED.total_time_benefit_ms,
execution_time_benefit_ms = EXCLUDED.execution_time_benefit_ms;
```
1. Recarregue os planos gerenciados na memória compartilhada e remova a tabela de planos temporária.
```
SELECT apg_plan_mgmt.reload(); -- refresh shared memory
DROP TABLE plans_copy;
```
# Referência de parâmetros do gerenciamento de planos de consultas do Aurora PostgreSQL
Você pode definir suas preferências para a extensão `apg_plan_mgmt` usando os parâmetros listados nesta seção. Eles estão disponíveis no parâmetro de cluster de banco de dados personalizado e no grupo de parâmetros de banco de dados associado ao seu cluster de banco de dados do Aurora PostgreSQL. Esses parâmetros controlam o comportamento do recurso de gerenciamento de planos de consultas e como ele afeta o otimizador. Para obter informações sobre como configurar o gerenciamento de planos de consultas, consulte [Ativar o gerenciamento de planos de consulta do Aurora PostgreSQL](AuroraPostgreSQL.Optimize.overview.md#AuroraPostgreSQL.Optimize.Enable). A alteração dos parâmetros a seguir não terá efeito se a extensão `apg_plan_mgmt` não for configurada conforme detalhado nessa seção. Para obter informações sobre como modificar parâmetros, consulte [Modificar parâmetros em um grupo de parâmetros de cluster de banco de dadosno Amazon Aurora](USER_WorkingWithParamGroups.ModifyingCluster.md) e [Grupos de parâmetros de banco de dados para instâncias de banco de dados do Amazon Aurora](USER_WorkingWithDBInstanceParamGroups.md).
**Topics**
+ [apg\$1plan\$1mgmt.capture\$1plan\$1baselines](#AuroraPostgreSQL.Optimize.Parameters.capture_plan_baselines)
+ [apg\$1plan\$1mgmt.plan\$1capture\$1threshold](#AuroraPostgreSQL.Optimize.Parameters.plan_capture_threshold)
+ [apg\$1plan\$1mgmt.explain\$1hashes](#AuroraPostgreSQL.Optimize.Parameters.explain_hashes)
+ [apg\$1plan\$1mgmt.log\$1plan\$1enforcement\$1result](#AuroraPostgreSQL.Optimize.Parameters.log_plan_enforcement_result)
+ [apg\$1plan\$1mgmt.max\$1databases](#AuroraPostgreSQL.Optimize.Parameters.max_databases)
+ [apg\$1plan\$1mgmt.max\$1plans](#AuroraPostgreSQL.Optimize.Parameters.max_plans)
+ [apg\$1plan\$1mgmt.plan\$1hash\$1version](#AuroraPostgreSQL.Optimize.Parameters.plan_hash_version)
+ [apg\$1plan\$1mgmt.plan\$1retention\$1period](#AuroraPostgreSQL.Optimize.Parameters.plan_retention_period)
+ [apg\$1plan\$1mgmt.unapproved\$1plan\$1execution\$1threshold](#AuroraPostgreSQL.Optimize.Parameters.unapproved_plan_execution_threshold)
+ [apg\$1plan\$1mgmt.use\$1plan\$1baselines](#AuroraPostgreSQL.Optimize.Parameters.use_plan_baselines)
+ [auto\$1explain.hashes](#AuroraPostgreSQL.Optimize.Parameters.auto_explain.hashes)
## apg\$1plan\$1mgmt.capture\$1plan\$1baselines
Captura os planos de execução de consultas gerados pelo otimizador para cada instrução SQL e os armazena na exibição `dba_plans`. Por padrão, o número máximo de planos que podem ser armazenados é 10.000, conforme especificado pelo parâmetro `apg_plan_mgmt.max_plans`. Para obter informações de referência, consulte [apg\$1plan\$1mgmt.max\$1plans](#AuroraPostgreSQL.Optimize.Parameters.max_plans).
É possível definir esse parâmetro no grupo de parâmetros do cluster de banco de dados personalizado ou no grupo de parâmetros do banco de dados personalizado. Alterar o valor desse parâmetro não requer uma reinicialização.
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/AmazonRDS/latest/AuroraUserGuide/AuroraPostgreSQL.Optimize.Parameters.html)
Para obter mais informações, consulte [Capturar planos de execução do Aurora PostgreSQL](AuroraPostgreSQL.Optimize.CapturePlans.md).
## apg\$1plan\$1mgmt.plan\$1capture\$1threshold
Especifica um limite para que, se o custo total do plano de execução da consulta estiver abaixo do limite, o plano não seja capturado na exibição. `apg_plan_mgmt.dba_plans`
Alterar o valor desse parâmetro não requer uma reinicialização.
| Padrão | Valores permitidos | Descrição |
| --- | --- | --- |
| 0 | 0 - 1.79769e\$1308 | Define o limite do custo total de execução do plano de consulta `apg_plan_mgmt` para captura de planos. |
Para obter mais informações, consulte [Examinar planos de consulta do Aurora PostgreSQL na exibição dba\$1plans](AuroraPostgreSQL.Optimize.ViewPlans.md).
## apg\$1plan\$1mgmt.explain\$1hashes
Especifica se `EXPLAIN [ANALYZE]` mostra `sql_hash` e `plan_hash` no final de sua saída. Alterar o valor desse parâmetro não requer uma reinicialização.
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/AmazonRDS/latest/AuroraUserGuide/AuroraPostgreSQL.Optimize.Parameters.html)
## apg\$1plan\$1mgmt.log\$1plan\$1enforcement\$1result
Especifica se os resultados precisam ser registrados para verificar se os planos gerenciados pelo QPM são usados corretamente. Quando um plano genérico armazenado é usado, não haverá registros gravados nos arquivos de log. Alterar o valor desse parâmetro não requer uma reinicialização.
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/AmazonRDS/latest/AuroraUserGuide/AuroraPostgreSQL.Optimize.Parameters.html)
## apg\$1plan\$1mgmt.max\$1databases
Especifica o número máximo de bancos de dados na instância Writer do seu cluster de banco de dados do Aurora PostgreSQL que podem usar o gerenciamento de planos de consultas. Por padrão, até 10 bancos de dados podem usar o gerenciamento de planos de consultas. Se você tiver mais de 10 bancos de dados na instância, poderá alterar o valor dessa configuração. Para descobrir quantos bancos de dados existem em determinada instância, conecte-se à instância usando `psql`. Depois, use o metacomando psql, `\l`, para listar os bancos de dados.
Alterar o valor desse parâmetro exige que você reinicialize a instância para que a configuração entre em vigor.
| Padrão | Valores permitidos | Descrição |
| --- | --- | --- |
| 10 | 10-2147483647 | Número máximo de bancos de dados que podem usar o gerenciamento de planos de consultas na instância. |
É possível definir esse parâmetro no grupo de parâmetros do cluster de banco de dados personalizado ou no grupo de parâmetros do banco de dados personalizado.
## apg\$1plan\$1mgmt.max\$1plans
Defina o número máximo de instruções SQL que o gerenciador de planos de consulta pode manter na visualização `apg_plan_mgmt.dba_plans`. Recomendamos definir esse parâmetro como `10000` ou superior para todas as versões do Aurora PostgreSQL.
É possível definir esse parâmetro no grupo de parâmetros do cluster de banco de dados personalizado ou no grupo de parâmetros do banco de dados personalizado. Alterar o valor desse parâmetro exige que você reinicialize a instância para que a configuração entre em vigor.
| Padrão | Valores permitidos | Descrição |
| --- | --- | --- |
| 10000 | 10-2147483647 | Número máximo de planos que podem ser armazenados na exibição `apg_plan_mgmt.dba_plans`. O padrão para o Aurora PostgreSQL versão 10 e anteriores é 1000. |
Para obter mais informações, consulte [Examinar planos de consulta do Aurora PostgreSQL na exibição dba\$1plans](AuroraPostgreSQL.Optimize.ViewPlans.md).
## apg\$1plan\$1mgmt.plan\$1hash\$1version
Especifica os casos de uso que o cálculo de plan\$1hash foi desenvolvido para atender. Uma versão superior de `apg_plan_mgmt.plan_hash_version` contém todas as funcionalidades da versão inferior. Por exemplo, a versão 3 atende aos casos de uso compatíveis com a versão 2.
A alteração do valor desse parâmetro deve ser seguida de uma chamada para `apg_plan_mgmt.validate_plans('update_plan_hash')`. Ela atualiza os valores de plan\$1hash em cada banco de dados com apg\$1plan\$1mgmt instalado e entradas na tabela de planos. Para obter mais informações, consulte . [Validar planos](AuroraPostgreSQL.Optimize.Deleting.md#AuroraPostgreSQL.Optimize.Maintenance.ValidatingPlans)
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/AmazonRDS/latest/AuroraUserGuide/AuroraPostgreSQL.Optimize.Parameters.html)
## apg\$1plan\$1mgmt.plan\$1retention\$1period
Especifica o número de dias em que os planos serão mantidos na exibição `apg_plan_mgmt.dba_plans`; serão excluídos automaticamente depois disso. Por padrão, um plano é excluído quando tiverem decorrido 32 dias desde o último uso do plano (a coluna `last_used` na exibição `apg_plan_mgmt.dba_plans`). Você pode alterar essa configuração para qualquer número, 1 ou mais.
Alterar o valor desse parâmetro exige que você reinicialize a instância para que a configuração entre em vigor.
| Padrão | Valores permitidos | Descrição |
| --- | --- | --- |
| 32 | 1-2147483647 | Número máximo de dias desde o último uso de um plano antes que seja excluído. |
Para obter mais informações, consulte [Examinar planos de consulta do Aurora PostgreSQL na exibição dba\$1plans](AuroraPostgreSQL.Optimize.ViewPlans.md).
## apg\$1plan\$1mgmt.unapproved\$1plan\$1execution\$1threshold
Especifica um limite de custo abaixo do qual um plano Não aprovado pode ser usado pelo otimizador. Por padrão, o limite é 0, portanto o otimizador não executa planos com status Não aprovado. Definir esse parâmetro como um limite de custo trivialmente baixo, como 100, evita a sobrecarga de fiscalização do plano em planos triviais. Você também pode definir esse parâmetro como um valor extremamente grande, como 10000000, usando o estilo reativo do gerenciamento do plano. Isso permite que o otimizador use todos os planos escolhidos sem sobrecarga de fiscalização do plano. Mas, quando um plano ruim é encontrado, você pode marcá-lo manualmente como “rejeitado” para que não seja usado na próxima vez.
O valor desse parâmetro representa uma estimativa de custo para execução de determinado plano. Se um plano Não aprovado estiver abaixo desse custo estimado, o otimizador o usará para a instrução SQL. Você pode ver os planos capturados e seu status (Aprovado, Não aprovado) na exibição `dba_plans`. Para saber mais, consulte [Examinar planos de consulta do Aurora PostgreSQL na exibição dba\$1plans](AuroraPostgreSQL.Optimize.ViewPlans.md).
Alterar o valor desse parâmetro não requer uma reinicialização.
| Padrão | Valores permitidos | Descrição |
| --- | --- | --- |
| 0 | 0-2147483647 | Estimativa de custo do plano abaixo da qual um plano Não aprovado é usado. |
Para obter mais informações, consulte [Usar planos gerenciados do Aurora PostgreSQL](AuroraPostgreSQL.Optimize.UsePlans.md).
## apg\$1plan\$1mgmt.use\$1plan\$1baselines
Especifica que o otimizador deve usar um dos planos capturados e armazenados com status Aprovado na exibição `apg_plan_mgmt.dba_plans`. Por padrão, esse parâmetro está desativado (false), fazendo com que o otimizador use o plano de custo mínimo que ele gera sem qualquer avaliação adicional. Ativar esse parâmetro (configurá-lo como true) força o otimizador a escolher um plano de execução de consulta para a instrução a partir da linha de base do plano. Para obter mais informações, consulte [Usar planos gerenciados do Aurora PostgreSQL](AuroraPostgreSQL.Optimize.UsePlans.md). Para encontrar uma imagem que detalha esse processo, consulte [Como o otimizador escolhe que plano executar.](AuroraPostgreSQL.Optimize.UsePlans.md#AuroraPostgreSQL.Optimize.UsePlans.ChoosePlans).
É possível definir esse parâmetro no grupo de parâmetros do cluster de banco de dados personalizado ou no grupo de parâmetros do banco de dados personalizado. Alterar o valor desse parâmetro não requer uma reinicialização.
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/AmazonRDS/latest/AuroraUserGuide/AuroraPostgreSQL.Optimize.Parameters.html)
Você pode avaliar os tempos de resposta de diferentes planos capturados e alterar o status do plano, conforme necessário. Para obter mais informações, consulte [Melhorar os planos de consulta do Aurora PostgreSQL](AuroraPostgreSQL.Optimize.Maintenance.md).
## auto\$1explain.hashes
Especifica se a saída de auto\$1explain mostra sql\$1hash e plan\$1hash. Alterar o valor desse parâmetro não requer uma reinicialização.
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/AmazonRDS/latest/AuroraUserGuide/AuroraPostgreSQL.Optimize.Parameters.html)
# Referência de funções do gerenciamento de planos de consultas do Aurora PostgreSQL
A extensão `apg_plan_mgmt` fornece as funções a seguir.
**Topics**
+ [apg\$1plan\$1mgmt.copy\$1outline](#AuroraPostgreSQL.Optimize.Functions.copy_outline)
+ [apg\$1plan\$1mgmt.delete\$1plan](#AuroraPostgreSQL.Optimize.Functions.delete_plan)
+ [apg\$1plan\$1mgmt.evolve\$1plan\$1baselines](#AuroraPostgreSQL.Optimize.Functions.evolve_plan_baselines)
+ [apg\$1plan\$1mgmt.get\$1explain\$1plan](#AuroraPostgreSQL.Optimize.Functions.get_explain_plan)
+ [apg\$1plan\$1mgmt.plan\$1last\$1used](#AuroraPostgreSQL.Optimize.Functions.plan_last_used)
+ [apg\$1plan\$1mgmt.reload](#AuroraPostgreSQL.Optimize.Functions.reload)
+ [apg\$1plan\$1mgmt.set\$1plan\$1enabled](#AuroraPostgreSQL.Optimize.Functions.set_plan_enabled)
+ [apg\$1plan\$1mgmt.set\$1plan\$1status](#AuroraPostgreSQL.Optimize.Functions.set_plan_status)
+ [apg\$1plan\$1mgmt.update\$1plans\$1last\$1used](#AuroraPostgreSQL.Optimize.Functions.update_plans_last_used)
+ [apg\$1plan\$1mgmt.validate\$1plans](#AuroraPostgreSQL.Optimize.Functions.validate_plans)
## apg\$1plan\$1mgmt.copy\$1outline
Copie um determinado hash do plano SQL e o esboço do plano para um hash e um esboço do plano SQL de destino, substituindo assim o hash e o esboço do plano de destino. Essa função está disponível no `apg_plan_mgmt` 2.3 e superiores.
**Sintaxe**
```
apg_plan_mgmt.copy_outline(
source_sql_hash,
source_plan_hash,
target_sql_hash,
target_plan_hash,
force_update_target_plan_hash
)
```
**Valor de retorno**
Retorna 0 quando a cópia é bem-sucedida. Gera exceções para entradas inválidas.
**Parâmetros**
****
| Parâmetro | Descrição |
| --- | --- |
| source\$1sql\$1hash | O ID sql\$1hash associado ao plan\$1hash a ser copiado na consulta de destino. |
| source\$1plan\$1hash | O ID plan\$1hash a ser copiado na consulta de destino. |
| target\$1sql\$1hash | O ID sql\$1hash da consulta a ser atualizada com o hash e o esboço do plano de origem. |
| target\$1plan\$1hash | O ID plan\$1hash da consulta a ser atualizada com o hash e o esboço do plano de origem. |
| force\$1update\$1target\$1plan\$1hash | (Opcional) O ID target\$1plan\$1hash da consulta é atualizado mesmo que o plano de origem não seja reproduzível para o target\$1sql\$1hash. Quando definida como verdadeira, a função pode ser usada para copiar planos em esquemas em que os nomes e as colunas das relações são consistentes. |
**Observações de uso**
Essa função permite que você copie um hash do plano e um esboço do plano que usam dicas para outras declarações semelhantes e, assim, evita que você precise usar instruções de dica em linha em cada ocorrência nas declarações de destino. Se a consulta de destino atualizada ocasionar um plano inválido, essa função gerará um erro e reverterá a tentativa de atualização.
## apg\$1plan\$1mgmt.delete\$1plan
Exclua um plano gerenciado.
**Sintaxe**
```
apg_plan_mgmt.delete_plan(
sql_hash,
plan_hash
)
```
**Valor de retorno**
Retorna 0 caso a exclusão tenha sido bem-sucedida ou -1 em caso de falha na exclusão.
**Parâmetros**
****
| Parâmetro | Descrição |
| --- | --- |
| sql\$1hash | O ID sql\$1hash da instrução SQL gerenciada do plano. |
| plan\$1hash | O ID plan\$1hash do plano gerenciado. |
## apg\$1plan\$1mgmt.evolve\$1plan\$1baselines
Verifica se um plano já aprovado é mais rápido ou se um plano identificado pelo otimizador de consultas como um plano de custo mínimo é mais rápido.
**Sintaxe**
```
apg_plan_mgmt.evolve_plan_baselines(
sql_hash,
plan_hash,
min_speedup_factor,
action
)
```
**Valor de retorno**
O número de planos que não eram mais rápidos do que o melhor plano aprovado.
**Parâmetros**
****
| Parâmetro | Descrição |
| --- | --- |
| sql\$1hash | O ID sql\$1hash da instrução SQL gerenciada do plano. |
| plan\$1hash | O ID plan\$1hash do plano gerenciado. Use NULL como média de todos os planos que tenham o mesmo valor de ID sql\$1hash. |
| min\$1speedup\$1factor | O *fator de agilização mínimo* pode ser o número de vezes mais rápido que um plano deve ser em relação ao melhor dos planos já aprovados para aprová-lo. Como alternativa, esse fator pode ser o número de vezes mais lento que um plano deve ser para rejeitá-lo ou desabilitá-lo. Trata-se de um valor flutuante positivo. |
| action | A ação que a função deve realizar. Entre os valores válidos estão os seguintes. O uso de maiúsculas ou minúsculas não importa. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/AmazonRDS/latest/AuroraUserGuide/AuroraPostgreSQL.Optimize.Functions.html) |
** Observações de uso**
Defina planos especificados como aprovados, rejeitados ou desabilitados com base na velocidade do planejamento mais o tempo de execução ser maior ou não que o melhor plano aprovado por um fator definido por você. O parâmetro de ação pode ser definido como `'approve'` ou `'reject'` para aprovar ou rejeitar automaticamente um plano que atenda aos critérios de performance. Como alternativa, ele pode ser definido como '' (string vazia) para realizar o experimento de performance e produzir um relatório, mas não realizar ação.
Você pode evitar a reexecução infundada da função `apg_plan_mgmt.evolve_plan_baselines` de um plano no qual ela foi executada recentemente. Para isso, restrinja os planos a apenas os planos não aprovados criados recentemente. Também é possível evitar executar a função `apg_plan_mgmt.evolve_plan_baselines` em qualquer plano aprovado que tenha um timestamp `last_verified` recente.
Realize um experimento de performance para comparar o tempo de planejamento mais execução de cada plano relativo aos outros planos na linha de base. Em alguns casos, talvez haja somente um plano para uma instrução e o plano seja aprovado. Nesse caso, compare o tempo de planejamento mais execução do plano com o tempo de planejamento mais execução de nenhum plano usado.
O benefício incremental (ou desvantagem) de cada plano é registrado na visualização `apg_plan_mgmt.dba_plans` na coluna `total_time_benefit_ms`. Quando esse valor é positivo, há uma vantagem de performance mensurável em incluir esse plano na linha de base.
Além de coletar o tempo de planejamento e execução de cada plano candidato, a coluna `last_verified` da visualização `apg_plan_mgmt.dba_plans` é atualizada com o `current_timestamp`. O time stamp `last_verified` pode ser usado para evitar a reexecução dessa função em um plano que recentemente teve a verificação da performance.
## apg\$1plan\$1mgmt.get\$1explain\$1plan
Gera o texto de uma instrução `EXPLAIN` para a instrução SQL especificada.
**Sintaxe**
```
apg_plan_mgmt.get_explain_plan(
sql_hash,
plan_hash,
[explainOptionList]
)
```
**Valor de retorno**
Retorna estatísticas de tempo de execução para as instruções SQL especificadas. Use sem `explainOptionList` para retornar um plano `EXPLAIN` simples.
**Parâmetros**
****
| Parâmetro | Descrição |
| --- | --- |
| sql\$1hash | O ID sql\$1hash da instrução SQL gerenciada do plano. |
| plan\$1hash | O ID plan\$1hash do plano gerenciado. |
| explainOptionList | Uma lista separada por vírgulas com opções de explicação. Os valores válidos incluem `'analyze'`, `'verbose'`, `'buffers'`, `'hashes'` e `'format json'`. Se a lista de `explainOptionList` for NULL (NULA) ou uma string vazia (''), essa função gerará uma instrução `EXPLAIN` sem nenhuma estatística. |
**Observações de uso**
Para a `explainOptionList`, você pode usar qualquer uma das mesmas opções que você usaria com uma instrução `EXPLAIN`. O otimizador do Aurora PostgreSQL concatena a lista de opções que você fornece à instrução `EXPLAIN`.
## apg\$1plan\$1mgmt.plan\$1last\$1used
Retorna a data `last_used` do plano especificado da memória compartilhada.
**nota**
O valor na memória compartilhada é sempre atual na instância de banco de dados primária do cluster de banco de dados. Esse valor é apenas periodicamente liberado na coluna `last_used` da visualização `apg_plan_mgmt.dba_plans`.
**Sintaxe**
```
apg_plan_mgmt.plan_last_used(
sql_hash,
plan_hash
)
```
**Valor de retorno**
Retorna a data `last_used`.
**Parâmetros**
****
| Parâmetro | Descrição |
| --- | --- |
| sql\$1hash | O ID sql\$1hash da instrução SQL gerenciada do plano. |
| plan\$1hash | O ID plan\$1hash do plano gerenciado. |
## apg\$1plan\$1mgmt.reload
Recarregue planos na memória compartilhada da visualização `apg_plan_mgmt.dba_plans`.
**Sintaxe**
```
apg_plan_mgmt.reload()
```
**Valor de retorno**
Nenhum.
**Parâmetros**
Nenhum.
** Observações de uso**
Chame `reload` para as seguintes situações:
+ Use-o para atualizar a memória compartilhada de uma réplica somente leitura imediatamente, em vez de aguardar a propagação de novos planos para a réplica.
+ Use-o após a importação de planos gerenciados.
## apg\$1plan\$1mgmt.set\$1plan\$1enabled
Habilite ou desabilite um plano gerenciado.
**Sintaxe**
```
apg_plan_mgmt.set_plan_enabled(
sql_hash,
plan_hash,
[true | false]
)
```
**Valor de retorno**
Retorna 0 caso a definição tenha sido bem-sucedida ou -1 em caso de falha na definição.
**Parâmetros**
****
| Parâmetro | Descrição |
| --- | --- |
| sql\$1hash | O ID sql\$1hash da instrução SQL gerenciada do plano. |
| plan\$1hash | O ID plan\$1hash do plano gerenciado. |
| enabled | Valores boolianos de verdadeiro ou falso: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/AmazonRDS/latest/AuroraUserGuide/AuroraPostgreSQL.Optimize.Functions.html) |
## apg\$1plan\$1mgmt.set\$1plan\$1status
Defina o status de um plano gerenciado como `Approved`, `Unapproved`, `Rejected`, ou `Preferred`.
**Sintaxe**
```
apg_plan_mgmt.set_plan_status(
sql_hash,
plan_hash,
status
)
```
**Valor de retorno**
Retorna 0 caso a definição tenha sido bem-sucedida ou -1 em caso de falha na definição.
**Parâmetros**
****
| Parâmetro | Descrição |
| --- | --- |
| sql\$1hash | O ID sql\$1hash da instrução SQL gerenciada do plano. |
| plan\$1hash | O ID plan\$1hash do plano gerenciado. |
| status | Uma string com um dos seguintes valores: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/AmazonRDS/latest/AuroraUserGuide/AuroraPostgreSQL.Optimize.Functions.html) A formatação de maiúsculas/minúsculas usada não importa. No entanto, o valor do status é definido com maiúsculas iniciais na visualização `apg_plan_mgmt.dba_plans`. Para obter mais informações sobre esses valores, consulte `status` em [Referência da visualização apg\$1plan\$1mgmt.dba\$1plans da edição compatível do Aurora PostgreSQL](AuroraPostgreSQL.Optimize.dba_plans_view_Reference.md). |
## apg\$1plan\$1mgmt.update\$1plans\$1last\$1used
Atualiza imediatamente a tabela de planos com a data de `last_used` armazenada na memória compartilhada.
**Sintaxe**
```
apg_plan_mgmt.update_plans_last_used()
```
**Valor de retorno**
Nenhum.
**Parâmetros**
Nenhum.
** Observações de uso**
Chame `update_plans_last_used` para garantir que as consultas na coluna `dba_plans.last_used` usem as informações mais atuais. Se a data `last_used` não for atualizada imediatamente, um processo em segundo plano atualizará a tabela de planos com a data de `last_used` uma vez a cada hora (por padrão).
Por exemplo, se uma instrução com um determinado `sql_hash` começar a ser executada lentamente, será possível determinar quais planos para essa instrução foram executados desde que a regressão de performance começou. Para fazer isso, primeiro descarregue os dados da memória compartilhada no disco para que as datas de `last_used` sejam atuais e, em seguida, consulte todos os planos de `sql_hash` da instrução com a regressão de performance. Na consulta, certifique-se de que a data de `last_used` seja igual ou posterior à data em que a regressão de performance começou. A consulta identifica o plano ou o conjunto de planos que pode ser o responsável pela regressão de performance. Você pode utilizar `apg_plan_mgmt.get_explain_plan` com `explainOptionList` definido como `verbose, hashes`. Também é possível utilizar `apg_plan_mgmt.evolve_plan_baselines` para analisar o plano e quaisquer planos alternativos que possam ter performance melhor.
A função `update_plans_last_used` tem efeito somente na instância de banco de dados primária do cluster de banco de dados.
## apg\$1plan\$1mgmt.validate\$1plans
Valide se o otimizador ainda pode recriar planos. O otimizador valida os planos `Approved`, `Unapproved` e `Preferred`, independentemente de o plano estar ativado ou desativado. Planos `Rejected` não são validados. Também é possível usar a função `apg_plan_mgmt.validate_plans` para excluir ou desabilitar planos inválidos.
**Sintaxe**
```
apg_plan_mgmt.validate_plans(
sql_hash,
plan_hash,
action)
apg_plan_mgmt.validate_plans(
action)
```
**Valor de retorno**
O número de planos inválidos.
**Parâmetros**
****
| Parâmetro | Descrição |
| --- | --- |
| sql\$1hash | O ID sql\$1hash da instrução SQL gerenciada do plano. |
| plan\$1hash | O ID plan\$1hash do plano gerenciado. Use NULL como média de todos os planos para o mesmo valor de ID sql\$1hash. |
| action | A ação que a função deve realizar em planos inválidos. Entre os valores de string válidos estão os seguintes. O uso de maiúsculas ou minúsculas não importa. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/AmazonRDS/latest/AuroraUserGuide/AuroraPostgreSQL.Optimize.Functions.html) Todos os outros valores são tratados como strings vazias. |
**Observações de uso**
Use a forma `validate_plans(action)` a fim de validar todos os planos gerenciados para todas as instruções gerenciadas em toda a exibição `apg_plan_mgmt.dba_plans`.
Use a forma `validate_plans(sql_hash, plan_hash, action)` para validar um plano gerenciado especificado com `plan_hash`, para uma instrução gerenciada especificada com `sql_hash`.
Use a forma `validate_plans(sql_hash, NULL, action)` a fim de validar todos os planos gerenciados para a instrução gerenciada especificada com `sql_hash`.
# Referência da visualização apg\$1plan\$1mgmt.dba\$1plans da edição compatível do Aurora PostgreSQL
As colunas das informações do plano na visualização `apg_plan_mgmt.dba_plans` incluem o seguinte.
| Coluna dba\$1plans | Descrição |
| --- | --- |
| cardinality\$1error | Uma medida do erro entre a cardinalidade estimada em comparação com a cardinalidade real. *Cardinalidade* é o número de linhas da tabela que o plano deve processar. Se a cardinalidade for grande, aumentará a probabilidade de o plano não ser ideal. Essa coluna é preenchida pela função [apg\$1plan\$1mgmt.evolve\$1plan\$1baselines](AuroraPostgreSQL.Optimize.Functions.md#AuroraPostgreSQL.Optimize.Functions.evolve_plan_baselines). |
| compatibility\$1level | Esse parâmetro mostra quando um plano de consulta foi validado pela última vez. Nas versões 12.19, 13.15, 14.12, 15.7, 16.3 e posteriores do Aurora PostgreSQL, ele exibe o número da versão do Aurora. Para versões anteriores, ele exibe um número de versão específico do recurso. Mantenha o valor desse parâmetro na configuração padrão. O Aurora PostgreSQL define e atualiza automaticamente esse valor. |
| created\$1by | O usuário autenticado (session\$1user) que criou o plano. |
| enabled | Um indicador da habilitação ou de desabilitação do plano. Todos os planos permanecem habilitados por padrão. Desabilite os planos para evitar que eles sejam usados pelo otimizador. Para modificar esse valor, use a função [apg\$1plan\$1mgmt.set\$1plan\$1enabled](AuroraPostgreSQL.Optimize.Functions.md#AuroraPostgreSQL.Optimize.Functions.set_plan_enabled). |
| environment\$1variables | Os parâmetros Grand Unified Configuration (GUC – Grande configuração unificada) PostgreSQL e os valores substituídos pelo otimizados no momento em que o plano foi capturado. |
| estimated\$1startup\$1cost | O custo de configuração do otimizador estimado antes da entrega de uma tabela pelo otimizador. |
| estimated\$1total\$1cost | O custo de entrega do otimizador estimado da linha da tabela final. |
| execution\$1time\$1benefit\$1ms | O benefício do tempo de execução, em milissegundos, da habilitação do plano. Essa coluna é preenchida pela função [apg\$1plan\$1mgmt.evolve\$1plan\$1baselines](AuroraPostgreSQL.Optimize.Functions.md#AuroraPostgreSQL.Optimize.Functions.evolve_plan_baselines). |
| execution\$1time\$1ms | O tempo estimado, em milissegundos, de execução do plano. Essa coluna é preenchida pela função [apg\$1plan\$1mgmt.evolve\$1plan\$1baselines](AuroraPostgreSQL.Optimize.Functions.md#AuroraPostgreSQL.Optimize.Functions.evolve_plan_baselines). |
| has\$1side\$1effects | Um valor que indica que a instrução SQL é uma instrução Data Manipulation Language (DML) ou uma instrução SELECT que contém uma função VOLATILE. |
| last\$1used | Esse valor é atualizado para a data atual sempre que o plano é executado ou quando o plano é o de custo mínimo do otimizador de consultas. Esse valor é armazenado em memória compartilhada e enviado periodicamente para o disco. Para obter o valor mais atualizado, leia a data da memória compartilhada chamando a função apg\$1plan\$1mgmt.plan\$1last\$1used(sql\$1hash, plan\$1hash), em vez de ler o valor last\$1used. Para obter informações adicionais, consulte o parâmetro [apg\$1plan\$1mgmt.plan\$1retention\$1period](AuroraPostgreSQL.Optimize.Parameters.md#AuroraPostgreSQL.Optimize.Parameters.plan_retention_period). |
| last\$1validated | A data e a hora mais recentes quando se verificou que o plano poderia ser recriado pela função [apg\$1plan\$1mgmt.validate\$1plans](AuroraPostgreSQL.Optimize.Functions.md#AuroraPostgreSQL.Optimize.Functions.validate_plans) ou pela função [apg\$1plan\$1mgmt.evolve\$1plan\$1baselines](AuroraPostgreSQL.Optimize.Functions.md#AuroraPostgreSQL.Optimize.Functions.evolve_plan_baselines). |
| last\$1verified | A data e a hora mais recentes quando se verificou que um plano era o de melhor performance para o parâmetro especificado pela função [apg\$1plan\$1mgmt.evolve\$1plan\$1baselines](AuroraPostgreSQL.Optimize.Functions.md#AuroraPostgreSQL.Optimize.Functions.evolve_plan_baselines). |
| origin | Como o plano foi capturado com o parâmetro [apg\$1plan\$1mgmt.capture\$1plan\$1baselines](AuroraPostgreSQL.Optimize.Parameters.md#AuroraPostgreSQL.Optimize.Parameters.capture_plan_baselines). Entre os valores válidos estão os seguintes: `M` – O plano foi capturado com a captura de planos manual. `A` – O plano foi capturado com a captura de planos automática. |
| param\$1list | Os valores de parâmetro que foram passados para a instrução, caso esta seja uma instrução preparada. |
| plan\$1created | A data e a hora em que o plano foi criado. |
| plan\$1hash | O identificador do plano. A combinação de plan\$1hash e sql\$1hash identifica com exclusividade um plano específico. |
| plan\$1outline | Uma representação do plano usado para recriar o plano de execução real e que seja independentemente em relação ao banco de dados. Os operadores na árvore correspondem aos operadores exibidos na saída EXPLAIN. |
| planning\$1time\$1ms | O tempo real de execução do planejador, em milissegundos. Essa coluna é preenchida pela função [apg\$1plan\$1mgmt.evolve\$1plan\$1baselines](AuroraPostgreSQL.Optimize.Functions.md#AuroraPostgreSQL.Optimize.Functions.evolve_plan_baselines). |
| queryId | Um hash de instrução, conforme calculado pela extensão pg\$1stat\$1statements. Não se trata de um identificador estável ou independente de banco de dados porque ele depende de Object Identifiers (OIDs – Identificadores de objetos). O valor será 0 se compute\$1query\$1id for off ao capturar o plano de consulta. |
| sql\$1hash | Um valor de hash do texto de instrução SQL, normalizado sem literais. |
| sql\$1text | O texto completo da instrução SQL. |
| status | O status de um plano, que determina como o otimizador usa um plano. Entre os valores válidos estão os seguintes. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/AmazonRDS/latest/AuroraUserGuide/AuroraPostgreSQL.Optimize.dba_plans_view_Reference.html) |
| stmt\$1name | O nome da instrução SQL dentro de uma instrução PREPARE. Este valor é uma string vazia para uma instrução preparada não nomeada. Este valor é NULL para uma instrução não preparada. |
| total\$1time\$1benefit\$1ms | O benefício do tempo total, em milissegundos, da habilitação desse plano. Este valor considera o tempo de planejamento e o tempo de execução. Caso esse valor seja negativo, há uma desvantagem em habilitar esse plano. Essa coluna é preenchida pela função [apg\$1plan\$1mgmt.evolve\$1plan\$1baselines](AuroraPostgreSQL.Optimize.Functions.md#AuroraPostgreSQL.Optimize.Functions.evolve_plan_baselines). |
# Atributos avançados do gerenciamento de planos de consultas
A seguir, você encontrará informações sobre os atributos avançados do gerenciamento de planos de consulta (QPM) do Aurora PostgreSQL:
**Topics**
+ [Capturar planos de execução nas réplicas do Aurora PostgreSQL](AuroraPostgreSQL.QPM.Plancapturereplicas.md)
+ [Compatibilidade ao particionamento de tabelas](AuroraPostgreSQL.QPM.Partitiontable.md)
# Capturar planos de execução nas réplicas do Aurora PostgreSQL
O QPM (gerenciamento de planos de consulta) permite capturar os planos de consulta gerados pelas réplicas do Aurora e armazená-los na instância de banco de dados primária do cluster de banco de dados do Aurora. Você pode coletar os planos de consulta de todas as réplicas do Aurora e manter um conjunto de planos ideais em uma tabela persistente central na instância primária. Então, você pode aplicar esses planos a outras réplicas quando necessário. Isso ajuda você a manter a estabilidade dos planos de execução e melhorar a performance das consultas nos clusters de banco de dados e nas versões do mecanismo.
**Topics**
+ [Pré-requisitos](#AuroraPostgreSQL.QPM.Plancapturereplicas.Prereq)
+ [Gerenciar a captura de planos em réplicas do Aurora](#AuroraPostgreSQL.QPM.Plancapturereplicas.managing)
+ [Solução de problemas](#AuroraPostgreSQL.QPM.Plancapturereplicas.Troubleshooting)
## Pré-requisitos
**Ativar `capture_plan_baselines parameter` na réplica do Aurora**: defina o parâmetro `capture_plan_baselines` como automático ou manual para capturar os planos nas réplicas do Aurora. Para ter mais informações, consulte [apg\$1plan\$1mgmt.capture\$1plan\$1baselines](AuroraPostgreSQL.Optimize.Parameters.md#AuroraPostgreSQL.Optimize.Parameters.capture_plan_baselines).
**Instalar a extensão postgres\$1fdw**: você deve instalar a extensão `postgres_fdw` externa do wrapper de dados para capturar os planos nas réplicas do Aurora. Para instalar a extensão, execute o command a seguir o em cada banco de dados.
```
postgres=> CREATE EXTENSION IF NOT EXISTS postgres_fdw;
```
## Gerenciar a captura de planos em réplicas do Aurora
**Ativar a captura de planos em réplicas do Aurora**
Você deve ter privilégios de `rds_superuser` para criar ou remover a captura de planos nas réplicas do Aurora. Para obter mais informações sobre funções e permissões de usuário, consulte [Noções básicas de perfis e permissões do PostgreSQL](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Appendix.PostgreSQL.CommonDBATasks.Roles.html).
Para capturar planos, chame a função apg\$1plan\$1mgmt.create\$1replica\$1plan\$1capture na instância de banco de dados de gravação, conforme mostrado a seguir:
```
postgres=> CALL apg_plan_mgmt.create_replica_plan_capture('endpoint', 'password');
```
+ endpoint: o endpoint de gravador ou o cluster\$1endpoint do Aurora Global Database oferece suporte a failover para captura de planos em réplicas do Aurora.
Para ter mais informações sobre o endpoint de gravador do Aurora Global Database, consulte [Visualizar os endpoints de um Amazon Aurora Global Database](aurora-global-database-connecting.md#viewing-endpoints).
Para ter mais informações sobre endpoints do cluster, consulte [Endpoints de cluster para Amazon Aurora](Aurora.Endpoints.Cluster.md).
+ Senha: siga as diretrizes abaixo ao criar a senha para aumentar a segurança:
+ Deve conter pelo menos oito caracteres.
+ Deve conter pelo menos uma letra maiúscula, uma letra minúscula e um número.
+ Deve ter pelo menos um caractere especial (`?`, `!`, `#`, `<`, `>`, `*` e assim por diante).
**nota**
Se você alterar o endpoint, a senha ou o número da porta, deverá executar `apg_plan_mgmt.create_replica_plan_capture()` novamente com o endpoint e a senha para reinicializar a captura de plano. Caso contrário, os planos de captura das réplicas do Aurora falharão.
**Desativar a captura de planos em réplicas do Aurora**
Você pode desativar o parâmetro `capture_plan_baselines` na réplica do Aurora definindo o respectivo valor como `off` no grupo de parâmetros.
**Remover a captura de planos em réplicas do Aurora**
Você pode remover completamente a captura de planos nas réplicas do Aurora, mas certifique-se antes de fazer isso. Para remover a captura de planos, chame `apg_plan_mgmt.remove_replica_plan_capture` conforme mostrado:
```
postgres=> CALL apg_plan_mgmt.remove_replica_plan_capture();
```
Você deve chamar apg\$1plan\$1mgmt.create\$1replica\$1plan\$1capture() novamente para ativar a captura de planos nas réplicas do Aurora com o endpoint e a senha.
## Solução de problemas
A seguir vão algumas ideias e soluções alternativas de problemas caso o plano não seja capturado nas réplicas do Aurora conforme o esperado.
+ **Configurações de parâmetros**: verifique se o parâmetro `capture_plan_baselines` está definido com o valor adequado para ativar a captura de planos.
+ A **extensão `postgres_fdw` está instalada**: use a consulta a seguir para verificar se `postgres_fdw` está instalada.
```
postgres=> SELECT * FROM pg_extension WHERE extname = 'postgres_fdw'
```
+ **create\$1replica\$1plan\$1capture() é chamado**: use o comando a seguir para verificar se o mapeamento do usuário existe. Caso contrário, chame `create_replica_plan_capture()` para inicializar o atributo.
```
postgres=> SELECT * FROM pg_foreign_server WHERE srvname = 'apg_plan_mgmt_writer_foreign_server';
```
+ **Endpoint e número da porta**: verifique se o endpoint e o número da porta são apropriados. Não haverá nenhuma mensagem de erro exibida se esses valores estiverem incorretos.
Use o comando a seguir para verificar se o endpoint é usado no create() e para verificar em qual banco de dados ele reside:
```
postgres=> SELECT srvoptions FROM pg_foreign_server WHERE srvname = 'apg_plan_mgmt_writer_foreign_server';
```
+ **reload ()**: você deve chamar apg\$1plan\$1mgmt.reload() depois de chamar apg\$1plan\$1mgmt.delete\$1plan() nas réplicas do Aurora para tornar a função delete efetiva. Isso garante que a mudança seja implementada com sucesso.
+ **Senha**: você deve inserir a senha em create\$1replica\$1plan\$1capture() de acordo com as diretrizes mencionadas. Caso contrário, você receberá uma mensagem de erro. Para obter mais informações, consulte [Gerenciar a captura de planos em réplicas do Aurora](#AuroraPostgreSQL.QPM.Plancapturereplicas.managing). Use outra senha que esteja de acordo com os requisitos.
+ **Conexão entre regiões**: a captura de planos nas réplicas do Aurora também é compatível com o banco de dados global do Aurora, onde a instância de gravação e as réplicas do Aurora podem estar em regiões diferentes. Use o endpoint de gravador do Aurora Global Database para manter a conectividade após eventos de failover ou transição. Para ter mais informações sobre os endpoints do Aurora Global Database, consulte [Visualizar os endpoints de um Amazon Aurora Global Database](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/aurora-global-database-connecting.html#viewing-endpoints). A instância de gravação e a réplica entre regiões devem ser capazes de se comunicar usando o emparelhamento de VPC. Para obter mais informações, consulte [Emparelhamento de VPC](https://docs.aws.amazon.com/vpc/latest/peering/what-is-vpc-peering.html). Se ocorrer um failover entre regiões, você deverá reconfigurar o endpoint com o novo endpoint primário do cluster de banco de dados.
**nota**
Ao usar um endpoint de cluster em vez de um endpoint de gravador do Aurora Global Database, você precisará atualizar o endpoint de cluster depois de realizar uma operação de failover ou transição global.
# Compatibilidade ao particionamento de tabelas
O gerenciamento de planos de consulta (QPM) do Aurora PostgreSQL comporta o particionamento de tabelas nas seguintes versões:
+ 15.3 e versões 15 posteriores
+ 14.8 e versões 14 posteriores
+ 13.11 e versões 13 posteriores
Para obter mais informações, consulte [Particionamento de tabelas](https://www.postgresql.org/docs/current/ddl-partitioning.html).
**Topics**
+ [Configurar o particionamento de tabelas](#AuroraPostgreSQL.QPM.Partitiontable.setup)
+ [Capturar planos para o particionamento de tabelas](#AuroraPostgreSQL.QPM.Partitiontable.capture)
+ [Aplicar um plano de particionamento de tabelas](#AuroraPostgreSQL.QPM.Partitiontable.enforcement)
+ [Convenção de nomenclatura](#AuroraPostgreSQL.QPM.Partitiontable.naming.convention)
## Configurar o particionamento de tabelas
Para configurar o particionamento de tabelas no QPM do Aurora PostgreSQL, faça o seguinte:
1. Defina `apg_plan_mgmt.plan_hash_version` como 3 ou mais no grupo de parâmetros do cluster de banco de dados.
1. Navegue até um banco de dados que usa o Gerenciamento de Planos de Consulta e que tem entradas na visualização de `apg_plan_mgmt.dba_plans`.
1. Ligue para `apg_plan_mgmt.validate_plans('update_plan_hash')` a fim de atualizar o valor de `plan_hash` na tabela de planos.
1. Repita as etapas 2 e 3 para todos os bancos de dados com o Gerenciamento de Planos de Consulta ativado e que tenham entradas na visualização `apg_plan_mgmt.dba_plans`.
Para obter mais informações sobre esses parâmetros, consulte [Referência de parâmetros do gerenciamento de planos de consultas do Aurora PostgreSQL](AuroraPostgreSQL.Optimize.Parameters.md).
## Capturar planos para o particionamento de tabelas
No QPM, planos diferentes são diferenciados pelo valor de `plan_hash`. Para entender como `plan_hash` muda, primeiro é necessário conhecer tipos semelhantes de planos.
A combinação de métodos de acesso, nomes de índice sem dígitos e nomes de partição sem dígitos, acumulados no nó de anexação, deve ser constante para que os planos sejam considerados iguais. As partições específicas acessadas nos planos não são significativas. No exemplo a seguir, uma tabela `tbl_a` é criada com quatro partições.
```
postgres=>create table tbl_a(i int, j int, k int, l int, m int) partition by range(i);
CREATE TABLE
postgres=>create table tbl_a1 partition of tbl_a for values from (0) to (1000);
CREATE TABLE
postgres=>create table tbl_a2 partition of tbl_a for values from (1001) to (2000);
CREATE TABLE
postgres=>create table tbl_a3 partition of tbl_a for values from (2001) to (3000);
CREATE TABLE
postgres=>create table tbl_a4 partition of tbl_a for values from (3001) to (4000);
CREATE TABLE
postgres=>create index t_i on tbl_a using btree (i);
CREATE INDEX
postgres=>create index t_j on tbl_a using btree (j);
CREATE INDEX
postgres=>create index t_k on tbl_a using btree (k);
CREATE INDEX
```
Os planos a seguir são considerados iguais porque um único método de varredura está sendo usado para analisar `tbl_a`, independentemente do número de partições que a consulta procura.
```
postgres=>explain (hashes true, costs false) select j, k from tbl_a where i between 990 and 999 and j < 9910 and k > 50;
QUERY PLAN
-------------------------------------------------------------------
Seq Scan on tbl_a1 tbl_a
Filter: ((i >= 990) AND (i <= 999) AND (j < 9910) AND (k > 50))
SQL Hash: 1553185667, Plan Hash: -694232056
(3 rows)
```
```
postgres=>explain (hashes true, costs false) select j, k from tbl_a where i between 990 and 1100 and j < 9910 and k > 50;
QUERY PLAN
-------------------------------------------------------------------
Append
-> Seq Scan on tbl_a1 tbl_a_1
Filter: ((i >= 990) AND (i <= 1100) AND (j < 9910) AND (k > 50))
-> Seq Scan on tbl_a2 tbl_a_2
Filter: ((i >= 990) AND (i <= 1100) AND (j < 9910) AND (k > 50))
SQL Hash: 1553185667, Plan Hash: -694232056
(6 rows)
```
```
postgres=>explain (hashes true, costs false) select j, k from tbl_a where i between 990 and 2100 and j < 9910 and k > 50;
QUERY PLAN
--------------------------------------------------------------------------
Append
-> Seq Scan on tbl_a1 tbl_a_1
Filter: ((i >= 990) AND (i <= 2100) AND (j < 9910) AND (k > 50))
-> Seq Scan on tbl_a2 tbl_a_2
Filter: ((i >= 990) AND (i <= 2100) AND (j < 9910) AND (k > 50))
-> Seq Scan on tbl_a3 tbl_a_3
Filter: ((i >= 990) AND (i <= 2100) AND (j < 9910) AND (k > 50))
SQL Hash: 1553185667, Plan Hash: -694232056
(8 rows)
```
Os três planos a seguir também são considerados iguais porque, no nível pai, os métodos de acesso, os nomes de índice sem dígitos e os nomes de partição sem dígitos são `SeqScan tbl_a`, `IndexScan (i_idx) tbl_a`.
```
postgres=>explain (hashes true, costs false) select j, k from tbl_a where i between 990 and 1100 and j < 9910 and k > 50;
QUERY PLAN
--------------------------------------------------------------------------
Append
-> Seq Scan on tbl_a1 tbl_a_1
Filter: ((i >= 990) AND (i <= 1100) AND (j < 9910) AND (k > 50))
-> Index Scan using tbl_a2_i_idx on tbl_a2 tbl_a_2
Index Cond: ((i >= 990) AND (i <= 1100))
Filter: ((j < 9910) AND (k > 50))
SQL Hash: 1553185667, Plan Hash: -993736942
(7 rows)
```
```
postgres=>explain (hashes true, costs false) select j, k from tbl_a where i between 990 and 2100 and j < 9910 and k > 50;
QUERY PLAN
--------------------------------------------------------------------------
Append
-> Index Scan using tbl_a1_i_idx on tbl_a1 tbl_a_1
Index Cond: ((i >= 990) AND (i <= 2100))
Filter: ((j < 9910) AND (k > 50))
-> Seq Scan on tbl_a2 tbl_a_2
Filter: ((i >= 990) AND (i <= 2100) AND (j < 9910) AND (k > 50))
-> Index Scan using tbl_a3_i_idx on tbl_a3 tbl_a_3
Index Cond: ((i >= 990) AND (i <= 2100))
Filter: ((j < 9910) AND (k > 50))
SQL Hash: 1553185667, Plan Hash: -993736942
(10 rows)
```
```
postgres=>explain (hashes true, costs false) select j, k from tbl_a where i between 990 and 3100 and j < 9910 and k > 50;
QUERY PLAN
--------------------------------------------------------------------------
Append
-> Seq Scan on tbl_a1 tbl_a_1
Filter: ((i >= 990) AND (i <= 3100) AND (j < 9910) AND (k > 50))
-> Seq Scan on tbl_a2 tbl_a_2
Filter: ((i >= 990) AND (i <= 3100) AND (j < 9910) AND (k > 50))
-> Seq Scan on tbl_a3 tbl_a_3
Filter: ((i >= 990) AND (i <= 3100) AND (j < 9910) AND (k > 50))
-> Index Scan using tbl_a4_i_idx on tbl_a4 tbl_a_4
Index Cond: ((i >= 990) AND (i <= 3100))
Filter: ((j < 9910) AND (k > 50))
SQL Hash: 1553185667, Plan Hash: -993736942
(11 rows)
```
Independentemente da diferença de ordem e número de ocorrências nas partições filho, os métodos de acesso, os nomes de índice sem dígitos e os nomes de partição sem dígitos são constantes no nível pai de cada um dos planos acima.
No entanto, os planos seriam considerados diferentes se alguma das condições a seguir fosse atendida:
+ Algum método de acesso adicional é usado no plano.
```
postgres=>explain (hashes true, costs false) select j, k from tbl_a where i between 990 and 2100 and j < 9910 and k > 50;
QUERY PLAN
--------------------------------------------------------------------------
Append
-> Seq Scan on tbl_a1 tbl_a_1
Filter: ((i >= 990) AND (i <= 2100) AND (j < 9910) AND (k > 50))
-> Seq Scan on tbl_a2 tbl_a_2
Filter: ((i >= 990) AND (i <= 2100) AND (j < 9910) AND (k > 50))
-> Bitmap Heap Scan on tbl_a3 tbl_a_3
Recheck Cond: ((i >= 990) AND (i <= 2100))
Filter: ((j < 9910) AND (k > 50))
-> Bitmap Index Scan on tbl_a3_i_idx
Index Cond: ((i >= 990) AND (i <= 2100))
SQL Hash: 1553185667, Plan Hash: 1134525070
(11 rows)
```
+ Um dos métodos de acesso do plano não é mais usado.
```
postgres=>explain (hashes true, costs false) select j, k from tbl_a where i between 990 and 1100 and j < 9910 and k > 50;
QUERY PLAN
--------------------------------------------------------------------------
Append
-> Seq Scan on tbl_a1 tbl_a_1
Filter: ((i >= 990) AND (i <= 1100) AND (j < 9910) AND (k > 50))
-> Seq Scan on tbl_a2 tbl_a_2
Filter: ((i >= 990) AND (i <= 1100) AND (j < 9910) AND (k > 50))
SQL Hash: 1553185667, Plan Hash: -694232056
(6 rows)
```
+ O índice associado a um método de indexação é alterado.
```
postgres=>explain (hashes true, costs false) select j, k from tbl_a where i between 990 and 1100 and j < 9910 and k > 50;
QUERY PLAN
--------------------------------------------------------------------------
Append
-> Seq Scan on tbl_a1 tbl_a_1
Filter: ((i >= 990) AND (i <= 1100) AND (j < 9910) AND (k > 50))
-> Index Scan using tbl_a2_j_idx on tbl_a2 tbl_a_2
Index Cond: (j < 9910)
Filter: ((i >= 990) AND (i <= 1100) AND (k > 50))
SQL Hash: 1553185667, Plan Hash: -993343726
(7 rows)
```
## Aplicar um plano de particionamento de tabelas
Os planos aprovados para tabelas particionadas são aplicados com correspondência posicional. Os planos não são específicos para as partições e podem ser aplicados em partições diferentes dos planos referenciados na consulta original. Os planos também podem ser aplicados para consultas que acessam um número diferente de partições em comparação com o esquema original aprovado.
Por exemplo, se o esquema aprovado for para o seguinte plano:
```
postgres=>explain (hashes true, costs false) select j, k from tbl_a where i between 990 and 2100 and j < 9910 and k > 50;
QUERY PLAN
--------------------------------------------------------------------------
Append
-> Index Scan using tbl_a1_i_idx on tbl_a1 tbl_a_1
Index Cond: ((i >= 990) AND (i <= 2100))
Filter: ((j < 9910) AND (k > 50))
-> Seq Scan on tbl_a2 tbl_a_2
Filter: ((i >= 990) AND (i <= 2100) AND (j < 9910) AND (k > 50))
-> Index Scan using tbl_a3_i_idx on tbl_a3 tbl_a_3
Index Cond: ((i >= 990) AND (i <= 2100))
Filter: ((j < 9910) AND (k > 50))
SQL Hash: 1553185667, Plan Hash: -993736942
(10 rows)
```
Depois, esse plano também pode ser aplicado em consultas SQL que fazem referência a duas, quatro ou mais partições. Os planos que poderiam surgir desses cenários para acessar duas e quatro partições são:
```
postgres=>explain (hashes true, costs false) select j, k from tbl_a where i between 990 and 1100 and j < 9910 and k > 50;
QUERY PLAN
----------------------------------------------------------------------------------
Append
-> Index Scan using tbl_a1_i_idx on tbl_a1 tbl_a_1
Index Cond: ((i >= 990) AND (i <= 1100))
Filter: ((j < 9910) AND (k > 50))
-> Seq Scan on tbl_a2 tbl_a_2
Filter: ((i >= 990) AND (i <= 1100) AND (j < 9910) AND (k > 50))
Note: An Approved plan was used instead of the minimum cost plan.
SQL Hash: 1553185667, Plan Hash: -993736942, Minimum Cost Plan Hash: -1873216041
(8 rows)
```
```
postgres=>explain (hashes true, costs false) select j, k from tbl_a where i between 990 and 3100 and j < 9910 and k > 50;
QUERY PLAN
--------------------------------------------------------------------------
Append
-> Index Scan using tbl_a1_i_idx on tbl_a1 tbl_a_1
Index Cond: ((i >= 990) AND (i <= 3100))
Filter: ((j < 9910) AND (k > 50))
-> Seq Scan on tbl_a2 tbl_a_2
Filter: ((i >= 990) AND (i <= 3100) AND (j < 9910) AND (k > 50))
-> Index Scan using tbl_a3_i_idx on tbl_a3 tbl_a_3
Index Cond: ((i >= 990) AND (i <= 3100))
Filter: ((j < 9910) AND (k > 50))
-> Seq Scan on tbl_a4 tbl_a_4
Filter: ((i >= 990) AND (i <= 3100) AND (j < 9910) AND (k > 50))
Note: An Approved plan was used instead of the minimum cost plan.
SQL Hash: 1553185667, Plan Hash: -993736942, Minimum Cost Plan Hash: -1873216041
(12 rows)
```
```
postgres=>explain (hashes true, costs false) select j, k from tbl_a where i between 990 and 3100 and j < 9910 and k > 50;
QUERY PLAN
----------------------------------------------------------------------------------
Append
-> Index Scan using tbl_a1_i_idx on tbl_a1 tbl_a_1
Index Cond: ((i >= 990) AND (i <= 3100))
Filter: ((j < 9910) AND (k > 50))
-> Seq Scan on tbl_a2 tbl_a_2
Filter: ((i >= 990) AND (i <= 3100) AND (j < 9910) AND (k > 50))
-> Index Scan using tbl_a3_i_idx on tbl_a3 tbl_a_3
Index Cond: ((i >= 990) AND (i <= 3100))
Filter: ((j < 9910) AND (k > 50))
-> Index Scan using tbl_a4_i_idx on tbl_a4 tbl_a_4
Index Cond: ((i >= 990) AND (i <= 3100))
Filter: ((j < 9910) AND (k > 50))
Note: An Approved plan was used instead of the minimum cost plan.
SQL Hash: 1553185667, Plan Hash: -993736942, Minimum Cost Plan Hash: -1873216041
(14 rows)
```
Considere outro plano aprovado com métodos de acesso diferentes para cada partição:
```
postgres=>explain (hashes true, costs false) select j, k from tbl_a where i between 990 and 2100 and j < 9910 and k > 50;
QUERY PLAN
--------------------------------------------------------------------------
Append
-> Index Scan using tbl_a1_i_idx on tbl_a1 tbl_a_1
Index Cond: ((i >= 990) AND (i <= 2100))
Filter: ((j < 9910) AND (k > 50))
-> Seq Scan on tbl_a2 tbl_a_2
Filter: ((i >= 990) AND (i <= 2100) AND (j < 9910) AND (k > 50))
-> Bitmap Heap Scan on tbl_a3 tbl_a_3
Recheck Cond: ((i >= 990) AND (i <= 2100))
Filter: ((j < 9910) AND (k > 50))
-> Bitmap Index Scan on tbl_a3_i_idx
Index Cond: ((i >= 990) AND (i <= 2100))
SQL Hash: 1553185667, Plan Hash: 2032136998
(12 rows)
```
Nesse caso, qualquer plano que leia de duas partições não seria aplicado. A menos que todas as combinações (método de acesso, nome de índice) do plano aprovado sejam utilizáveis, o plano não pode ser aplicado. Por exemplo, os planos a seguir têm hashes de plano diferentes e o plano aprovado não pode ser aplicado nesses casos:
```
postgres=>explain (hashes true, costs false) select j, k from tbl_a where i between 990 and 1900 and j < 9910 and k > 50;
QUERY PLAN
-------------------------------------------------------------------------
Append
-> Bitmap Heap Scan on tbl_a1 tbl_a_1
Recheck Cond: ((i >= 990) AND (i <= 1900))
Filter: ((j < 9910) AND (k > 50))
-> Bitmap Index Scan on tbl_a1_i_idx
Index Cond: ((i >= 990) AND (i <= 1900))
-> Bitmap Heap Scan on tbl_a2 tbl_a_2
Recheck Cond: ((i >= 990) AND (i <= 1900))
Filter: ((j < 9910) AND (k > 50))
-> Bitmap Index Scan on tbl_a2_i_idx
Index Cond: ((i >= 990) AND (i <= 1900))
Note: This is not an Approved plan. No usable Approved plan was found.
SQL Hash: 1553185667, Plan Hash: -568647260
(13 rows)
```
```
postgres=>explain (hashes true, costs false) select j, k from tbl_a where i between 990 and 1900 and j < 9910 and k > 50;
QUERY PLAN
--------------------------------------------------------------------------
Append
-> Index Scan using tbl_a1_i_idx on tbl_a1 tbl_a_1
Index Cond: ((i >= 990) AND (i <= 1900))
Filter: ((j < 9910) AND (k > 50))
-> Seq Scan on tbl_a2 tbl_a_2
Filter: ((i >= 990) AND (i <= 1900) AND (j < 9910) AND (k > 50))
Note: This is not an Approved plan. No usable Approved plan was found.
SQL Hash: 1553185667, Plan Hash: -496793743
(8 rows)
```
## Convenção de nomenclatura
Para que o QPM aplique um plano com tabelas particionadas declarativas, é necessário seguir regras de nomenclatura específicas para tabelas principais, partições de tabelas e índices:
+ **Nomes de tabelas principais**: esses nomes devem ser diferenciados por caracteres alfabéticos ou especiais, e não apenas por dígitos. Por exemplo, tA, tB e tC são nomes aceitáveis para tabelas pais distintas, enquanto t1, t2 e t3 não são.
+ **Nomes de tabelas de partição individuais**: partições da mesma tabela principal devem diferir umas das outras somente por dígitos. Por exemplo, nomes de partição aceitáveis para tA podem ser tA1 e tA2, t1A e t2A, ou até mesmo vários dígitos.
Quaisquer outras diferenças (letras, caracteres especiais) não garantirão a aplicação do plano.
+ **Nomes dos índices**: na hierarquia das tabelas de partições, todos os índices deverão ter nomes exclusivos. Isso significa que as partes não numéricas dos nomes devem ser diferentes. Por exemplo, se você tiver uma tabela particionada denominada `tA` com um índice chamado `tA_col1_idx1`, não poderá ter outro índice denominado `tA_col1_idx2`. No entanto, é possível ter um índice denominado `tA_a_col1_idx2` porque a parte não numérica do nome é exclusiva. Essa regra aplica-se aos índices criados na tabela principal e nas tabelas de partição individuais.
O não cumprimento das convenções de nomenclatura acima pode resultar na falha na aplicação dos planos aprovados. O exemplo a seguir ilustra essa falha de aplicação:
```
postgres=>create table t1(i int, j int, k int, l int, m int) partition by range(i);
CREATE TABLE
postgres=>create table t1a partition of t1 for values from (0) to (1000);
CREATE TABLE
postgres=>create table t1b partition of t1 for values from (1001) to (2000);
CREATE TABLE
postgres=>SET apg_plan_mgmt.capture_plan_baselines TO 'manual';
SET
postgres=>explain (hashes true, costs false) select count(*) from t1 where i > 0;
QUERY PLAN
--------------------------------------------------------------------------
Aggregate
-> Append
-> Seq Scan on t1a t1_1
Filter: (i > 0)
-> Seq Scan on t1b t1_2
Filter: (i > 0)
SQL Hash: -1720232281, Plan Hash: -1010664377
(7 rows)
```
```
postgres=>SET apg_plan_mgmt.use_plan_baselines TO 'on';
SET
postgres=>explain (hashes true, costs false) select count(*) from t1 where i > 1000;
QUERY PLAN
-------------------------------------------------------------------------
Aggregate
-> Seq Scan on t1b t1
Filter: (i > 1000)
Note: This is not an Approved plan. No usable Approved plan was found.
SQL Hash: -1720232281, Plan Hash: 335531806
(5 rows)
```
Embora os dois planos pareçam idênticos, os valores `Plan Hash` são diferentes devido aos nomes das tabelas secundárias. Os nomes das tabelas variam de acordo com caracteres alfa, em vez de apenas dígitos, o que ocasiona uma falha de imposição.