설치된 확장 보기
INFORMATION_SCHEMA 뷰를 사용하여 설치된 확장을 쿼리합니다:- 인터랙티브 세션과 스크립트 모두에서 사용 가능
- MySQL 도구와 호환되는 표준 SQL 인터페이스
확장 함수 확인
설치 후 확장 함수가 정상 작동하는지 확인합니다:확장 디렉터리
VillageSQL이.veb 파일을 찾는 위치를 확인합니다:
veb_dir 구성
확장 디렉터리 위치를 변경하려면 MySQL 구성 파일에veb_dir을 설정합니다:
my.cnf / my.ini:
- 경로는 절대 경로여야 함(상대 경로 불가)
- 서버 시작 전 디렉터리가 존재해야 함
- MySQL 사용자에게 디렉터리 읽기 권한이 있어야 함
- 하나의
veb_dir만 지원됨(여러 경로 불가) - 변경 사항은 서버 재시작 후 적용됨
문제 해결
빠른 참조
확장을 찾을 수 없음
오류:Extension 'my_extension' not found
디버그 단계:
설치 후 함수 사용 불가
오류:FUNCTION my_func does not exist
디버그 단계:
업데이트 후 확장이 오래된 동작 보여줌
현상:.veb 파일을 교체하고 재설치한 후 확장이 여전히 오래된 코드 실행
원인: VillageSQL은 .veb 파일을 처음 로드할 때 {datadir}/.veb_expansion_cache/에 전개합니다. UNINSTALL EXTENSION을 실행하지 않고 새 .veb를 복사하면 서버는 이미 메모리에 로드된 이전 확장된 .so를 계속 사용합니다.
해결 방법: 항상 UNINSTALL → 교체 → INSTALL 순서를 따르세요:
veb_dir의 .veb 파일을 교체하고 재설치합니다:
확장 제거 불가
오류:Cannot uninstall extension: types in use
해결 방법:
라이브러리 로딩 오류
오류:Cannot load library: undefined symbol
원인:
- 라이브러리 종속성 누락
- ABI 호환성 불일치
- 잘못된 MySQL 버전
확장 이름 검증 오류
오류:Failed to load VEF extension 'extension_name' 및 로그 메시지 Extension name mismatch
원인: manifest.json의 확장 이름이 VEB 파일 이름과 일치하지 않음.
디버그 단계:
-
VEB 파일 이름이 매니페스트와 일치하는지 확인:
-
manifest.json의 name 필드 확인:
- VEB 파일 이름:
my_extension.veb - manifest.json:
"name": "my_extension"
- 매니페스트에 하이픈 사용:
"name": "my-extension"❌ - VEB 파일 이름 불일치:
my-extension.veb대"name": "my_extension"❌
사용자 정의 유형 비교 오류
오류:Cannot compare types X and Y in =
원인: 비교 양쪽 모두 사용자 정의 유형이지만 서로 다른 유형 또는 확장에서 유래합니다.
오류:
Unable to implicitly cast a non-custom type during compare with a custom type in =
원인: 비교의 한쪽은 사용자 정의 유형 열이고 다른 쪽은 해당 유형으로 자동 변환할 수 없는 값(리터럴 또는 열).
확장 사용 모니터링
쿼리 성능
performance_schema를 사용해 VDF 실행 시간 추적:사용자 정의 유형 사용
사용자 정의 유형을 사용하는 테이블 추적:확장 업데이트
새로운 버전으로 확장을 업데이트하려면 수동 업데이트 프로세스를 사용합니다:ALTER EXTENSION UPDATE은 아직 지원되지 않으며 향후 릴리스에서 계획됨.
수동 업데이트 프로세스
-
현재 버전 제거:
-
.veb 파일 교체:
-
새 버전 설치:
-
업데이트 확인:
정리
고아 확장 디렉터리 제거
VillageSQL은.veb 파일을 {datadir}/.veb_expansion_cache/{name}/{sha256}/로 전개합니다. 오래된 버전이 시간이 지나 누적됩니다.
서버 재시작 시 고립된 확장 디렉터리 자동 정리.
복제
사용자 정의 유형은 ROW 형식의 binlog를 요구합니다. STATEMENT 및 MIXED 모드는 사용자 정의 유형 열을 가진 테이블에 지원되지 않습니다. INSERT, UPDATE, DELETE, ALTER TABLE 작업은 ROW 형식에서 정상적으로 복제됩니다.INSTALL EXTENSION은 복제되지 않습니다 — 각 서버가 자체 확장을 관리합니다. 복제 시작 전에 모든 복제본에 동일한 버전으로 확장을 설치하세요. 서버는 정확한 버전 일치를 강제하며, 버전 불일치 시 복제가 중단됩니다.
복제본이 인식하지 못하는 사용자 정의 유형을 만나면 DDL 문(statement)에서 복제가 중단됩니다 — CREATE TABLE 또는 ALTER TABLE에서 종속 DML이 적용되기 전에 중단됩니다. 올바른 확장 버전을 설치한 후 복제를 재개합니다:
mysqldump은 출력에 전체 이름이 지정된(fully qualified) 사용자 정의 유형 이름을 유지합니다. 확장이 대상 서버에 설치된 경우 로직 복원이 정상적으로 작동합니다.
Docker와 확장 사용
VillageSQL을 Docker에서 실행할 때, 호스트에서.veb 파일을 추가할 수 있도록 로컬 디렉터리를 veb_dir로 마운트합니다.
Docker Compose 예시:
./extensions/에 .veb 파일을 복사한 후 SQL에서 설치합니다:
도움 요청
이 문서에 포함되지 않은 문제에 직면했을 때:- 오류 로그 확인: 대부분의 확장 오류는 세부 정보와 함께 로깅됨
- 확장 문서 검토: 확장별 문제 해결 방법이 있을 수 있음
- Discord에서 문의: VillageSQL Discord에 가입
- 이슈 제출: GitHub Issues에서 버그 보고
다음 단계
시스템 참조
시스템 테이블 및 뷰 쿼리
확장 제거
확장 안전하게 제거
확장 아키텍처
내부 구조 이해

