> ## 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 Server를 시작해 보세요.

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

## 단계 1: VillageSQL 설치

### 옵션 A: Docker (권장)

호스트 설치 없이 컨테이너에서 VillageSQL을 실행합니다:

```bash theme={null}
docker run -d --name vsql -e MYSQL_ALLOW_EMPTY_PASSWORD=yes -p 3306:3306 villagesql/server:mysql-9.7_0.0.6-$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')
```

이미지 태그는 코드베이스, VillageSQL 버전, 아키텍처를 나타냅니다. 위 명령은 아키텍처를 `uname` 에서 읽습니다. PowerShell 에서는 접미사를 직접 입력하세요. Intel 과 AMD 는 `-amd64`, ARM 은 `-arm64` 입니다.

### 옵션 B: 쉘 스크립트

공식 설치 스크립트를 사용하여 직접 머신에 VillageSQL을 설치합니다. 해당 스크립트는 플랫폼에 맞는 서버 바이너리를 다운로드하고 구성합니다.

```bash theme={null}
curl -fsSL https://install.villagesql.com | bash
```

스크립트는 세 가지를 묻습니다. 어떤 코드베이스를 설치할지, 어떤 방법으로 설치할지, 어떤 버전을 설치할지입니다. 첫 번째 질문에서 **MySQL 9.7** 을 선택하면 이 문서가 설명하는 서버가 설치됩니다.

질문에 답할 터미널이 없는 환경(CI 작업, Dockerfile, AI 에이전트)에서는 답을 환경 변수로 전달하세요. 파이프의 `bash` 쪽에 지정합니다.

```bash theme={null}
curl -fsSL https://install.villagesql.com | \
  VSQL_CODEBASE=mysql-9.7 INSTALL_METHOD=prebuilt bash
```

`VSQL_CODEBASE` 는 `mysql-8.4`, `percona-8.4`, `mysql-9.7` 을 받습니다. `INSTALL_METHOD` 는 `docker`, `prebuilt`, `source` 를 받습니다. 소스 빌드는 `VSQL_VERSION=stable|nightly|latest` 도 받습니다. Docker 와 사전 빌드 바이너리 설치는 항상 안정 릴리스입니다.

스크립트를 실행하기 전에 확인하려면: `curl -fsSL https://install.villagesql.com | less`

### 옵션 C: 소스에서 빌드

개발 또는 맞춤 빌드를 위해, 최신 코드로 직접 컴파일하려면 [소스에서 복제 및 빌드 가이드](/docs/ko/mysql-9.7/stable/source)를 따르세요.

### 쉘 스크립트가 설정하는 것

쉘 스크립트(옵션 B)는 모든 것을 `~/.villagesql/` 아래에 설치하고 포트 3306에서 서버를 시작합니다. 중요한 위치는 다음과 같습니다:

| 경로                              | 설명                                                    |
| ------------------------------- | ----------------------------------------------------- |
| `~/.villagesql/credentials.txt` | 생성된 root 비밀번호와 바로 실행할 수 있는 시작, 중지, 연결 명령(본인만 읽을 수 있음) |
| `~/.villagesql/data/`           | 데이터베이스 데이터 디렉터리                                       |
| `~/.villagesql/mysql.sock`      | 서버 소켓                                                 |
| `~/.villagesql/mysql.log`       | 서버 오류 로그                                              |

`~/.local/bin`이 `PATH`에 있으면, 스크립트는 단축 명령도 추가합니다: `villagesql`(클라이언트), `villagesql-server`(서버), `villagesql-admin`(관리 도구).

Docker(옵션 A)와 수동 소스 빌드는 `~/.villagesql/`를 만들지 않습니다 — Docker는 데이터를 컨테이너 안에 보관합니다.

## 단계 2: 서버에 연결

표준 MySQL 클라이언트로 연결합니다. 기본값인 `localhost` 대신 `-h 127.0.0.1`을 사용하세요. `localhost`를 쓰면 클라이언트가 Unix 소켓을 찾는데, 서버가 Docker에서 실행 중일 때는 그 소켓에 접근할 수 없으므로 TCP로 연결하세요.

```bash theme={null}
mysql -h 127.0.0.1 -P 3306 -u root -p
```

* **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 타입과 생성기)와 [번들 확장 목록](https://github.com/villagesql/villagesql-server/blob/main/villagesql/dev_server/bundled_extensions.txt)에 있는 다른 확장들입니다.
* `vsql_complex`와 `vsql_simple`은 확장 프레임워크의 동작 방식을 보여주기 위해 이 문서의 다른 곳([C++ 확장 예제](/docs/ko/mysql-9.7/stable/examples))에서 사용되는 참조용 확장입니다.

VillageSQL을 소스에서 빌드했다면(옵션 C), `vsql_complex`와 `vsql_simple`도 이미 `veb_dir`에 들어 있습니다 — `make install`이 이들을 무조건 빌드하기 때문입니다. 하지만 `vsql_uuid`와 다른 확장들은 그렇지 않습니다: 이들은 별도의 저장소에 있으며 직접 빌드하고 설치해야 합니다. 옵션 C를 사용했다면, 계속하기 전에 [vsql-uuid](https://github.com/villagesql/vsql-uuid)를 클론해서 빌드하거나, 대신 `vsql_complex`를 사용해 건너뛰어도 됩니다 — 자세한 내용은 [확장 설치](/docs/ko/mysql-9.7/stable/install)를 참조하세요.

네이티브 UUID 생성과 `UUID` 열 타입을 추가하려면 `vsql_uuid` 확장을 설치합니다:

```sql theme={null}
INSTALL EXTENSION vsql_uuid;
```

설치 확인:

```sql theme={null}
SELECT * FROM INFORMATION_SCHEMA.EXTENSIONS;
```

`vsql_uuid`가 목록에 표시되어야 합니다.

자세한 내용은 [확장 설치](/docs/ko/mysql-9.7/stable/install)를 참조하세요.

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

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

```sql theme={null}
-- Create a database and use it
CREATE DATABASE demo;
USE demo;

-- Create a table with a UUID primary key
CREATE TABLE events (
    id UUID PRIMARY KEY,
    label VARCHAR(50)
);

-- Insert rows with generated v7 UUIDs
INSERT INTO events VALUES
    (UUID_V7(), 'signup'),
    (UUID_V7(), 'login'),
    (UUID_V7(), 'purchase');

-- v7 keys sort in creation order
SELECT id, label FROM events ORDER BY id;

-- Introspect the stored UUIDs
SELECT
    label,
    UUID_VERSION(id) AS version,
    UUID_TIMESTAMP(id) AS created_at
FROM events
ORDER BY id;
```

확장 제거 방법:

```sql theme={null}
UNINSTALL EXTENSION vsql_uuid;
```

## 서버 중지 및 재시작

서버는 컨테이너(Docker)나 백그라운드 프로세스(쉘 설치)를 제어하여 중지하고 시작합니다 — 데이터베이스도 그에 따라 함께 올라오고 내려갑니다.

* **Docker(옵션 A):** `docker stop vsql`은 서버를 중지하고, `docker start vsql`은 서버를 다시 시작합니다.
* **쉘 스크립트(옵션 B):** 데이터 디렉터리, 소켓, 포트가 이미 채워진 시작, 중지, 연결 명령이 `~/.villagesql/credentials.txt`에 있습니다.

## 다음 단계

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

<CardGroup cols={2}>
  <Card title="확장 관리" icon="puzzle-piece" href="/docs/ko/mysql-9.7/stable/managing">
    다른 확장을 설치하고 관리하는 방법을 배웁니다.
  </Card>

  <Card title="확장 만들기" icon="code" href="/docs/ko/mysql-9.7/stable/create">
    VillageSQL용 자체 확장을 구축하는 방법을 배웁니다.
  </Card>

  <Card title="업그레이드 가이드" icon="arrow-up" href="/docs/guides/upgrade">
    이전 버전에서 업그레이드하거나 MySQL에서 마이그레이션하는 방법.
  </Card>
</CardGroup>

## 문제 해결

### 서버 시작 안됨

흔한 문제:

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