> ## 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 arquivos privado da extensão** — `vsql::preview::storage` dá
a uma extensão um lugar gerenciado em disco. As extensões do PostgreSQL
gerenciam seus próprios arquivos, sem uma API do lado do servidor para isso.
* **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 existem 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.
Qualquer coisa marcada como **Disponível** através de uma capability Preview
requer `vsql_allow_preview_extensions = ON` — consulte
[Capabilities Preview](/docs/pt-BR/mysql-8.4/stable/preview-capabilities).
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 | Ainda não — [rust-sdk#37](https://github.com/villagesql/vsql-rust-sdk/issues/37) |
| Eventos de conclusão de instrução | Sim | Ainda não — [rust-sdk#37](https://github.com/villagesql/vsql-rust-sdk/issues/37) |
| Métodos de autenticação | Sim | Ainda não — [rust-sdk#37](https://github.com/villagesql/vsql-rust-sdk/issues/37) |
| Armazenamento privado da extensão | 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 |
| 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 em C++](/docs/pt-BR/mysql-8.4/stable/custom-types) |
| Funções de agregação | Registra uma agregação definida pelo usuário | **Disponível** — `make_aggregate_func`, consulte [Desenvolvimento em C++](/docs/pt-BR/mysql-8.4/stable/development) |
| 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 dentro da extensão sem acesso ao
servidor, diferentemente de `_PG_init`. Eles servem para configuração local,
como escolher pointers de função específicos da CPU. A configuração que precisa
falar com o servidor pertence à etapa de população de uma capability.
`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 |
| `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 |
| `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` |
| `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 atribua papéis à sessão assim que ele resolve uma identidade
externa, e `auto_grant_roles()` registra um callback que concede papéis
automaticamente com base nas claims de um token. 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.