Pular para o conteúdo principal

VillageSQL is a drop-in replacement for MySQL with extensions.

All examples on this page work on VillageSQL. Install Now →
As extensões do VillageSQL são bibliotecas compartilhadas que o servidor carrega em tempo de execução. O VEF SDK fornece wrappers C++ tipados para que você possa escrever funções de extensão sem tocar em FFI bruto. Este guia percorre a construção de uma extensão mínima do zero.

Quando Escolher C++

C++ é a escolha certa quando:
  • Sua equipe já tem uma base de código em C++ e quer manter a extensão na mesma linguagem
  • Você precisa de tipos personalizados com layouts binários precisos (o type builder em C++ é a API mais completa)
  • Você está trabalhando com bibliotecas C++ existentes que quer expor como funções SQL
Se você prefere Rust e não tem requisitos de C++, consulte Escrevendo Extensões em Rust.

Pré-requisitos

Antes de escrever o código da extensão, você precisa de um build do VillageSQL — as extensões são vinculadas aos headers do SDK e à árvore de build do servidor. Você também precisa de:
  • Compilador C++17 — GCC 8+, Clang 8+ ou MSVC 2019+
  • CMake 3.18+ — o template de extensão usa CMake
Siga primeiro o guia Compilar a partir do Código-fonte se você ainda não compilou o servidor.

Configuração do CMake

A forma mais rápida de começar é com o vsql-extension-template. Faça um fork ou clone-o:
O CMakeLists.txt do template cuida da configuração de build do VEF para você — copie o template e adapte-o em vez de escrever o CMake do zero. Configure o diretório de build com -DVillageSQL_BUILD_DIR:
-DVillageSQL_BUILD_DIR informa ao CMake onde fica o seu build do VillageSQL para que ele encontre os headers do SDK. Isso produz um arquivo .veb na saída do build. Consulte Criando Extensões e o vsql-extension-template para a configuração completa do CMake.

Uma VDF Mínima em C++

Inclua o header do VEF SDK e use a API de builder para registrar a sua função. Aqui está uma extensão completa que implementa uma função de inversão de string:
Alguns pontos a observar:
  • Inclua <villagesql/vsql.h>, não <villagesql/extension.h> (esse é o header antigo da V1)
  • Os wrappers de argumento tipados (StringArg, IntArg, RealArg) verificam nulos e expõem valores tipados — sem aritmética de pointer bruta
  • out.set_null(), out.warning(msg) e out.error(msg) são os três retornos que não são de sucesso
  • VEF_GENERATE_ENTRY_POINTS recebe um builder make_extension(), não uma struct bruta
Para funções que retornam inteiros ou reais:
Para declarar uma função como determinística — as mesmas entradas sempre produzem a mesma saída — adicione .deterministic() à cadeia do builder:
Funções determinísticas podem ser usadas em colunas geradas e índices funcionais. Adicione .deterministic() apenas quando isso for realmente verdade.

Compilando

Após a etapa de configuração do cmake da seção de configuração do CMake acima, compile e instale:
make install copia o arquivo .veb para o diretório de extensões do seu VillageSQL.

Instalando e Testando

Conecte-se ao VillageSQL e instale a extensão:
Verifique se ela foi carregada:
Chame a sua função:
Para testes automatizados, escreva uma suíte do MySQL Test Framework em mysql-test/t/:
Gere os resultados esperados e execute:

Veja também