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

# Rust 확장 작성하기

> Rust로 VillageSQL 확장을 작성하는 방법 — Rust를 선택해야 하는 경우, cargo-vsql 설정, 함수 작성, 테스트, 설치를 다룹니다.

> [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 →

VillageSQL 확장은 `villagesql` 크레이트를 사용하여 Rust로 작성할 수 있습니다. SDK가 모든 FFI 마셜링을 처리하므로 — 여러분은 평범한 Rust를 작성하고, `extension!` 매크로가 서버가 로드 시점에 호출하는 C 진입점을 생성합니다.

## Rust를 선택해야 하는 경우

다음과 같은 경우 Rust가 올바른 선택입니다:

* Rust를 선호하고 C++ 코드베이스가 필요하지 않을 때
* 가비지 컬렉터 없이 메모리 안전성을 원할 때
* 새 확장을 만들고 있고 기존 C++ 의존성이 없을 때

기존 C++ 코드베이스가 있거나 현재 사용할 수 있는 가장 완전한 사용자 정의 타입 빌더 API가 필요하다면 [C++ 확장 작성하기](https://villagesql.com/docs/ko/guides/cpp-extensions.md)를 참조하세요.

> [!WARNING]
>
> 이 API는 확장 개발에 안정적이지만, 사용자 정의 타입 빌더 API는 아직 성숙해 가는 중입니다.

## 사전 요구 사항

다음이 필요합니다:

* **Rust 안정 툴체인** — [rustup.rs](https://rustup.rs)에서 설치
* **cargo-vsql** — 패키징, 설치, 테스트를 위한 Cargo 하위 명령

SDK 저장소에서 `cargo-vsql`을 설치하세요:

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

## 새 크레이트 설정하기

라이브러리 크레이트를 만들고, SDK를 추가하고, 설정하세요:

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

그다음 `Cargo.toml`에서 크레이트 타입을 설정하세요:

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

`Cargo.toml` 옆에 `manifest.json`을 추가하세요:

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

## 함수 작성하기

[Rust로 확장 만들기](https://villagesql.com/docs/ko/extensions/build/rust-sdk.md) 페이지에 ROT-13 예제를 사용한 전체 안내가 있습니다. 짧게 요약하면: `fn(&[InValue]) -> VdfReturn`을 구현하고, `func!`로 등록하고, 모든 것을 `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),
    ]
}
```

사용자 정의 타입(바이너리 저장, 정렬, 해싱)은 [Rust에서의 사용자 정의 타입](https://villagesql.com/docs/ko/sdk/rust/custom-types.md)을 참조하세요.

## 확장 테스트하기

`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;
```

VillageSQL 빌드 디렉터리를 설정하고, 예상 결과를 생성한 다음, 실행하세요:

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

통과한 실행은 각 테스트 파일에 대해 `[ pass ]`를 출력합니다.

## SQL에서 설치하기

패키징하고 설치하세요:

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

그다음 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
```

## 함께 보기

* [Rust로 확장 만들기](https://villagesql.com/docs/ko/extensions/build/rust-sdk.md) — ROT-13 예제, 패키징, 테스트 세부 사항을 담은 전체 안내
* [Rust에서의 사용자 정의 타입](https://villagesql.com/docs/ko/sdk/rust/custom-types.md) — 바이너리 저장과 정렬을 갖춘 새 열 타입 정의
* [Rust API 참조](https://villagesql.com/docs/ko/sdk/rust/api-reference.md) — InValue, VdfReturn, 모든 매크로
* [C++ 확장 작성하기](https://villagesql.com/docs/ko/guides/cpp-extensions.md) — 같은 작업을 위한 C++ 경로


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