> ## 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.

# Escrevendo Extensões em Rust

> Como escrever uma extensão do VillageSQL em Rust — quando escolher Rust, configuração do cargo-vsql, escrita de uma função, testes e instalação.

> [card] [VillageSQL is a drop-in replacement for MySQL with extensions.](https://villagesql.com/docs/en/8.4/stable/install-server.md)
>
> All examples on this page work on VillageSQL. Install Now →

As extensões do VillageSQL podem ser escritas em Rust usando o crate `villagesql`. O SDK cuida de todo o marshaling de FFI — você escreve Rust comum, e a macro `extension!` gera os pontos de entrada em C que o servidor chama no momento do carregamento.

## Quando Escolher Rust

Rust é a escolha certa quando:

* Você prefere Rust e não precisa de uma base de código em C++
* Você quer segurança de memória sem um garbage collector
* Você está construindo uma nova extensão e não tem nenhuma dependência existente em C++

Se você tem uma base de código existente em C++ ou precisa da API de construção de tipos personalizados mais completa disponível hoje, consulte [Escrevendo Extensões em C++](https://villagesql.com/docs/pt-BR/guides/cpp-extensions.md).

> [!WARNING]
>
> A API é estável para o desenvolvimento de extensões, mas a API de construção de tipos personalizados ainda está amadurecendo.

## Pré-requisitos

Você precisa de:

* **Toolchain estável do Rust** — instale em [rustup.rs](https://rustup.rs)
* **cargo-vsql** — o subcomando do Cargo para empacotar, instalar e testar

Instale o `cargo-vsql` a partir do repositório do SDK:

```bash theme={null}
git clone https://github.com/villagesql/vsql-rust-sdk
cd vsql-rust-sdk
cargo install --path cargo-vsql
```

## Configure um Novo Crate

Crie um crate de biblioteca, adicione o SDK e configure-o:

```bash theme={null}
cargo new --lib vsql_my_extension
cd vsql_my_extension
cargo add villagesql
```

Em seguida, defina o tipo do crate em `Cargo.toml`:

```toml theme={null}
[lib]
crate-type = ["cdylib"]
```

Adicione `manifest.json` ao lado de `Cargo.toml`:

```json theme={null}
{
  "name": "vsql_my_extension",
  "version": "0.1.0",
  "description": "My VillageSQL extension",
  "author": "Your Name",
  "license": "GPL-2.0"
}
```

## Escreva uma Função

A página [Construindo Extensões em Rust](https://villagesql.com/docs/pt-BR/extensions/build/rust-sdk.md) tem o passo a passo completo com o exemplo ROT-13. A versão resumida: implemente `fn(&[InValue]) -> VdfReturn`, registre-a com `func!` e envolva tudo em `extension!`:

```rust theme={null}
use villagesql::{InValue, VdfReturn};

fn my_func_impl(args: &[InValue]) -> VdfReturn {
    match args.first() {
        Some(InValue::String(s)) => VdfReturn::string(s.to_uppercase()),
        Some(InValue::Null) | None => VdfReturn::null(),
        _ => VdfReturn::error("my_func: expected a STRING argument"),
    }
}

villagesql::extension! {
    funcs: [
        villagesql::func!(my_func_impl, "my_func", [villagesql::Type::String] -> villagesql::Type::String),
    ]
}
```

Para tipos personalizados (armazenamento binário, ordenação, hashing), consulte [Tipos Personalizados em Rust](https://villagesql.com/docs/pt-BR/sdk/rust/custom-types.md).

## Teste Sua Extensão

Escreva um teste em `mysql-test/t/basic.test`:

```sql theme={null}
INSTALL EXTENSION vsql_my_extension;
SELECT my_func('hello');
SELECT my_func(NULL);
UNINSTALL EXTENSION vsql_my_extension;
```

Defina o diretório de build do seu VillageSQL, gere os resultados esperados e então execute:

```bash theme={null}
export VillageSQL_BUILD_DIR=/path/to/villagesql/build
cargo vsql test --record
cargo vsql test
```

Uma execução bem-sucedida imprime `[ pass ]` para cada arquivo de teste.

## Instale em SQL

Empacote e instale:

```bash theme={null}
cargo vsql install
```

Em seguida, em SQL:

```sql theme={null}
INSTALL EXTENSION vsql_my_extension;
SELECT * FROM INFORMATION_SCHEMA.EXTENSIONS WHERE EXTENSION_NAME = 'vsql_my_extension';
SELECT my_func('hello');
-- → HELLO
```

## Veja também

* [Construindo Extensões em Rust](https://villagesql.com/docs/pt-BR/extensions/build/rust-sdk.md) — passo a passo completo com o exemplo ROT-13, empacotamento e detalhes de testes
* [Tipos Personalizados em Rust](https://villagesql.com/docs/pt-BR/sdk/rust/custom-types.md) — defina novos tipos de coluna com armazenamento binário e ordenação
* [Referência da API Rust](https://villagesql.com/docs/pt-BR/sdk/rust/api-reference.md) — InValue, VdfReturn e todas as macros
* [Escrevendo Extensões em C++](https://villagesql.com/docs/pt-BR/guides/cpp-extensions.md) — o caminho em C++ para a mesma tarefa


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.