확장 설치

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

명령어 구문

INSTALL EXTENSION extension_name [VERSION 'version'];

VERSION이 제공되면 서버는 {name}-{version}.veb를 열고, 그 매니페스트가 다른 버전을 지정하면 중단합니다:

ERROR 3219 (HY000): Version mismatch in '<file>': filename says 'X' but manifest says 'Y'

버전이 지정된 파일이 없으면 서버는 대신 {name}.veb를 열고 다음 오류와 함께 중단합니다:

ERROR 3219 (HY000): Cannot install extension '<name>': manifest version is 'X' but VERSION 'Y' was specified

이 절을 생략하면 {name}.veb를 설치하거나, 버전이 지정된 VEB만 존재하는 경우 유일하게 존재하는 {name}-{version}.veb를 설치합니다. 버전 선택을 참조하세요.

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

버전 선택

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

INSTALL EXTENSION vsql_uuid VERSION '0.2.0';

VERSION을 사용하면 서버는 vsql_uuid-0.2.0.veb가 존재하면 그 파일을, 그렇지 않으면 vsql_uuid.veb를 열고 해당 manifest.json의 버전이 0.2.0과 일치하는지 확인합니다. VERSION이 없으면 서버는 다음과 같이 파일을 결정합니다:

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

버전이 지정된 여러 VEB가 존재하고 버전 미지정 VEB가 없으면 INSTALL EXTENSION은

Multiple versions of extension '<name>' found in '<dir>'; specify a version with INSTALL EXTENSION <name> VERSION 'x.y.z'

오류와 함께 실패합니다. 명시적인 VERSION 절을 사용하여 다시 실행하세요.

확장 명명 규칙

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

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

예시:

# Clone from GitHub repo (hyphens in URL)
git clone https://github.com/villagesql/vsql-uuid

# After you build the extension, its .veb file uses underscores
# vsql_uuid.veb

# Then install it from a mysql session, with underscores and no quotes:
#   INSTALL EXTENSION vsql_uuid;

필수 권한

INSTALL EXTENSION, UNINSTALL EXTENSION 및 ALTER EXTENSION은 EXTENSION_ADMIN 동적 권한으로 보호됩니다. 이 문장들은 네이티브 확장 코드를 실행 중인 서버에 로드하므로 관리 권한이 필요하며, 권한이 없는 계정에서는 사용할 수 없습니다. EXTENSION_ADMIN은 전역 범위(ON *.*)에서 부여되는 동적 권한입니다:

GRANT EXTENSION_ADMIN ON *.* TO user@host;

이전 버전과의 호환성을 위해 SUPER도 대체 권한으로 허용되므로, 이미 SUPER를 보유한 계정은 별도의 부여 없이 이 문장들을 실행할 수 있습니다. --initialize 또는 --initialize-insecure로 생성된 데이터 디렉토리는 root@localhost에 EXTENSION_ADMIN을 직접 부여하므로, 새 서버에는 수동 부여가 필요하지 않습니다. 기존 데이터 디렉토리를 제자리에서 업그레이드하면 SUPER를 보유한 모든 사용자 계정에 EXTENSION_ADMIN이 부여됩니다. 단, 이미 이 권한을 보유한 계정이 하나도 없는 경우에만 부여되므로, 한 번 업그레이드된 서버는 이후 업그레이드에서 다시 채워지지 않습니다. 예약된 mysql.* 시스템 계정은 제외됩니다. 두 권한 중 어느 것도 보유하지 않은 계정은 확장 작업이 시작되기 전에 거부됩니다:

ERROR 1227 (42000): Access denied; you need (at least one of) the EXTENSION_ADMIN or SUPER privilege(s) for this operation

권한 취소도 같은 방식으로 수행합니다:

REVOKE EXTENSION_ADMIN ON *.* FROM user@host;

취소는 다음 연결이 아니라 즉시 적용됩니다. 서버는 모든 확장 DDL 문에서 계정의 현재 권한에 대해 EXTENSION_ADMIN/SUPER를 확인하므로, 기존 세션은 취소 후에도 권한을 유지하지 않습니다. 바로 다음 문장에서 위에 표시된 것과 동일한 ERROR 1227 (42000)으로 실패합니다.

사전 요구 사항

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

내장 확장 설치

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

INSTALL EXTENSION vsql_complex;

설치 확인

-- List installed extensions
SELECT * FROM INFORMATION_SCHEMA.EXTENSIONS;

출력:

+----------------+-------------------+-----------------+----------------------+--------------------+-----------------------+
| EXTENSION_NAME | EXTENSION_VERSION | PENDING_VERSION | PENDING_REQUESTED_AT | PENDING_LAST_ERROR | PENDING_LAST_ERROR_AT |
+----------------+-------------------+-----------------+----------------------+--------------------+-----------------------+
| vsql_complex   | 0.0.1             | NULL            | NULL                 | NULL               | 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

-- Clean up
DROP TABLE test;
DROP DATABASE test_db;  -- deletes the database created above; do this only if test_db was created by this example

외부 확장 설치

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

모든 서버에는 기본 veb_dir이 있습니다. 다른 디렉토리를 사용하려면 veb_dir 구성하기를 참조하세요.

1. .veb 파일 복사

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

-- Find the extension directory
SHOW VARIABLES LIKE 'veb_dir';

cp /path/to/my_extension.veb /path/to/veb_dir/

2. 확장 설치

INSTALL EXTENSION my_extension;

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

INSTALL EXTENSION my_extension VERSION '1.2.0';

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

ERROR 3219 (HY000): Cannot install extension 'my_extension': manifest version
is '0.0.1' but VERSION '1.2.0' was specified

이는 대체 파일 경로({name}-{version}.veb가 존재하지 않는 경우)이며, 앞서 표시된 Version mismatch in '<file>' 오류와는 다른 코드 경로입니다. 후자는 버전이 지정된 파일 자체가 존재할 때 발생합니다. 빈 VERSION ''은 불일치가 아닙니다 — 서버는 이를 아무 제약도 없는 것으로 취급하므로, 사용 가능한 버전이 무엇이든 설치는 성공합니다. 설정되지 않은 변수를 VERSION 절에 삽입하는 스크립트는 실패하지 않고, 대신 조용히 버전 고정을 건너뜁니다.

3. 설치 확인

SELECT * FROM INFORMATION_SCHEMA.EXTENSIONS WHERE EXTENSION_NAME = 'my_extension';

문제 해결

문제	해결 방법
`VEB file not found: <name>.veb`	`.veb` 파일이 `veb_dir`에 있는지 확인: `SHOW VARIABLES LIKE 'veb_dir'`
`Cannot open VEB file '<name>.veb': Failed to open '<path>'`	파일 권한 확인: `chmod 644 extension.veb`
`Manifest name '<name>' does not match VEB basename '<file>'`	`manifest.json`의 이름이 `.veb` 파일 이름과 일치하지 않습니다. 확장을 다시 빌드하세요.
`vef_register not found: ...`	`.veb` 파일이 유효한 VEF 엔트리 포인트를 내보내지 않습니다. 올바른 SDK로 다시 빌드하세요.
`vef_register returned an error: ...`	확장 등록에 실패했습니다. 추가 메시지를 읽어 세부 사항을 확인하세요.
`Cannot install extension 'name': manifest version is 'X' but VERSION 'Y' was specified`	`{name}-{version}.veb`가 존재하지 않아 서버가 `{name}.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` 절을 사용하여 다시 실행하세요.

추가 문제 해결은 확장 관리를 참조하세요.

다음 단계

확장 관리

설치된 확장 모니터링 및 문제 해결

사용 가능한 확장

설치 가능한 확장 탐색

확장 만들기

자체 확장 빌드

Getting Started

Server Development

Using Extensions

Creating Extensions

명령어 구문

버전 선택

확장 명명 규칙

필수 권한

사전 요구 사항

내장 확장 설치

설치 확인

기능 테스트

외부 확장 설치

1. .veb 파일 복사

2. 확장 설치

3. 설치 확인

문제 해결

다음 단계

확장 관리

사용 가능한 확장

확장 만들기

​명령어 구문

​버전 선택

​확장 명명 규칙

​필수 권한

​사전 요구 사항

​내장 확장 설치

​설치 확인

​기능 테스트

​외부 확장 설치

​1. .veb 파일 복사

​2. 확장 설치

​3. 설치 확인

​문제 해결

​다음 단계

확장 관리

사용 가능한 확장

확장 만들기

명령어 구문

버전 선택

확장 명명 규칙

필수 권한

사전 요구 사항

내장 확장 설치

설치 확인

기능 테스트

외부 확장 설치

1. .veb 파일 복사

2. 확장 설치

3. 설치 확인

문제 해결

다음 단계