> ## 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. # Exemplos de Extensões em Rust > Aprenda com as implementações de referência vsql_rot13, vsql_rational, vsql_agg_sum e vsql_varargs usando o SDK Rust Esta página apresenta quatro das extensões de referência do repositório do SDK Rust: um exemplo mínimo que contém apenas uma função, um tipo personalizado completo com aritmética, ordenação e hashing, uma função de agregação e uma função varargs. O diretório `examples/` do repositório também traz um exemplo para cada [capability preview](/docs/pt-BR/mysql-9.7/stable/rust-preview-capabilities) suportada. **Código-fonte:** `examples/` em [vsql-rust-sdk](https://github.com/villagesql/vsql-rust-sdk/tree/main/examples) *** ## vsql\_rot13 — Extensão Apenas com Função A extensão Rust mais simples possível: uma VDF que recebe uma STRING e retorna uma STRING. **Uso:** ```sql theme={null} INSTALL EXTENSION vsql_rot13; SELECT rot13('Hello, World!'); -- 'Uryyb, Jbeyq!' SELECT rot13(rot13('Hello, World!')); -- 'Hello, World!' (rot13 is its own inverse) SELECT rot13(NULL); -- NULL ``` ### Estrutura de Diretórios ``` vsql_rot13/ ├── Cargo.toml # cdylib crate, depends on villagesql ├── manifest.json # Extension metadata ├── src/ │ └── lib.rs # Implementation + extension! registration └── mysql-test/ └── t/*.test # MTR test cases ``` ### Implementação **Arquivo: `src/lib.rs`** ```rust theme={null} use villagesql::{InValue, VdfReturn}; /// SQL: rot13(s STRING) -> STRING fn rot13_impl(args: &[InValue]) -> VdfReturn { match args.first() { Some(InValue::String(s)) => VdfReturn::string(rot13(s)), Some(InValue::Null) | None => VdfReturn::null(), _ => VdfReturn::error("rot13: expected a STRING argument"), } } fn rot13(s: &str) -> String { s.chars() .map(|c| match c { 'a'..='m' | 'A'..='M' => (c as u8 + 13) as char, 'n'..='z' | 'N'..='Z' => (c as u8 - 13) as char, _ => c, }) .collect() } villagesql::extension! { funcs: [ villagesql::func!(rot13_impl, "rot13", [villagesql::Type::String] -> villagesql::Type::String), ] } ``` **Padrões principais:** * As VDFs recebem `&[InValue]` e retornam `VdfReturn`, sendo ambos enums seguros do Rust * NULL é uma variante de primeira classe em ambos os lados; faça o pattern-match diretamente * A macro `extension!` gera os pontos de entrada em C que o servidor chama no momento do carregamento * `func!` declara a assinatura SQL; os tipos de argumento e de retorno usam `villagesql::Type::*` ### Manifesto **Arquivo: `manifest.json`** ```json theme={null} { "name": "vsql_rot13", "version": "0.1.0", "description": "Example VillageSQL extension: provides rot13(STRING) -> STRING", "author": "VillageSQL Community", "license": "GPL-2.0" } ``` *** ## vsql\_rational — Tipo Personalizado com Aritmética Um tipo personalizado completo: números racionais armazenados como `(numerator, denominator)` em forma reduzida, com funções aritméticas, ordenação e hashing. **Uso:** ```sql theme={null} INSTALL EXTENSION vsql_rational; CREATE TABLE measurements (id INT, ratio rational); INSERT INTO measurements VALUES (1, '1/2'), (2, '2/4'), -- normalizes to '1/2' on storage (3, '-3/6'), -- normalizes to '-1/2' (4, '0/1'); SELECT id, ratio FROM measurements ORDER BY ratio; SELECT rational_add('1/2', '1/3'); -- '5/6' SELECT rational_mul('2/3', '3/4'); -- '1/2' SELECT rational_to_real('22/7'); -- 3.142857... ``` ### Formato de Armazenamento Binário `rational` armazena **16 bytes** (little-endian): * Bytes 0–7: numerador (`i64`) * Bytes 8–15: denominador (`i64`) Os valores são sempre armazenados em forma reduzida (GCD = 1) com um denominador positivo. ### Funções do Sistema de Tipos **Arquivo: `src/lib.rs`** O tipo registra quatro operações: encode (string → bytes), decode (bytes → string), compare (para ORDER BY) e hash (para indexação). ```rust theme={null} pub fn rational_encode(s: &str) -> Result, String> { let (num_s, den_s) = s .split_once('/') .ok_or_else(|| format!("rational: expected 'n/d', got {s:?}"))?; let num: i64 = num_s.trim().parse().map_err(|e| format!("numerator: {e}"))?; let den: i64 = den_s.trim().parse().map_err(|e| format!("denominator: {e}"))?; let (n, d) = normalize(i128::from(num), i128::from(den)) .ok_or_else(|| "rational: zero or overflowing denominator".to_string())?; Ok(to_bytes(n, d)) } pub fn rational_decode(b: &[u8]) -> Result { if b.len() < BYTES { return Err(format!("rational: expected {} bytes, got {}", BYTES, b.len())); } let (n, d) = from_bytes(b); Ok(format!("{n}/{d}")) } pub fn rational_compare(a: &[u8], b: &[u8]) -> std::cmp::Ordering { let (n1, d1) = from_bytes(a); let (n2, d2) = from_bytes(b); // Cross-multiply; denominators are always positive after normalization let lhs = i128::from(n1) * i128::from(d2); let rhs = i128::from(n2) * i128::from(d1); lhs.cmp(&rhs) } ``` ### Implementações de VDF As VDFs que recebem um tipo personalizado recebem `InValue::Custom(&[u8])` e decodificam os bytes por conta própria: ```rust theme={null} fn rational_add_impl(args: &[InValue]) -> VdfReturn { match (arg(args, 0), arg(args, 1)) { (Ok(Some((n1, d1))), Ok(Some((n2, d2)))) => { match normalize( i128::from(n1) * i128::from(d2) + i128::from(n2) * i128::from(d1), i128::from(d1) * i128::from(d2), ) { Some((n, d)) => VdfReturn::Binary(to_bytes(n, d)), None => VdfReturn::error("rational_add: overflow"), } } (Err(e), _) | (_, Err(e)) => VdfReturn::error(format!("rational_add: {e}")), _ => VdfReturn::null(), } } ``` ### Registro A macro `extension!` registra tanto o tipo quanto suas funções em uma única declaração: ```rust theme={null} villagesql::extension! { funcs: [ villagesql::func!(rational_add_impl, "rational_add", [villagesql::custom!("rational"), villagesql::custom!("rational")] -> villagesql::custom!("rational"), deterministic: true), villagesql::func!(rational_sub_impl, "rational_sub", [villagesql::custom!("rational"), villagesql::custom!("rational")] -> villagesql::custom!("rational"), deterministic: true), villagesql::func!(rational_mul_impl, "rational_mul", [villagesql::custom!("rational"), villagesql::custom!("rational")] -> villagesql::custom!("rational"), deterministic: true), villagesql::func!(rational_div_impl, "rational_div", [villagesql::custom!("rational"), villagesql::custom!("rational")] -> villagesql::custom!("rational"), deterministic: true), villagesql::func!(rational_numer_impl, "rational_numer", [villagesql::custom!("rational")] -> villagesql::Type::Int, deterministic: true), villagesql::func!(rational_denom_impl, "rational_denom", [villagesql::custom!("rational")] -> villagesql::Type::Int, deterministic: true), villagesql::func!(rational_to_real_impl, "rational_to_real", [villagesql::custom!("rational")] -> villagesql::Type::Real, deterministic: true), ], types: [ villagesql::custom_type!( type_name: "rational", persisted_length: 16, max_decode_buffer_length: 42, encode: rational_encode, decode: rational_decode, compare: rational_compare, hash: rational_hash, default: "0/1", ), ] } ``` **Padrões principais:** * `villagesql::custom!("name")` referencia um tipo personalizado como argumento ou retorno * `custom_type!` registra o tipo junto com suas funções encode/decode/compare/hash * `default: "0/1"` é o padrão intrínseco: o servidor chama `encode()` nessa string na inicialização do tipo, portanto ela deve ser um valor válido * `persisted_length` deve corresponder ao comprimento em bytes que `encode()` retorna * `deterministic: true` permite que o otimizador dobre chamadas constantes *** ## vsql\_agg\_sum — Função de Agregação Uma VDF de agregação que reimplementa `SUM` sobre uma coluna `INT`. Ela mostra os três ganchos de que uma agregação precisa — `clear`, `accumulate` e a função de resultado — e como cada um vê o mesmo acumulador. **Uso:** ```sql theme={null} INSTALL EXTENSION vsql_agg_sum; CREATE TABLE t (grp INT, val INT); INSERT INTO t VALUES (1, 10), (1, 20), (2, 100), (2, 200), (2, 300); SELECT grp, vsql_agg_sum.agg_sum(val) AS mine, SUM(val) AS builtin FROM t GROUP BY grp ORDER BY grp; ``` ``` grp mine builtin 1 30 30 2 600 600 ``` Adicionar um grupo todo de NULLs mostra que o acumulador é redefinido entre grupos em vez de ser carregado adiante: ```sql theme={null} INSERT INTO t VALUES (3, NULL), (3, NULL); SELECT grp, vsql_agg_sum.agg_sum(val) AS mine, SUM(val) AS builtin FROM t GROUP BY grp ORDER BY grp; ``` ``` grp mine builtin 1 30 30 2 600 600 3 NULL NULL ``` ### Ciclo de Vida do Acumulador O acumulador é um valor por instrução, reutilizado em todos os grupos. O servidor o conduz em uma ordem fixa: | Etapa | Sua função | Quando é executada | | ---------- | --------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | Alocação | nenhuma — `agg_func!` a gera | Uma vez por instrução, antes da primeira linha. O SDK aloca o estado em `Default::default()`, e é por isso que o tipo do estado deve implementar `Default`. | | Clear | `clear:` — `fn(&mut State)` | No início de cada grupo. | | Accumulate | `accumulate:` — `fn(&mut State, &[InValue])` | Uma vez por linha do grupo. Não retorna nada; seu único efeito é sobre o estado. | | Resultado | o primeiro argumento de `agg_func!` — `fn(&State) -> VdfReturn` | Uma vez por grupo, depois que a última linha foi incorporada. | | Descarte | nenhuma — `agg_func!` o gera | Depois que a instrução termina. | `clear` redefine o acumulador no início de cada grupo. Um campo que ele esquecer de redefinir vaza do grupo anterior. O servidor chama `accumulate` para cada linha, incluindo as linhas em que o argumento é NULL. Pular os NULLs é trabalho da função: faça a correspondência apenas da variante que você quer e ignore o resto. ### Implementação **Arquivo: `src/lib.rs`** ```rust theme={null} use villagesql::{InValue, VdfReturn}; /// Accumulator for `agg_sum`: the running total for the current group. #[derive(Default)] struct SumState { total: i64, seen: bool, } /// clear: reset the total at the start of each group. fn agg_sum_clear(state: &mut SumState) { state.total = 0; state.seen = false; } /// accumulate: fold one row's int into the running total. fn agg_sum_acc(state: &mut SumState, args: &[InValue]) { if let Some(InValue::Int(n)) = args.first() { state.total += *n; state.seen = true; } } /// result: emit the group's total once every row has been folded in. fn agg_sum_result(state: &SumState) -> VdfReturn { if state.seen { VdfReturn::int(state.total) } else { VdfReturn::Null } } ``` O flag `seen` é o que distingue um grupo cuja soma deu zero de um grupo sem nada para somar. Sem ele, um grupo vazio ou todo de NULLs retornaria `0` onde o `SUM` embutido retorna NULL. ### Registro ```rust theme={null} villagesql::extension! { funcs: [ villagesql::agg_func!(agg_sum_result, "agg_sum", [villagesql::Type::Int] -> villagesql::Type::Int, state: SumState, clear: agg_sum_clear, accumulate: agg_sum_acc), ] } ``` **Padrões principais:** * O primeiro identificador é a função de **resultado**, não a função de linha — o trabalho por linha de uma agregação vive em `accumulate:` * `state:` nomeia o tipo do acumulador, que deve implementar `Default` * A lista de parâmetros declarada é a lista de argumentos por linha: `[villagesql::Type::Int]` é o que `accumulate` recebe, e o tipo de retorno é o que a função de resultado produz * `agg_func!` também aceita `buffer_size:` e `deterministic:` depois de `accumulate:`, fornecidos juntos, nessa ordem *** ## vsql\_varargs — Função Varargs Quatro VDFs que recebem, cada uma, qualquer número de argumentos. Juntas, elas cobrem as três formas de registro que `varargs_func!` suporta — com estado e uma prerun, apenas com prerun e básica — além da validação de argumentos de tipos personalizados. **Uso:** ```sql theme={null} INSTALL EXTENSION vsql_varargs; SELECT vsql_varargs.str_join('alpha', 'beta'); SELECT vsql_varargs.str_join('a', 'b', 'c', 'd'); ``` ``` vsql_varargs.str_join('alpha', 'beta') #1: alpha, beta vsql_varargs.str_join('a', 'b', 'c', 'd') #1: a, b, c, d ``` A mesma função atende às duas aridades. O prefixo `#1` é o contador de chamadas por instrução, que sobe ao longo das linhas de uma instrução: ```sql theme={null} CREATE TABLE t (x VARCHAR(16), y VARCHAR(16)); INSERT INTO t VALUES ('1a', '1b'), ('2a', '2b'), ('3a', '3b'); SELECT vsql_varargs.str_join(x, y) AS joined FROM t ORDER BY x; ``` ``` joined #1: 1a, 1b #2: 2a, 2b #3: 3a, 3b ``` ### A Prerun É Dona de Toda a Validação de Varargs Para uma função varargs, o servidor não faz nenhuma verificação de argumentos — nem a contagem, nem os tipos. Uma assinatura declarada é o que normalmente faz o servidor rejeitar uma chamada ruim antes que seu código seja executado, e uma função varargs não tem nenhuma. O que quer que o gancho prerun não rejeite chega à função de linha. A prerun rejeita a *chamada*, uma vez, antes de qualquer linha: ela vê os tipos de argumento que o otimizador resolveu e faz a instrução falhar. A função de linha ainda tem que tratar cada *valor*, porque uma coluna cujo tipo passou na validação ainda pode carregar NULL em qualquer linha. Uma rejeição da prerun faz a inicialização da instrução falhar: ```sql theme={null} SELECT vsql_varargs.str_join(); ``` ``` ERROR 1123 (HY000): Can't initialize function 'str_join'; str_join requires at least one argument ``` ```sql theme={null} SELECT vsql_varargs.str_join('ok', 123); ``` ``` ERROR 1123 (HY000): Can't initialize function 'str_join'; str_join: every argument must be a string ``` Omitir a prerun significa aceitar toda chamada. `arg_count` é registrada na forma básica, então uma chamada com zero argumentos é legal: ```sql theme={null} SELECT vsql_varargs.arg_count(); SELECT vsql_varargs.arg_count(1, 2.5, 'mix'); ``` ``` vsql_varargs.arg_count() 0 vsql_varargs.arg_count(1, 2.5, 'mix') 3 ``` ### Implementação **Arquivo: `src/lib.rs`** Uma prerun recebe `PrerunArgs` e um `PrerunResult` cujo `T` corresponde ao tipo do estado. `PrerunArgs::len()` é a contagem de argumentos, e `type_at(i)` retorna o tipo do argumento `i` como um `ArgType`: ```rust theme={null} use villagesql::{InValue, PrerunArgs, PrerunResult, VdfReturn}; /// Per-statement state: how many times the row handler has run this statement. #[derive(Default)] struct JoinState { calls: i64, } /// Validate the call and set up the statement. The server does no validation for /// varargs, so this is the only gate. fn str_join_prerun(args: PrerunArgs, mut out: PrerunResult) { // Reject a zero-argument call. if args.is_empty() { out.error("str_join requires at least one argument"); return; } // Every argument must be a string. for i in 0..args.len() { if !args.type_at(i).is_some_and(|t| t.is_str()) { out.error("str_join: every argument must be a string"); return; } } // Size the result buffer from the arg count. out.request_buffer_size(32 + args.len() * 64); // Hand the fresh counter to the server. out.set_state(JoinState::default()); } /// Join a variable number of string arguments, prefixed with the per-statement /// call count. `args` length varies with how many arguments the SQL call passed. fn str_join(state: &mut JoinState, args: &[InValue]) -> VdfReturn { state.calls += 1; let mut joined = String::new(); for (i, arg) in args.iter().enumerate() { match arg { InValue::String(s) => { if i > 0 { joined.push_str(", "); } joined.push_str(s); } // A string column can carry NULL. SQL-style: NULL in -> NULL out. InValue::Null => return VdfReturn::Null, _ => return VdfReturn::error("str_join: non-string argument at runtime"), } } VdfReturn::string(format!("#{}: {joined}", state.calls)) } /// Bare varargs: no prerun, no state, no validation. Returns how many arguments /// it was called with, including zero. fn arg_count(args: &[InValue]) -> VdfReturn { VdfReturn::int(i64::try_from(args.len()).unwrap_or(i64::MAX)) } ``` Para varargs, dimensione o buffer na prerun com `request_buffer_size`, escalado por `args.len()` — um `buffer_size` fixo não pode crescer com a contagem de argumentos. `ArgType` expõe quatro predicados — `is_int()`, `is_real()`, `is_str()` e `is_custom()` — para que uma prerun possa aceitar uma chamada heterogênea desde que todo argumento seja um dos formatos que a função de linha trata. `describe` aceita qualquer combinação dos três escalares e rejeita qualquer outra coisa: ```rust theme={null} fn describe_prerun(args: PrerunArgs, mut out: PrerunResult<()>) { if args.is_empty() { out.error("describe requires at least one argument"); return; } for i in 0..args.len() { let ok = args .type_at(i) .is_some_and(|t| t.is_int() || t.is_real() || t.is_str()); if !ok { out.error("describe: arguments must be INT, REAL, or STRING"); return; } } out.request_buffer_size(32 + args.len() * 48); } ``` ```sql theme={null} SELECT vsql_varargs.describe(42, 3.14e0, 'hello'); ``` ``` vsql_varargs.describe(42, 3.14e0, 'hello') int:42, real:3.14, str:hello ``` O tipo do estado é `()` porque essa prerun não guarda nada: ela valida e dimensiona o buffer, e nunca chama `set_state`. ### Varargs com Tipos Personalizados `is_custom()` sozinho diz apenas que o argumento é *algum* tipo personalizado. `custom_name()` retorna qual deles, então uma prerun pode restringir uma chamada varargs a um único tipo. A extensão registra um tipo personalizado `point2d` e aceita um número variável de valores `point2d`: ```rust theme={null} fn point_path_prerun(args: PrerunArgs, mut out: PrerunResult<()>) { if args.is_empty() { out.error("point_path requires at least one point"); return; } for i in 0..args.len() { let ok = args .type_at(i) .is_some_and(|t| t.is_custom() && t.custom_name() == Some("point2d")); if !ok { out.error("point_path: every argument must be a point2d"); return; } } out.request_buffer_size(16 + args.len() * 32); } ``` ```sql theme={null} SELECT vsql_varargs.point_path(point2d::from_string('0,0'), point2d::from_string('1,2'), point2d::from_string('3,5')); ``` ``` vsql_varargs.point_path(point2d::from_string('0,0'), point2d::from_string('1,2'), point2d::from_string('3,5')) (0,0) -> (1,2) -> (3,5) ``` Uma string simples é rejeitada antes da primeira linha, mesmo que seus bytes fossem interpretáveis como um ponto: ```sql theme={null} SELECT vsql_varargs.point_path('1,2'); ``` ``` ERROR 1123 (HY000): Can't initialize function 'point_path'; point_path: every argument must be a point2d ``` A função de linha então faz a correspondência de `InValue::Custom(b)` e decodifica os bytes por conta própria, como qualquer outra VDF de tipo personalizado. ### Registro ```rust theme={null} villagesql::extension! { funcs: [ villagesql::varargs_func!(str_join, "str_join", [..] -> villagesql::Type::String, state: JoinState, prerun: str_join_prerun), villagesql::varargs_func!(arg_count, "arg_count", [..] -> villagesql::Type::Int), villagesql::varargs_func!(describe, "describe", [..] -> villagesql::Type::String, prerun: describe_prerun), villagesql::varargs_func!(point_path, "point_path", [..] -> villagesql::Type::String, prerun: point_path_prerun), ], types: [ villagesql::custom_type!( type_name: "point2d", persisted_length: 8, max_decode_buffer_length: 32, encode: point_encode, decode: point_decode, compare: point_compare, default: "0,0", ), ] } ``` `describe`, `point_path` e o `encode`/`decode`/`compare` de `point2d` seguem os mesmos padrões de correspondência de `InValue` e de codificação de bytes já mostrados para `str_join` e `rational` acima — consulte `examples/vsql_varargs/src/lib.rs` no [repositório do SDK Rust](https://github.com/villagesql/vsql-rust-sdk) para o código-fonte completo. **Padrões principais:** * `[..]` no lugar de uma lista de parâmetros é o que marca a função como varargs * Três formas, cada uma com uma assinatura diferente de função de linha: `state:` + `prerun:` dá `fn(&mut State, &[InValue]) -> VdfReturn`; `prerun:` sozinha e a forma básica dão ambas `fn(&[InValue]) -> VdfReturn` * Apenas a forma com `state:` aloca e descarta o estado por instrução * O tipo de retorno ainda é declarado, então apenas a lista de argumentos é variável * Cada forma também aceita `buffer_size:` e `deterministic:` como um par final * `point2d` não registra `hash`, que é opcional — `compare` sozinho é suficiente para `ORDER BY` *** ## Padrões Principais de Implementação | Padrão | Uso | | ----------------------------------------- | ---------------------------------------------------------------------------------------------- | | **Assinatura de VDF** | `fn impl(args: &[InValue]) -> VdfReturn` | | **Tratamento de NULL** | Faça o match de `InValue::Null` e `None` explicitamente | | **Relato de erros** | `VdfReturn::error("message")` aborta a instrução | | **Encode de tipo personalizado** | Retorna `Result, String>` | | **Decode de tipo personalizado** | Retorna `Result` | | **Argumentos com reconhecimento de tipo** | Use `villagesql::custom!("name")` em `func!` | | **Função de agregação** | `agg_func!(result_fn, ..., state: T, clear: f, accumulate: f)`; `T` deve implementar `Default` | | **Função varargs** | `varargs_func!(f, "name", [..] -> ret)`; a prerun é a única validação de argumentos | | **Inspeção de tipos na prerun** | `PrerunArgs::type_at(i)` → `ArgType::is_int`/`is_real`/`is_str`/`is_custom`/`custom_name` | | **Registro** | Um único bloco `extension!` declara funções e tipos | *** ## Testes Todos os quatro exemplos usam MTR (o MySQL Test Runner) assim como as extensões em C++: ```bash theme={null} # From inside the example directory -- cargo-vsql passes the suite's full path: cargo vsql test # Or point mysql-test-run.pl at the suite directly. A bare --suite=vsql_rot13 # fails: that form only finds suites staged inside the server's own # mysql-test/suite/ tree, and these live in the SDK repo. cd /path/to/villagesql/build/mysql-test ./mysql-test-run.pl --suite=/path/to/vsql-rust-sdk/examples/vsql_rot13/mysql-test ./mysql-test-run.pl --suite=/path/to/vsql-rust-sdk/examples/vsql_rational/mysql-test ./mysql-test-run.pl --suite=/path/to/vsql-rust-sdk/examples/vsql_agg_sum/mysql-test ./mysql-test-run.pl --suite=/path/to/vsql-rust-sdk/examples/vsql_varargs/mysql-test ``` Gere ou atualize os resultados esperados com `--record`. *** ## Próximos Passos Instalação do SDK, compilação e a macro extension! Aprofundamento em encode, decode, compare e hash InValue, VdfReturn e a superfície da macro Código-fonte completo dos quatro exemplos