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

# 확장 설치

> 확장을 사용하여 VillageSQL에 새로운 기능을 추가하는 방법입니다.

VillageSQL 확장을 설치하여 데이터베이스에 사용자 정의 유형, 함수 및 기능을 추가합니다.

## 명령어 구문

```sql theme={null}
INSTALL EXTENSION extension_name [VERSION 'version'];
```

`VERSION`이 제공되면 서버는 `{name}-{version}.veb`를 열고 매니페스트와 버전을 비교하며, 다를 경우 중단합니다. 이 절을 생략하면 `{name}.veb`를 설치하거나, 버전이 지정된 VEB만 존재하는 경우 유일하게 존재하는 `{name}-{version}.veb`를 설치합니다. [버전 선택](#selecting-a-version)을 참조하세요.

<Info>
  확장은 컴파일된 라이브러리와 메타데이터를 포함한 `.veb`(VillageSQL 확장 번들) 파일로 배포됩니다.
</Info>

<h3 id="selecting-a-version">
  버전 선택
</h3>

`veb_dir`의 VEB 파일은 `{name}.veb`(버전 미지정) 또는 `{name}-{version}.veb`(버전 지정) 중 하나로 이름을 지정할 수 있습니다. 특정 버전의 VEB를 설치하려면 `VERSION` 절을 추가하세요:

```sql theme={null}
INSTALL EXTENSION vsql_uuid VERSION '0.2.0';
```

`VERSION`을 사용하면 서버는 `vsql_uuid-0.2.0.veb`를 열고 해당 `manifest.json`의 버전이 `0.2.0`과 일치하는지 확인합니다.

`VERSION`이 없으면 서버는 다음과 같이 파일을 결정합니다:

* `{name}.veb`가 존재하면 이를 설치하며, 버전은 해당 `manifest.json`에서 읽습니다.
* 그렇지 않고 정확히 하나의 `{name}-{version}.veb`가 존재하면 이를 설치하며, 파일 이름의 버전은 해당 `manifest.json`과 대조하여 검증됩니다.
* 그렇지 않으면 설치가 실패하며 버전을 지정해야 합니다.

<Warning>
  버전이 지정된 여러 VEB가 존재하고 버전 미지정 VEB가 없으면 `INSTALL EXTENSION`은 `Multiple versions of extension '<name>' found in '<dir>'; specify a version with INSTALL EXTENSION <name> VERSION 'x.y.z'` 오류와 함께 실패합니다. 명시적인 `VERSION` 절을 사용하여 다시 실행하세요.
</Warning>

<h3 id="extension-naming-conventions">
  확장 명명 규칙
</h3>

VillageSQL은 다양한 맥락에서 다른 명명 규칙을 사용합니다:

* **SQL 명령어:** 밑줄 사용: `INSTALL EXTENSION vsql_uuid`
* **저장소 이름:** 하이픈 사용: `github.com/villagesql/vsql-uuid`
* **파일 이름:** 밑줄 사용: `vsql_uuid.veb`
* **manifest.json:** SQL과 일치하도록 밑줄 사용: `"name": "vsql_uuid"`

**예시:**

```bash theme={null}
# Clone from GitHub repo (hyphens in URL)
git clone https://github.com/villagesql/vsql-uuid

# But .veb file uses underscores
ls vsql_uuid.veb

# Install with underscores (no quotes)
INSTALL EXTENSION vsql_uuid;
```

## 사전 요구 사항

* 실행 중인 VillageSQL 서버 인스턴스
* 관리자 접근 권한(루트 또는 동등한 계정)

## 내장 확장 설치

VillageSQL에 포함된 내장 확장은 이미 veb\_dir에 있습니다. 간단히 활성화만 하면 됩니다:

```sql theme={null}
-- Connect to VillageSQL
mysql -u root -p

-- Install the extension
INSTALL EXTENSION vsql_complex;
```

### 설치 확인

```sql theme={null}
-- List installed extensions
SELECT * FROM INFORMATION_SCHEMA.EXTENSIONS;
```

**출력:**

```
+------------------+-------------------+
| EXTENSION_NAME   | EXTENSION_VERSION |
+------------------+-------------------+
| vsql_complex     | 0.0.1             |
+------------------+-------------------+
```

### 기능 테스트

```sql theme={null}
-- Create a database first
CREATE DATABASE test_db;
USE test_db;

-- Test extension functions
CREATE TABLE test (id INT, value COMPLEX);
INSERT INTO test VALUES (1, '(3,4)');
SELECT complex_abs(value) FROM test;  -- Returns 5.0

-- Clean up
DROP TABLE test;
DROP DATABASE test_db;
```

## 외부 확장 설치

별도로 다운로드하거나 빌드한 확장의 경우:

<Info>
  외부 확장을 설치하기 전에 서버에서 `veb_dir`이 구성되어 있어야 합니다. [veb\_dir 구성하기](/docs/ko/mysql-8.4/0.0.5/managing#configuring-veb_dir)를 참조하세요.
</Info>

### 1. .veb 파일 복사

서버의 확장 디렉토리를 찾아 `.veb` 파일을 해당 디렉토리로 복사합니다:

```sql theme={null}
-- Find the extension directory
SHOW VARIABLES LIKE 'veb_dir';
```

```bash theme={null}
cp /path/to/my_extension.veb /path/to/veb_dir/
```

### 2. 확장 설치

```sql theme={null}
INSTALL EXTENSION my_extension;
```

CI 또는 스크립트 기반 롤아웃에서 유용하도록, 예상 버전을 고정하려면 `VERSION` 절을 포함하세요:

```sql theme={null}
INSTALL EXTENSION my_extension VERSION '1.2.0';
```

매니페스트가 다른 버전을 보고하면 설치가 실패하고 아무것도 등록되지 않습니다:

```
ERROR 3219 (HY000): Version mismatch in 'my_extension-1.2.0.veb':
filename says '1.2.0' but manifest says '0.0.1'
```

### 3. 설치 확인

```sql theme={null}
SELECT * FROM INFORMATION_SCHEMA.EXTENSIONS WHERE EXTENSION_NAME = 'my_extension';
```

## 문제 해결

| 문제                                                                                                                      | 해결 방법                                                                                                |
| ----------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `Extension not found`                                                                                                   | `.veb` 파일이 `veb_dir`에 있는지 확인: `SHOW VARIABLES LIKE 'veb_dir'`                                        |
| `Permission denied`                                                                                                     | 파일 권한 확인: `chmod 644 extension.veb`                                                                  |
| `extension name mismatch`                                                                                               | 확장 내부 이름이 `.veb` 파일 이름과 일치하지 않습니다. 확장을 다시 빌드하세요.                                                     |
| `vef_register not found`                                                                                                | `.veb` 파일이 유효한 VEF 엔트리 포인트를 내보내지 않습니다. 올바른 SDK로 다시 빌드하세요.                                            |
| `vef_register returned an error: ...`                                                                                   | 확장 등록에 실패했습니다. 추가 메시지를 읽어 세부 사항을 확인하세요.                                                              |
| `Version mismatch in 'name-Y.veb': filename says 'Y' but manifest says 'X'`                                             | `VERSION` 절이 `{name}-{version}.veb`를 선택하지만 내부 매니페스트가 다른 버전을 보고합니다. 매니페스트 버전으로 다시 실행하거나 파일 이름을 수정하세요. |
| `Multiple versions of extension 'name' found in '<dir>'; specify a version with INSTALL EXTENSION name VERSION 'x.y.z'` | 버전 미지정 `{name}.veb` 없이 여러 `{name}-{version}.veb` 파일이 존재합니다. 명시적인 `VERSION` 절을 사용하여 다시 실행하세요.         |

추가 문제 해결은 [확장 관리](/docs/ko/mysql-8.4/0.0.5/managing)를 참조하세요.

## 다음 단계

<CardGroup cols={2}>
  <Card title="확장 관리" icon="sliders" href="/docs/ko/mysql-8.4/0.0.5/managing">
    설치된 확장 모니터링 및 문제 해결
  </Card>

  <Card title="사용 가능한 확장" icon="list" href="/docs/ko/mysql-8.4/0.0.5/extensions">
    설치 가능한 확장 탐색
  </Card>

  <Card title="확장 만들기" icon="code" href="/docs/ko/mysql-8.4/0.0.5/create">
    자체 확장 빌드
  </Card>
</CardGroup>