// ... read src, write result to dst ...
out.set_length(src.size());
}
```
Registre com `.param(COMPLEX)` e `.returns(COMPLEX)`:
```cpp theme={null}
.func(make_func<&complex_conjugate_impl>("complex_conjugate")
.returns(COMPLEX)
.param(COMPLEX)
.build())
```
Consulte o [guia de desenvolvimento](/docs/pt-BR/mysql-8.4/0.0.5/development#argument-and-result-types)
para a API completa de `CustomArg`/`CustomResult`, incluindo `CustomArgWith`
e `CustomResultWith
` para tipos parametrizados.
### Funções Determinísticas
Por padrão, VDFs são registradas como não determinísticas. Uma função não determinística é bloqueada em três contextos SQL: colunas geradas, restrições CHECK e valores padrão de expressão (`DEFAULT (expr)` em uma coluna) — usar qualquer um desses recursos com uma VDF não determinística retorna um erro. Se sua função sempre produz a mesma saída para as mesmas entradas e não tem efeitos colaterais, você pode declará-la determinística adicionando `.deterministic()` à cadeia do builder.
O otimizador pode usar essa informação para avaliar a função uma vez por instrução e reutilizar o valor entre as linhas, em vez de chamá-la por linha. Marcar incorretamente uma função não determinística como determinística pode, portanto, fazer com que o servidor retorne o mesmo resultado para entradas que deveriam produzir saídas diferentes. Adicione `.deterministic()` apenas quando sua função realmente não tiver dependência de estado externo, aleatoriedade ou tempo.
**Assinatura do builder:** `.deterministic(bool d = true)` — a forma sem argumentos assume `true` como padrão.
**Exemplo:**
```cpp theme={null}
.func(make_func<&complex_add_impl>("complex_add")
.returns(COMPLEX)
.param(COMPLEX)
.param(COMPLEX)
.deterministic()
.build())
```
Como `complex_add` é declarada determinística, ela pode ser usada em uma definição de coluna gerada:
```sql theme={null}
-- Deterministic VDFs can be used in generated columns
CREATE TABLE t (
a COMPLEX,
b COMPLEX,
result COMPLEX GENERATED ALWAYS AS (complex_add(a, b)) STORED
);
-- STORED vs VIRTUAL follows standard MySQL generated column rules
```
Tamanhos de Buffer Personalizados
Para funções que retornam dados de comprimento variável, solicite um tamanho de buffer específico:
```cpp theme={null}
make_func<&large_result_impl>("large_result")
.returns(STRING)
.param(INT)
.buffer_size(65536) // Request 64KB buffer
.build()
```
Quando você mesmo constrói o valor com `buffer()` e `set_length()`, o buffer
tem tamanho fixo de `buffer().size()` bytes — escrever além dele causa estouro de memória, então proteja-se
contra isso:
```cpp theme={null}
void large_result_impl(StringArg input, StringResult out) {
if (input.is_null()) { out.set_null(); return; }
size_t needed = calculate_output_size(input.value());
auto buf = out.buffer();
if (needed > buf.size()) {
out.error("Output exceeds buffer size");
return;
}
// Write output into buf.data()
out.set_length(actual_output_length);
}
```
Para resultados STRING, `out.set(sv)` segue um contrato de estouro no estilo snprintf: ele
copia quantos bytes couberem e informa o tamanho total do valor via `set_length`.
Quando o tamanho informado excede o buffer, o servidor aumenta o buffer de resultado e
reinvoca a função, de modo que um valor STRING maior que o buffer solicitado deixa de ser truncado.
Esse contrato se aplica no momento da linha. Um resultado STRING *materializado* (em uma
tabela temporária de GROUP BY/DISTINCT, `CREATE TABLE ... SELECT` ou UNION) ainda
é truncado na largura do argumento, a menos que a função declare
`.max_result_length(n)`, que dimensiona a coluna de resultado (em caracteres, limitada a
`VEF_MAX_RESULT_LENGTH`, 16 MiB):
```cpp theme={null}
make_func<&large_result_impl>("large_result")
.returns(STRING)
.max_result_length(65536)
.build()
```
Solicite um tamanho de buffer suficiente via `.buffer_size()` com base no tamanho máximo de saída da sua função. Dimensionar o buffer corretamente evita o custo de um ciclo de aumento-e-nova-tentativa.
Antes de implementar suas funções, revise a [Referência da API C++](/docs/pt-BR/mysql-8.4/0.0.5/extension-api-reference) para os contratos completos de VDF: verificação de null, tipos de resultado, dimensionamento de buffer e tratamento de erros.
## Passo 4: Criando Tipos Personalizados
Tipos personalizados permitem definir novos tipos de coluna — como `COMPLEX`, `UUID` ou
`VECTOR` — que funcionam com `ORDER BY`, índices e funções de agregação.
Se sua extensão registra apenas funções, pule para o Passo 5.
Consulte [Tipos Personalizados em C++](/docs/pt-BR/mysql-8.4/0.0.5/custom-types) para o passo a passo completo
da implementação. Se seu tipo recebe parâmetros (ex.: `VECTOR(1536)`),
consulte [Tipos Parametrizados](/docs/pt-BR/mysql-8.4/0.0.5/type-operations#parameterized-types).
Passo 5: Atualize a Configuração de Compilação
Edite `CMakeLists.txt` para compilar sua extensão como um arquivo VEB:
```cmake theme={null}
cmake_minimum_required(VERSION 3.18)
project(my_extension)
# Find VillageSQL Extension Framework
find_package(VillageSQLExtensionFramework QUIET)
# The framework detects build flags via 4 methods (in order):
# 1. Explicit MYSQL_INCLUDE_FLAGS/MYSQL_CXXFLAGS
# 2. VillageSQL_BUILD_DIR (reads CMakeCache.txt from VillageSQL build)
# 3. VSQL_BASE_DIR (uses mysql_config)
# 4. Default - mysql_config from PATH
# Build shared library with your source files
add_library(extension SHARED
src/extension.cc
src/my_functions.cc
)
# Create VEB archive
VEF_CREATE_VEB(
NAME my_extension
LIBRARY_TARGET extension
MANIFEST ${CMAKE_CURRENT_SOURCE_DIR}/manifest.json
)
# Install VEB to VillageSQL extensions directory
install(FILES ${VEB_OUTPUT} DESTINATION ${INSTALL_DIR})
```
**Notas de configuração:**
* `VillageSQLExtensionFramework` fornece helpers do CMake para compilar extensões
* `VEF_CREATE_VEB()` empacota sua biblioteca, manifesto e metadados em um arquivo `.veb`
* O framework detecta automaticamente as flags de compilação do MySQL/VillageSQL
* O nome do target da biblioteca é normalmente `extension` (pode ser qualquer um)
* O nome do VEB deve corresponder ao nome no seu manifest.json
* Por padrão, extensões são compiladas com os cabeçalhos da ABI estável. Defina `-DVSQL_USE_DEV_ABI=ON` para compilar com os cabeçalhos instáveis da dev ABI
***
## Passo 6: Crie um Diretório de Compilação
Crie um diretório de compilação separado:
```bash theme={null}
mkdir build
cd build
```
## Passo 7: Compile com CMake e Make
Configure e compile sua extensão:
```bash theme={null}
# Configure the build
cmake ..
# Or, if building against VillageSQL source:
cmake .. -DVillageSQL_BUILD_DIR=/path/to/villagesql/build
# Or, to build against the unstable dev ABI headers:
cmake .. -DVSQL_USE_DEV_ABI=ON
# Build the extension
make
```
Isso cria:
* Biblioteca compartilhada compilada (arquivo `.so`)
* Pacote VEB (arquivo `.veb`) - um arquivo tar contendo manifesto e biblioteca
### Verifique a Compilação
Verifique o conteúdo do seu arquivo VEB:
```bash theme={null}
make show_veb
```
Você deverá ver:
```
manifest.json
lib/myext.so
```
## Passo 8: Instale e Teste
### Opção A: Instalar no Diretório de Extensões do VillageSQL
Use o target de instalação para copiar o VEB para sua instalação do VillageSQL:
```bash theme={null}
make install
```
Isso copia o arquivo `.veb` para o diretório configurado via `VillageSQL_VEB_INSTALL_DIR`.
### Opção B: Instalação Manual
Copie o arquivo VEB manualmente:
```bash theme={null}
# Find the VEF directory
mysql -u root -p -e "SHOW VARIABLES LIKE 'veb_dir';"
# Copy the VEB file
sudo cp my-awesome-extension.veb /path/to/veb_dir/
```
### Teste Sua Extensão
1. **Conecte-se ao VillageSQL**:
```bash theme={null}
mysql -u root -p
```
2. **Instale a extensão**:
```sql theme={null}
INSTALL EXTENSION my_awesome_extension;
```
3. **Verifique a instalação**:
```sql theme={null}
SELECT * FROM INFORMATION_SCHEMA.EXTENSIONS;
```
4. **Teste suas funções**:
```sql theme={null}
SELECT my_reverse('Hello, World!');
-- Output: !dlroW ,olleH
SELECT count_vowels('VillageSQL');
-- Output: 3
```
## Criando Testes
Adicione arquivos de teste para validar que sua extensão funciona corretamente:
1. **Crie um arquivo de teste** em `mysql-test/t/`:
```sql theme={null}
-- mysql-test/t/my_basic.test
SELECT my_reverse('abc');
SELECT my_reverse('');
SELECT my_reverse(NULL);
```
2. **Gere os resultados esperados**:
```bash theme={null}
cd /path/to/villagesql/build/mysql-test
perl mysql-test-run.pl --suite=/path/to/your/extension/mysql-test --record
```
3. **Execute os testes**:
```bash theme={null}
perl mysql-test-run.pl --suite=/path/to/your/extension/mysql-test
```
## Solução de Problemas
### A Extensão Não Carrega
Verifique o log de erros e confira o conteúdo do VEB:
```bash theme={null}
make show_veb
tail -f /var/log/mysql/error.log
```
### Função Não Encontrada
Verifique a instalação e o registro:
```sql theme={null}
SELECT * FROM INFORMATION_SCHEMA.EXTENSIONS;
```
### Erros de Compilação
```bash theme={null}
# Verify mysql_config is available
which mysql_config
mysql_config --version
# Check compiler version
gcc --version # or clang --version
# Verify CMake version (3.18+ required)
cmake --version
```
## Extensões de Exemplo
Aprenda com extensões existentes do VillageSQL:
Implementação do tipo de dado de número complexo
Template mínimo para criar extensões
## Próximos Passos
Aprenda a instalar e gerenciar extensões
Tipos de argumento e de retorno, agregados, variáveis de sistema e testes
Ciclo de vida, cache, desempenho e modelo de segurança
Compile o VillageSQL a partir do código-fonte
## Recursos
* [VillageSQL Extension Template](https://github.com/villagesql/vsql-extension-template)
* [MySQL UDF API Documentation](https://dev.mysql.com/doc/extending-mysql/8.4/en/adding-loadable-function.html)
* [CMake Documentation](https://cmake.org/documentation/)
* [VillageSQL Community Discord](https://discord.gg/KSr6whd3Fr)