> ## Documentation Index
> Fetch the complete documentation index at: https://villagesql.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Cobertura do VEF Comparada ao PostgreSQL

> Esta página é uma comparação entre o VillageSQL Extension Framework e o framework de extensões do PostgreSQL, mostrando quais interfaces e hooks o VEF oferece hoje e onde o trabalho restante é acompanhado.

O VillageSQL Extension Framework (VEF) dá a uma extensão acesso ao
funcionamento interno do banco de dados de uma forma definida. O PostgreSQL tem
o framework de extensões mais maduro de todos os bancos de dados de código
aberto, então esta página o usa como ponto de referência para lhe dar uma noção
das capabilities atuais e planejadas do VEF.

Você deve ler esta página como um retrato de um momento, e não como o estado
final. O VEF muda a cada versão. Igualar exatamente as capabilities de hook do
PostgreSQL não é o objetivo. MySQL e PostgreSQL são bancos de dados diferentes e
as necessidades de seus usuários muitas vezes também são diferentes.

## Capabilities específicas do VillageSQL

Parte do que o VEF oferece não tem nada com que se comparar nas tabelas abaixo,
seja porque o MySQL é construído de forma diferente, seja porque os autores de
extensões do VillageSQL precisavam de algo que o PostgreSQL não dá às suas
próprias extensões.

* **Acesso ao keyring** — `vsql::preview::keyring` permite que uma extensão leia
  segredos do keyring do servidor.
* **Armazenamento de páginas do InnoDB** — `vsql::preview::storage` permite que uma
  extensão crie segmentos do InnoDB e leia e escreva suas páginas através do
  buffer pool, com redo logging.
* **Handlers de protocolo alternativos** —
  [#299](https://github.com/villagesql/villagesql-server/issues/299) permitiria
  que uma extensão atendesse clientes por algo diferente do protocolo de rede do
  MySQL.

Duas outras capabilities estão planejadas por causa de como o MySQL é construído. A
observação de escrita e flush do log binário
([#297](https://github.com/villagesql/villagesql-server/issues/297)) e a
observação de canais de replicação
([#341](https://github.com/villagesql/villagesql-server/issues/341)) leem tanto o
log binário do MySQL quanto seus canais de replicação multi-origem. O PostgreSQL
cobre terreno comparável através da decodificação lógica no WAL e de sua
maquinaria de assinaturas, que é um design diferente com propósito semelhante.

## Como ler as tabelas

| Status | Significado |
| - | - |
| **Disponível** | Você pode fazer isso em uma extensão hoje. A linha nomeia a capability ou a função do SDK que fornece isso. |
| **Parcial** | Parte disso funciona hoje. A linha, ou a nota abaixo da tabela, diz o que está faltando. |
| **Em andamento** | Parte do trabalho já foi entregue. As issues vinculadas carregam o restante. |
| **Planejado** | Ainda não disponível. A issue vinculada acompanha o trabalho. |

Toda linha que não está marcada como **Disponível** vincula a issue do GitHub
onde esse trabalho é acompanhado e discutido, na linha ou na nota abaixo da tabela.

Qualquer coisa marcada como **Disponível** através de uma capability Preview
requer `vsql_allow_preview_extensions = ON` — consulte
[Capabilities Preview](https://villagesql.com/docs/pt-BR/extensions/build/preview-capabilities.md). `vsql::preview::auth` e
`vsql::preview::statement_event` também estão disponíveis apenas para uma extensão compilada contra a ABI de desenvolvimento (`-DVSQL_USE_DEV_ABI=ON`).

## C++ e Rust

Você pode escrever uma extensão do VillageSQL em C++ ou em Rust. O VEF é a
capability do lado do servidor e cada SDK é uma ligação sobre ele; as ligações
Rust são mais novas, então algumas capabilities são alcançáveis apenas a partir
do C++ por enquanto.

| Capability | SDK C++ | SDK Rust |
| - | - | - |
| Funções escalares (VDFs) | Sim | Sim |
| Tipos personalizados | Sim | Sim |
| Variáveis de sistema e de status | Sim | Sim |
| Workers em segundo plano | Sim | Sim |
| Acesso ao keyring | Sim | Sim |
| Funções de agregação | Sim | Sim |
| Callbacks de carregamento e descarregamento | Sim | Ainda não — [rust-sdk#13](https://github.com/villagesql/vsql-rust-sdk/issues/13) |
| Executar SQL a partir de uma extensão | Sim | Sim |
| Eventos de conclusão de instrução | Sim (somente ABI de desenvolvimento) | Ainda não — [rust-sdk#37](https://github.com/villagesql/vsql-rust-sdk/issues/37) |
| Métodos de autenticação | Sim (somente ABI de desenvolvimento) | Ainda não — [rust-sdk#37](https://github.com/villagesql/vsql-rust-sdk/issues/37) |
| Armazenamento de páginas do InnoDB | Sim | Ainda não — [rust-sdk#37](https://github.com/villagesql/vsql-rust-sdk/issues/37) |

## Interfaces plugáveis

São essas interfaces, e não os hooks mais adiante, que servem de base para as
extensões mais conhecidas do PostgreSQL. Elas também são a parte do framework
que o VEF cobre de forma mais completa, então comece por aqui.

| Interface do PostgreSQL | O que ela faz | VillageSQL |
| - | - | - |
| `_PG_init`, `_PG_fini` | Executa a configuração quando o módulo carrega, e a finalização quando ele descarrega | **Disponível** — `on_init()` e `on_deinit()` no builder da extensão, nos headers da ABI de desenvolvimento (`-DVSQL_USE_DEV_ABI=ON`) |
| Tipos de dados e operadores personalizados | Registra um novo tipo base com seu próprio armazenamento e comportamento de comparação | **Disponível** — consulte [Tipos Personalizados](https://villagesql.com/docs/pt-BR/sdk/cpp/custom-types.md) |
| Funções de agregação | Registra uma agregação definida pelo usuário | **Disponível** — `make_aggregate_func`, consulte [Guia de Desenvolvimento](https://villagesql.com/docs/pt-BR/sdk/cpp/development.md) |
| Variáveis de configuração personalizadas | Define configurações que o operador pode alterar em tempo de execução, e contadores que ele pode ler | **Disponível** — `vsql::sys_var` para configurações, `vsql::status_var` para contadores |
| Workers em segundo plano | Executa um processo de vida longa dentro do servidor, com acesso ao banco de dados | **Disponível** — `vsql::preview::thread_worker` |
| SPI (executar SQL de dentro do servidor) | Executa SQL a partir do código da extensão | **Parcial** — `vsql::preview::sql_query`, com os limites indicados abaixo |
| Funções que retornam conjuntos | Retorna um conjunto de resultados a partir de uma função | Planejado — [#549](https://github.com/villagesql/villagesql-server/issues/549) |
| Procedimentos escritos em C | Expõe uma operação como `CALL`, e não como uma função escalar | Planejado — [#596](https://github.com/villagesql/villagesql-server/issues/596) |
| Métodos de acesso a índices | Registra um tipo de índice inteiro, com construção, manutenção e busca | Em andamento — [#264](https://github.com/villagesql/villagesql-server/issues/264), [#265](https://github.com/villagesql/villagesql-server/issues/265), [#266](https://github.com/villagesql/villagesql-server/issues/266), [#268](https://github.com/villagesql/villagesql-server/issues/268) |
| Provedores de varredura personalizados | Adiciona nós definidos pela extensão ao executor | Planejado — [#276](https://github.com/villagesql/villagesql-server/issues/276) |
| Métodos de acesso a tabelas | Substitui o armazenamento de linhas, a visibilidade e o comportamento de vacuum | Planejado — [#290](https://github.com/villagesql/villagesql-server/issues/290), [#291](https://github.com/villagesql/villagesql-server/issues/291), [#292](https://github.com/villagesql/villagesql-server/issues/292) |
| Foreign data wrappers | Expõe um sistema externo como uma tabela, com pushdown de predicados e escritas | Planejado — [#277](https://github.com/villagesql/villagesql-server/issues/277), [#278](https://github.com/villagesql/villagesql-server/issues/278), [#279](https://github.com/villagesql/villagesql-server/issues/279), [#280](https://github.com/villagesql/villagesql-server/issues/280) |
| Plugins de saída de decodificação lógica | Consome um fluxo de mudanças de linhas | Planejado — [#283](https://github.com/villagesql/villagesql-server/issues/283), [#284](https://github.com/villagesql/villagesql-server/issues/284), [#285](https://github.com/villagesql/villagesql-server/issues/285) |
| Visões de sistema para o estado da extensão | Publica o estado da extensão como uma tabela consultável | Planejado — [#271](https://github.com/villagesql/villagesql-server/issues/271) |
| Linguagens procedurais | Adiciona um runtime de linguagem para rotinas armazenadas | Planejado — [#342](https://github.com/villagesql/villagesql-server/issues/342) |

`on_init()` e `on_deinit()` são executados com as capabilities declaradas pela
extensão ativas: `on_init()` depois que o servidor as populou, e `on_deinit()` antes
de ele as despopular, de modo que um hook pode ler uma variável de sistema registrada. Eles também
servem para configuração local, como escolher pointers de função específicos da CPU.

`vsql::preview::sql_query` tem três limites que afetam qualquer extensão
construída em torno de SPI. As instruções não aceitam parâmetros de vínculo,
então os valores precisam ser escapados manualmente
([#627](https://github.com/villagesql/villagesql-server/issues/627)). Uma
extensão recebe uma única sessão em vez de sessões concorrentes
([#626](https://github.com/villagesql/villagesql-server/issues/626)). E ela não
pode ser chamada de dentro de uma VDF
([#597](https://github.com/villagesql/villagesql-server/issues/597)).

## Variáveis de hook

Um hook é um ponto em que o servidor entrega o controle a uma extensão no meio
de uma instrução, permitindo que ela leia ou altere o que o servidor está prestes
a fazer. O PostgreSQL declara um conjunto fixo deles como pointers de função
globais; as tabelas abaixo cobrem todos eles, agrupados pela etapa do
processamento da consulta em que cada um dispara.

### Análise sintática e DDL

| Hook do PostgreSQL | O que ele faz | VillageSQL |
| - | - | - |
| `post_parse_analyze_hook` | Inspeciona ou reescreve uma instrução após a análise sintática | Planejado — [#701](https://github.com/villagesql/villagesql-server/issues/701) |
| `ProcessUtility_hook` | Intercepta, bloqueia ou redireciona DDL e outras instruções utilitárias antes que elas sejam executadas | Planejado — [#272](https://github.com/villagesql/villagesql-server/issues/272) |
| `object_access_hook`, `object_access_hook_str` | Recebe uma notificação quando um objeto do catálogo é criado, alterado, removido ou acessado | Planejado — [#270](https://github.com/villagesql/villagesql-server/issues/270) |

### Planejador

| Hook do PostgreSQL | O que ele faz | VillageSQL |
| - | - | - |
| `planner_hook` | Envolve ou substitui o planejador para uma instrução | Planejado — [#275](https://github.com/villagesql/villagesql-server/issues/275) |
| `set_rel_pathlist_hook` | Adiciona ou remove caminhos de varredura candidatos para uma tabela | Planejado — [#275](https://github.com/villagesql/villagesql-server/issues/275) |
| `set_join_pathlist_hook` | Adiciona ou remove caminhos de junção candidatos | Planejado — [#275](https://github.com/villagesql/villagesql-server/issues/275) |
| `join_search_hook` | Substitui a própria busca de ordem de junção | Planejado — [#275](https://github.com/villagesql/villagesql-server/issues/275) |
| `create_upper_paths_hook` | Adiciona caminhos para etapas pós-varredura, como agrupamento e ordenação | Planejado — [#275](https://github.com/villagesql/villagesql-server/issues/275) |
| `get_relation_info_hook` | Ajusta os metadados de relação e de índice que o planejador enxerga | Planejado — [#268](https://github.com/villagesql/villagesql-server/issues/268) |
| `get_relation_stats_hook`, `get_index_stats_hook` | Fornece estatísticas para uma coluna ou índice no lugar das do catálogo | Planejado — [#274](https://github.com/villagesql/villagesql-server/issues/274) |
| `get_attavgwidth_hook` | Fornece uma largura média de coluna para estimativa de custo | Planejado — [#274](https://github.com/villagesql/villagesql-server/issues/274) |

### Executor

| Hook do PostgreSQL | O que ele faz | VillageSQL |
| - | - | - |
| `ExecutorStart_hook` | Executa antes de uma consulta começar a ser executada | Planejado — [#702](https://github.com/villagesql/villagesql-server/issues/702) |
| `ExecutorRun_hook` | Envolve a produção de linhas, para mascaramento, transformação ou contabilização por linha | Planejado — [#289](https://github.com/villagesql/villagesql-server/issues/289) |
| `ExecutorFinish_hook` | Executa depois da última linha, antes da finalização | Planejado — [#287](https://github.com/villagesql/villagesql-server/issues/287) |
| `ExecutorEnd_hook` | Observa uma instrução concluída e suas estatísticas de execução | **Disponível** — `vsql::preview::statement_event`, fase pós-execução (somente ABI de desenvolvimento) |
| `ExecutorCheckPerms_hook` | Aprova ou rejeita as permissões de tabela e de coluna de que uma instrução precisa | Planejado — [#314](https://github.com/villagesql/villagesql-server/issues/314) |

As extensões do PostgreSQL que precisam de detalhe por operador o obtêm
envolvendo o `ExecutorRun_hook` no nível do nó. No VEF isso é um trabalho
separado, acompanhado em
[#340](https://github.com/villagesql/villagesql-server/issues/340).

### EXPLAIN

| Hook do PostgreSQL | O que ele faz | VillageSQL |
| - | - | - |
| `ExplainOneQuery_hook` | Substitui ou estende a forma como uma instrução é explicada | Planejado — [#317](https://github.com/villagesql/villagesql-server/issues/317) |
| `explain_per_plan_hook` | Adiciona saída da extensão uma vez por plano explicado | Planejado — [#317](https://github.com/villagesql/villagesql-server/issues/317) |
| `explain_per_node_hook` | Adiciona saída da extensão para cada nó do plano | Planejado — [#317](https://github.com/villagesql/villagesql-server/issues/317) |
| `explain_get_index_name_hook` | Sobrescreve o nome do índice mostrado na saída | Planejado — [#317](https://github.com/villagesql/villagesql-server/issues/317) |
| `explain_validate_options_hook` | Aceita opções de `EXPLAIN` definidas pela extensão | Planejado — [#317](https://github.com/villagesql/villagesql-server/issues/317) |

### Autenticação e segurança

| Hook do PostgreSQL | O que ele faz | VillageSQL |
| - | - | - |
| `ClientAuthentication_hook` | Participa da autenticação e observa seu resultado | **Parcial** — veja abaixo; a capability de autenticação é somente da ABI de desenvolvimento |
| `check_password_hook` | Impõe uma política de senha quando uma senha é definida | Planejado — [#456](https://github.com/villagesql/villagesql-server/issues/456) |
| `ldap_password_hook` | Substitui o bind LDAP usado pelo método de autenticação `ldap` | **Disponível** — implemente o próprio método com `vsql::preview::auth` (somente ABI de desenvolvimento) |
| `openssl_tls_init_hook` | Ajusta o contexto TLS do servidor na inicialização | Planejado — [#458](https://github.com/villagesql/villagesql-server/issues/458) |
| `row_security_policy_hook_permissive`, `row_security_policy_hook_restrictive` | Adiciona predicados de filtro de linha a uma consulta com base na sessão | Planejado — [#315](https://github.com/villagesql/villagesql-server/issues/315) |

As extensões do PostgreSQL usam o `ClientAuthentication_hook` para dois
trabalhos diferentes, e o VEF cobre um deles. Uma extensão pode implementar um
método de autenticação próprio através da capability `vsql::preview::auth`, que é
a base sobre a qual o `vsql-oauth2` é construído. Ela ainda não consegue observar
o resultado de uma autenticação que não tratou, que é como funcionam o
`auth_delay` e os rastreadores de login malsucedido do PostgreSQL. Essa parte é a
[#464](https://github.com/villagesql/villagesql-server/issues/464).

O PostgreSQL mapeia identidades externas para contas de banco de dados através
do `pg_ident.conf`, e não de um hook. O VEF cobre isso através da mesma
capability `vsql::preview::auth`: `set_active_roles()` permite que um plugin de
autenticação prepare papéis para a sessão assim que ele resolve uma identidade
externa, e `roles_mode()` registra um callback, consultado novamente a cada login, que
decide se o servidor apenas ativa os papéis preparados, também os concede,
ou sincroniza as concessões da conta para corresponder (um `DEFAULT ROLE`
fixado pelo operador sobrevive a uma sincronização). Ambos são declarados em
`villagesql/sdk/include/villagesql/preview/auth.h`.

### Registro em log

| Hook do PostgreSQL | O que ele faz | VillageSQL |
| - | - | - |
| `emit_log_hook` | Vê cada mensagem de log antes que ela seja escrita, e a filtra ou redireciona | Planejado — [#316](https://github.com/villagesql/villagesql-server/issues/316) |

### Inicialização e memória compartilhada

| Hook do PostgreSQL | O que ele faz | VillageSQL |
| - | - | - |
| `shmem_request_hook` | Solicita memória compartilhada durante a inicialização | Planejado — [#282](https://github.com/villagesql/villagesql-server/issues/282) |
| `shmem_startup_hook` | Inicializa essa memória compartilhada assim que ela existe | Planejado — [#282](https://github.com/villagesql/villagesql-server/issues/282) |

### Gerenciador de funções

| Hook do PostgreSQL | O que ele faz | VillageSQL |
| - | - | - |
| `fmgr_hook`, `needs_fmgr_hook` | Executa código em torno de cada chamada de função, para auditoria ou sandbox | Planejado — [#287](https://github.com/villagesql/villagesql-server/issues/287) |

## Conte para nós o que você precisa

Nós priorizamos este trabalho com base no que os autores de extensões pedem. Se
algo acima está bloqueando uma extensão que você quer construir, adicione um 👍 à
sua issue e descreva seu caso de uso em um comentário.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.