Pular para o conteúdo principal
As capabilities desta página estão em Preview: suas APIs não são estáveis, e uma extensão que declara uma delas requer vsql_allow_preview_extensions = ON para instalar. Consulte Capabilities Preview para saber como habilitar o nível Preview e registrar uma capability.

Acesso ao Keyring

A capability keyring (vsql::preview::keyring) permite que as extensões leiam e escrevam segredos armazenados no componente keyring do MySQL. As extensões a usam para coisas como chaves de API, chaves de criptografia ou outros segredos que não deveriam ficar em tabelas SQL. O nome da capability VEF_PREVIEW_KEYRING_NAME é "vsql::preview::keyring". Um componente keyring (por exemplo, component_keyring_file) deve ser carregado na inicialização do servidor por meio de um manifesto de componente e do seu arquivo de configuração, como descrito em Keyring Component Installation; INSTALL COMPONENT não o torna disponível. Sem um, as operações retornam KeyringCapability::Status::UNAVAILABLE.

Valores de Status

KeyringCapability::Status é um enum com escopo retornado por read() (dentro de ReadResult) e por write():

Declarando a Capability

Inclua o cabeçalho, declare um objeto de capability no escopo do arquivo e passe-o para .with():
O objeto g_keyring é populado pelo servidor no momento do carregamento. Os métodos read() e write() retornam Status::UNAVAILABLE em tempo de execução quando nenhum componente keyring está instalado — verifique esse status em cada chamada em vez de depender de uma verificação de disponibilidade separada.

Lendo e Escrevendo

data_id é o identificador da chave. auth_id é o usuário proprietário — passe uma string vazia (ou omita-o em read, que assume {} como padrão) para ler ou escrever chaves internas não associadas a um usuário específico. read retorna um ReadResult por valor. Vincule-o com structured bindings:
Em qualquer status diferente de Status::OK, value fica vazio. write retorna Status diretamente e armazena data sob data_id / auth_id. Com component_keyring_file, escrever uma chave existente retorna Status::ERROR.

Exemplo Completo

Esta é uma versão simplificada da extensão de teste vsql_keyring_reader, na árvore villagesql/test-extensions/ do servidor. Ela registra 2 VDFs: keyring_read e keyring_store.

Serviços do MySQL

A capability mysql_services (vsql::preview::mysql_services) permite que uma extensão consuma serviços do registro do MySQL — os mesmos serviços que um componente do MySQL consome, fornecidos por um componente instalado ou pelo núcleo do servidor. A extensão declara em um único lugar todos os serviços de que precisa; o servidor adquire cada um quando a extensão é carregada e o libera quando a extensão é descarregada. O nome da capability VEF_PREVIEW_MYSQL_SERVICES_NAME é "vsql::preview::mysql_services". Recorra a ela quando um recurso do servidor não tiver uma capability VEF própria. Os atributos de sessão e os próprios serviços de componente do keyring são alcançáveis por esse caminho. Somente o consumo é suportado: registrar a implementação da própria extensão no registro é um trabalho futuro planejado e não faz parte desta capability.

Declarando a Capability

Declare um objeto MysqlServices no escopo do arquivo, nomeie cada serviço que você consome com VSQL_REQUIRE_SERVICE e passe o objeto para .with(). Inclua o cabeçalho do próprio MySQL para cada serviço — é nesse cabeçalho que o tipo e os métodos do serviço são declarados:
VSQL_REQUIRE_SERVICE(services, name, var) declara var, a referência na qual o servidor escreve o serviço adquirido, e registra name em services. Ele declara var como static para você. O objeto MysqlServices também precisa ser static, assim como qualquer referência que você declare manualmente: o servidor escreve através deles no carregamento, e eles precisam sobreviver à extensão.

Fixando uma Implementação Específica

VSQL_REQUIRE_SERVICE usa name duas vezes — como o SERVICE_TYPE(name) do C++ e como a string que o servidor procura no registro. Sob esse nome simples, o servidor adquire a implementação padrão do serviço. Para nomear uma implementação em vez disso, use seu nome qualificado no registro — service.component, a forma que o PROVIDES_SERVICE(component, service) do MySQL gera. Isto pede o leitor de keyring do componente component_keyring_file em vez do padrão:
Um nome qualificado é adquirido da mesma maneira que um nome simples, então vale a regra de sempre: se aquela implementação exata não estiver registrada, a extensão falha ao instalar em vez de recorrer a outra.

Compilando com os Cabeçalhos do MySQL

As definições de serviço pertencem ao framework de componentes do MySQL, e não ao VEF, e o servidor não as instala. Portanto, mysql/components/services/*.h está ausente do SDK de extensões e de tudo o que é gerado por make install, o que inclui o tarball de release e a imagem Docker. Uma extensão que consome serviços é compilada contra uma árvore de código-fonte do servidor VillageSQL: As extensões de teste internas à árvore obtêm ambos a partir da flag MYSQL_HEADERS de vsql_add_test_extension(), que os repassa como MYSQL_INCLUDE_DIR e MYSQL_GENERATED_INCLUDE_DIR. Uma compilação fora da árvore define seus próprios caminhos de include. Duas falhas de compilação aparecem em um lugar diferente da linha que as causou. Omitir o cabeçalho MySQL de um serviço deixa VSQL_REQUIRE_SERVICE com um nome que não resolve para nada, então o erro aparece na macro em vez de no include ausente (clang 17):
Algumas definições de serviço usam size_t sem incluir <cstddef>, então colocar um desses cabeçalhos antes de todos os cabeçalhos villagesql falha dentro do próprio cabeçalho do MySQL:
Inclua <cstddef> primeiro, como fazem os exemplos desta página.

Chamando um Serviço

Uma referência de serviço expõe o seu próprio valid(), e -> encaminha para o serviço. Use . para a referência e -> para o serviço:
Verifique valid() antes de cada chamada com ->. -> retorna o pointer adquirido, que é nulo quando o serviço não foi adquirido. Um serviço que falha ao ser adquirido faz a instalação falhar, então, dentro de uma função em execução, um serviço requerido é válido. A verificação ainda importa, porque um ServiceRef declarado manualmente e nunca passado para require() nunca é escrito: ele compila, a extensão instala, e valid() é falso por toda a vida da extensão. O que um serviço é — seus métodos, seus parâmetros e o que eles retornam — é documentado pelo MySQL, não aqui. Para um serviço chamado NAME, leia include/mysql/components/services/NAME.h na árvore do servidor: seu bloco BEGIN_SERVICE_DEFINITION(NAME) declara cada método com a sua própria documentação. Chame-os exatamente como aquele cabeçalho especifica, incluindo a convenção do MySQL de que um retorno bool false significa sucesso e true significa falha.

Falha na Aquisição

Todo serviço declarado é adquirido quando a extensão é carregada, antes que qualquer uma de suas funções possa ser chamada, então um serviço que não está registrado faz o carregamento falhar em vez de aparecer mais tarde. O INSTALL EXTENSION falha e nomeia o serviço. vsql_mysql_services_missing_test, abaixo, é uma extensão de teste interna à árvore que requer um serviço que o registro não tem. Não é algo que você possa instalar — é como a falha foi capturada, e é o que a sua própria extensão produz se ela requerer um serviço que este servidor não fornece:
Outras duas falhas de instalação chegam a esta capability de fora dela: deixar o objeto MysqlServices fora de .with() e instalar em um servidor com vsql_allow_preview_extensions OFF. Ambas são cobertas em Padrão de Registro.

Exemplo Completo

Uma versão simplificada de vsql_mysql_services_session_test, na árvore villagesql/test-extensions/ do servidor. Ela lê o comando SQL em execução na sessão que a chamou compondo dois serviços: um devolve o THD atual, o outro lê um atributo nomeado a partir dele. Ambos são serviços do núcleo do servidor, registrados em todo servidor, então nada precisa ser instalado antes:
Instale-a e chame a função: