Skip to main content
VillageSQL Server 인스턴스를 실행하고, 연결한 후 확장 시스템을 사용해 보세요.

단계 1: VillageSQL 설치

옵션 A: Docker (권장)

호스트 설치 없이 컨테이너에서 VillageSQL을 실행합니다:
이미지 태그는 코드베이스, VillageSQL 버전, 아키텍처를 나타냅니다. 위 명령은 아키텍처를 uname 에서 읽습니다. PowerShell 에서는 접미사를 직접 입력하세요. Intel 과 AMD 는 -amd64, ARM 은 -arm64 입니다.

옵션 B: 쉘 스크립트

공식 설치 스크립트를 사용하여 직접 머신에 VillageSQL을 설치합니다. 해당 스크립트는 플랫폼에 맞는 서버 바이너리를 다운로드하고 구성합니다.
스크립트는 세 가지를 묻습니다. 어떤 코드베이스를 설치할지, 어떤 방법으로 설치할지, 어떤 버전을 설치할지입니다. 첫 번째 질문에서 MySQL 9.7 을 선택하면 이 문서가 설명하는 서버가 설치됩니다. 질문에 답할 터미널이 없는 환경(CI 작업, Dockerfile, AI 에이전트)에서는 답을 환경 변수로 전달하세요. 파이프의 bash 쪽에 지정합니다.
VSQL_CODEBASEmysql-8.4, percona-8.4, mysql-9.7 을 받습니다. INSTALL_METHODdocker, prebuilt, source 를 받습니다. 소스 빌드는 VSQL_VERSION=stable|nightly|latest 도 받습니다. Docker 와 사전 빌드 바이너리 설치는 항상 안정 릴리스입니다. 스크립트를 실행하기 전에 확인하려면: curl -fsSL https://install.villagesql.com | less

옵션 C: 소스에서 빌드

개발 또는 맞춤 빌드를 위해, 최신 코드로 직접 컴파일하려면 소스에서 복제 및 빌드 가이드를 따르세요.

쉘 스크립트가 설정하는 것

쉘 스크립트(옵션 B)는 모든 것을 ~/.villagesql/ 아래에 설치하고 포트 3306에서 서버를 시작합니다. 중요한 위치는 다음과 같습니다: ~/.local/binPATH에 있으면, 스크립트는 단축 명령도 추가합니다: villagesql(클라이언트), villagesql-server(서버), villagesql-admin(관리 도구). Docker(옵션 A)와 수동 소스 빌드는 ~/.villagesql/를 만들지 않습니다 — Docker는 데이터를 컨테이너 안에 보관합니다.

단계 2: 서버에 연결

표준 MySQL 클라이언트로 연결합니다. 기본값인 localhost 대신 -h 127.0.0.1을 사용하세요. localhost를 쓰면 클라이언트가 Unix 소켓을 찾는데, 서버가 Docker에서 실행 중일 때는 그 소켓에 접근할 수 없으므로 TCP로 연결하세요.
  • Docker(옵션 A): 컨테이너는 빈 root 비밀번호로 시작합니다 — 비밀번호 프롬프트에서 Enter를 누르세요.
  • 쉘 스크립트(옵션 B): 생성된 root 비밀번호는 ~/.villagesql/credentials.txt에 저장되어 있습니다.

단계 3: 첫 번째 확장 설치

INSTALL EXTENSION <name>은 서버의 VEB 디렉터리에서 <name>.veb를 찾습니다 — 그 위치는 SHOW VARIABLES LIKE 'veb_dir';로 확인할 수 있습니다. Docker(옵션 A)나 쉘 스크립트(옵션 B)로 설치했다면, .veb 파일 세트가 이미 veb_dir에 들어 있습니다 — 다운로드하거나 복사할 필요가 없습니다. 그곳에는 두 종류의 확장이 제공됩니다:
  • 확장. 예를 들어 vsql_uuid(UUID 타입과 생성기)와 번들 확장 목록에 있는 다른 확장들입니다.
  • vsql_complexvsql_simple은 확장 프레임워크의 동작 방식을 보여주기 위해 이 문서의 다른 곳(C++ 확장 예제)에서 사용되는 참조용 확장입니다.
VillageSQL을 소스에서 빌드했다면(옵션 C), vsql_complexvsql_simple도 이미 veb_dir에 들어 있습니다 — make install이 이들을 무조건 빌드하기 때문입니다. 하지만 vsql_uuid와 다른 확장들은 그렇지 않습니다: 이들은 별도의 저장소에 있으며 직접 빌드하고 설치해야 합니다. 옵션 C를 사용했다면, 계속하기 전에 vsql-uuid를 클론해서 빌드하거나, 대신 vsql_complex를 사용해 건너뛰어도 됩니다 — 자세한 내용은 확장 설치를 참조하세요. 네이티브 UUID 생성과 UUID 열 타입을 추가하려면 vsql_uuid 확장을 설치합니다:
설치 확인:
vsql_uuid가 목록에 표시되어야 합니다. 자세한 내용은 확장 설치를 참조하세요.

단계 4: 확장된 데이터 타입 사용

이제 확장이 활성화되었으므로, 테이블에서 UUID 타입을 네이티브 타입처럼 사용할 수 있습니다. 각 표준 버전에 대한 생성기 — UUID_V1(), UUID_V1MC(), UUID_V3(), UUID_V4(), UUID_V5(), UUID_V6(), UUID_V7()(UUID_V2()는 없습니다) — 와 저장된 값을 조사하는 함수가 함께 제공됩니다. 아래 예제는 v7을 사용합니다. v7 값은 타임스탬프가 내장되어 있어 1밀리초 이상 간격으로 생성되면 생성 시간 순으로 정렬됩니다. 같은 밀리초 안에 생성된 값은 호출 순서가 아니라 임의 비트에 따라 정렬됩니다. 즉, BINARY(16) 생성을 직접 구현하지 않고도 순차적으로 정렬되는 키를 얻을 수 있습니다.
확장 제거 방법:

서버 중지 및 재시작

서버는 컨테이너(Docker)나 백그라운드 프로세스(쉘 설치)를 제어하여 중지하고 시작합니다 — 데이터베이스도 그에 따라 함께 올라오고 내려갑니다.
  • Docker(옵션 A): docker stop vsql은 서버를 중지하고, docker start vsql은 서버를 다시 시작합니다.
  • 쉘 스크립트(옵션 B): 데이터 디렉터리, 소켓, 포트가 이미 채워진 시작, 중지, 연결 명령이 ~/.villagesql/credentials.txt에 있습니다.

다음 단계

VillageSQL을 실행하고 확장 시스템을 확인한 후, 다음을 탐색해 보세요:

확장 관리

다른 확장을 설치하고 관리하는 방법을 배웁니다.

확장 만들기

VillageSQL용 자체 확장을 구축하는 방법을 배웁니다.

업그레이드 가이드

이전 버전에서 업그레이드하거나 MySQL에서 마이그레이션하는 방법.

문제 해결

서버 시작 안됨

흔한 문제:
  • 포트 3306이 이미 사용 중: 서버를 다른 포트로 구성하세요
  • 권한: 파일이 읽기/실행 가능하도록 확인하세요