> ## 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.

# MySQL용 vsql_uuid 확장 기능

> vsql_uuid 확장 기능은 네이티브 16바이트 uuid 열 유형을 MySQL에 추가하고 SQL에서 버전 1, 3, 4, 5, 6, 7 UUID를 생성합니다.

MySQL은 UUID를 텍스트로 저장하거나, 직접 변환해야 하는 `BINARY(16)`으로
저장합니다. `vsql_uuid`는 16바이트를 저장하고, 익숙한 36자 형식으로 출력하며,
자체 비교 규칙으로 정렬되는 진짜 `uuid` 열 유형을 추가합니다. 또한 버전 1, 3,
4, 5, 6, 7을 생성합니다. MySQL 자체의 `UUID()`는 버전 1만 생성합니다.

| | |
| - | - |
| **관리자** | VillageSQL |
| **소스 및 전체 문서** | [villagesql/vsql-uuid](https://github.com/villagesql/vsql-uuid) |
| **라이선스** | GPL-2.0 |

## 설치

설치 스크립트, Docker 이미지 또는 릴리스 tarball로 VillageSQL을 설치했다면
`vsql_uuid.veb`는 이미 서버의 `lib/veb/` 디렉터리에 있습니다. 문 하나로 서버에
설치하세요:

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

설치되었는지 확인합니다:

```sql theme={null}
SELECT EXTENSION_NAME
FROM INFORMATION_SCHEMA.EXTENSIONS
WHERE EXTENSION_NAME = 'vsql_uuid';
```

```
+----------------+
| EXTENSION_NAME |
+----------------+
| vsql_uuid      |
+----------------+
```

직접 빌드하려면 [저장소](https://github.com/villagesql/vsql-uuid)의 빌드
지침을 따르세요.

## 추가되는 기능

### uuid 유형

열을 `uuid`로 선언합니다. 16바이트를 차지하며 기본 키로 사용할 수 있습니다.

```sql theme={null}
CREATE TABLE orders (
    id     uuid PRIMARY KEY,
    placed DATETIME,
    total  DECIMAL(8,2)
);
```

### 함수

| 함수 | 반환값 | 설명 |
| - | - | - |
| `UUID_V1()` | `uuid` | 시간 기반, 호스트 MAC 주소 사용 |
| `UUID_V1MC()` | `uuid` | 시간 기반, MAC 대신 무작위 멀티캐스트 주소 사용 |
| `UUID_V3(namespace, name)` | `uuid` | 이름 기반, MD5 |
| `UUID_V4()` | `uuid` | 무작위 |
| `UUID_V5(namespace, name)` | `uuid` | 이름 기반, SHA-1 |
| `UUID_V6()` | `uuid` | 시간 순서, 연결 내에서 단조 증가 |
| `UUID_V7()` | `uuid` | Unix 밀리초 타임스탬프 기준 시간 순서 |
| `UUID_NIL()`, `UUID_MAX()` | `uuid` | 모든 비트가 0인 값과 모든 비트가 1인 값 |
| `UUID_NS_DNS()`, `UUID_NS_URL()`, `UUID_NS_OID()`, `UUID_NS_X500()` | text | `UUID_V3`와 `UUID_V5`용 RFC 9562 네임스페이스 상수 |
| `UUID_IS_VALID(s)` | int | 문자열이 `uuid` 열에 허용되면 1, 아니면 0 |
| `UUID_VERSION(u)` | int | 버전 니블 |
| `UUID_TIMESTAMP(u)` | text | 내장된 시간을 UTC 기준 `'YYYY-MM-DD HH:MM:SS'` 형식으로 반환, 시간이 없는 버전은 NULL |
| `UUID_EPOCH(u)` | int | 같은 시간을 Unix 초로 반환 |
| `UUID_COMPARE(a, b)` | int | -1, 0 또는 1 |

## 예제

버전 7 식별자를 기본 키로 사용하면 나중에 쓴 행이 먼저 쓴 행 뒤에 정렬됩니다.
그런 다음 버전을 다시 읽어 봅니다:

```sql theme={null}
INSERT INTO orders VALUES (UUID_V7(), NOW(), 42.50);
DO SLEEP(0.01);
INSERT INTO orders VALUES (UUID_V7(), NOW(), 19.99);

SELECT UUID_VERSION(id) AS version, total FROM orders ORDER BY id;
```

```
+---------+-------+
| version | total |
+---------+-------+
|       7 | 42.50 |
|       7 | 19.99 |
+---------+-------+
```

이름에서 고정된 식별자를 만듭니다:

```sql theme={null}
SELECT UUID_V5(UUID_NS_DNS(), 'villagesql.com') AS dns_uuid;
```

```
+--------------------------------------+
| dns_uuid                             |
+--------------------------------------+
| fc51a94b-5261-5a4c-a5ec-48199b58d67b |
+--------------------------------------+
```

> [!NOTE]
>
> 위의 정렬 순서는 밀리초 단위를 넘어서는 경우에만 보장됩니다. 버전 7은 앞부분에
> 밀리초 타임스탬프를 두고 나머지는 카운터 없이 무작위로 채우므로, 같은 밀리초에
> 생성된 두 값은 서로 무작위 순서로 정렬됩니다. 그래서 예제에서 두 행을 별도의
> 문으로 삽입합니다. 더 세밀한 순서가 필요하면 `UUID_V6()`를 사용하세요.

> [!NOTE]
>
> `uuid` 열은 문자열 리터럴은 받지만 문자열 표현식은 받지 않습니다. 따라서
> `INSERT INTO orders VALUES ('550e8400-e29b-41d4-a716-446655440000', ...)`는
> 동작하지만, `INSERT INTO orders VALUES (UUID(), ...)`는
> `ERROR 3219 (HY000): Incorrect uuid value: cannot implicitly cast string
>     expression. Use explicit conversion for column 'id' at row 1` 오류로
> 실패합니다. 대신 위의 함수 중 하나로 값을 생성하세요.

## 참고 항목

* [MySQL의 UUID](https://villagesql.com/docs/en/guides/uuids.md) — 각 버전의 용도와 선택 기준
* [기본 키 전략](https://villagesql.com/docs/en/guides/primary-key-strategies.md) — UUID 키가 도움이 되는 곳과 비용이 드는 곳
* [확장 기능 설치](https://villagesql.com/docs/ko/extensions/install.md) — `INSTALL EXTENSION`의 동작 방식과 서버가 번들을 찾는 위치
* [사용 가능한 확장 기능](https://villagesql.com/docs/ko/extensions/catalog) — 전체 카탈로그
* [villagesql/vsql-uuid](https://github.com/villagesql/vsql-uuid) — 소스, 빌드 지침, 알려진 제한 사항


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.