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

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

<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.4/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;
```

### 3. 설치 확인

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

## 문제 해결

| 문제                              | 해결 방법                                                         |
| ------------------------------- | ------------------------------------------------------------- |
| `확장을 찾을 수 없음`                   | `.veb` 파일이 `veb_dir`에 있는지 확인: `SHOW VARIABLES LIKE 'veb_dir'` |
| `권한 거부`                         | 파일 권한 확인: `chmod 644 extension.veb`                           |
| `확장 이름 불일치`                     | 확장 내부 이름이 `.veb` 파일 이름과 일치하지 않습니다. 확장을 다시 빌드하세요.              |
| `vef_register를 찾을 수 없음`         | `.veb` 파일이 유효한 VEF 엔트리 포인트를 내보내지 않습니다. 올바른 SDK로 다시 빌드하세요.     |
| `vef_register가 오류를 반환했습니다: ...` | 확장 등록에 실패했습니다. 추가 메시지를 읽어 세부 사항을 확인하세요.                       |

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

## 다음 단계

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

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

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