Skip to main content

설치된 확장 보기

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 파일 이름과 일치하지 않음. 디버그 단계:
  1. VEB 파일 이름이 매니페스트와 일치하는지 확인:
  2. 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 = 원인: 비교의 한쪽은 사용자 정의 유형 열이고 다른 쪽은 해당 유형으로 자동 변환할 수 없는 값(리터럴 또는 열).
해결 방법: 문자열 리터럴은 유형의 encode 함수를 사용해 자동으로 사용자 정의 유형으로 변환됩니다. 다른 유형(정수, 부동소수점)의 경우 명시적 변환 함수 사용:

확장 사용 모니터링

쿼리 성능

performance_schema를 사용해 VDF 실행 시간 추적:

사용자 정의 유형 사용

사용자 정의 유형을 사용하는 테이블 추적:

확장 업데이트

새로운 버전으로 확장을 업데이트하려면 수동 업데이트 프로세스를 사용합니다:
ALTER EXTENSION UPDATE은 아직 지원되지 않으며 향후 릴리스에서 계획됨.

수동 업데이트 프로세스

  1. 현재 버전 제거:
  2. .veb 파일 교체:
  3. 새 버전 설치:
  4. 업데이트 확인:
데이터 안전성: 테이블이 확장의 사용자 정의 유형을 사용하는 경우, 제거 전에 해당 테이블을 삭제하거나 수정해야 합니다. 먼저 데이터를 백업하세요.
예시:

정리

고아 확장 디렉터리 제거

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) 사용자 정의 유형 이름을 유지합니다. 확장이 대상 서버에 설치된 경우 로직 복원이 정상적으로 작동합니다.
Clone 플러그인, XtraBackup, InnoDB 클러스터/그룹 복제와의 동작은 아직 테스트되지 않았습니다. 프로덕션 환경에 적용하기 전에 복원 경로를 테스트하세요.

Docker와 확장 사용

VillageSQL을 Docker에서 실행할 때, 호스트에서 .veb 파일을 추가할 수 있도록 로컬 디렉터리를 veb_dir로 마운트합니다. Docker Compose 예시:
호스트의 ./extensions/.veb 파일을 복사한 후 SQL에서 설치합니다:
실행 중인 서버가 사용하는 디렉터리 확인:

도움 요청

이 문서에 포함되지 않은 문제에 직면했을 때:
  1. 오류 로그 확인: 대부분의 확장 오류는 세부 정보와 함께 로깅됨
  2. 확장 문서 검토: 확장별 문제 해결 방법이 있을 수 있음
  3. Discord에서 문의: VillageSQL Discord에 가입
  4. 이슈 제출: GitHub Issues에서 버그 보고

다음 단계

시스템 참조

시스템 테이블 및 뷰 쿼리

확장 제거

확장 안전하게 제거

확장 아키텍처

내부 구조 이해