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():
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:
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 testevsql_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 objetoMysqlServices 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:
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):
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:
<cstddef> primeiro, como fazem os exemplos desta página.
Chamando um Serviço
Uma referência de serviço expõe o seu própriovalid(), e -> encaminha para o
serviço. Use . para a referência e -> para o serviço:
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. OINSTALL 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:
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 devsql_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: