> ## 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의 버전 관리 체계와 MySQL 호환성 매트릭스를 이해하세요.

## 개요

VillageSQL은 배포 및 업그레이드에 대한 정보 기반 결정을 도와주기 위해 명확한 버전 관리 및 호환성 정책을 따릅니다.

## VillageSQL 버전 관리

VillageSQL은 각 릴리스에서의 변경 사항의 성격과 영향을 전달하기 위해 [Semantic Versioning](https://semver.org/) (SemVer)을 사용합니다.

### 버전 형식

버전은 다음 형식을 따릅니다: **MAJOR.MINOR.PATCH**

```
0.0.1
│ │ │
│ │ └─ PATCH version
│ └─── MINOR version
└───── MAJOR version
```

### 버전 증가 규칙

* **MAJOR 버전** (예: 1.0.0 → 2.0.0): 코드 수정 또는 데이터베이스 마이그레이션을 요구할 수 있는 변경 사항
* **MINOR 버전** (예: 0.1.0 → 0.2.0): 호환성 유지 방식으로 추가된 새로운 기능 및 동작
* **PATCH 버전** (예: 0.0.1 → 0.0.2): 하위 호환성을 유지하는 버그 수정 및 경미한 개선

<Note>
  VillageSQL은 현재 1.0 미만 개발 단계(버전 0.x.x)에 있습니다. 이 단계에서는 플랫폼이 안정화될 때까지 API 및 확장 인터페이스가 더 자주 변경될 수 있습니다.
</Note>

### 개발 빌드

접미사가 프리릴리스인 버전(예: `0.0.4-dev`)은 개발 빌드입니다. 서버는 기본적으로 개발 빌드로 초기화된 데이터베이스에서 업그레이드를 차단합니다. 개발 빌드는 업그레이드 호환성에 대해 테스트되지 않았으며, 스키마 또는 프로토콜 변경을 포함할 수 있습니다.

이를 허용하려면 `--villagesql-allow-unsafe-dev-upgrade` 플래그와 함께 서버를 시작하세요:

```bash theme={null}
mysqld --villagesql-allow-unsafe-dev-upgrade --datadir=/path/to/data
```

플래그 없이 서버는 개발 버전 데이터베이스를 감지하면 오류로 종료합니다:

```
Upgrading from a development version (0.0.4-dev) is not allowed. Use --villagesql-allow-unsafe-dev-upgrade to permit this.
```

플래그와 함께 서버는 경고를 기록하고 계속 진행합니다:

```
Upgrading from a development version (0.0.4-dev); --villagesql-allow-unsafe-dev-upgrade was specified.
```

플래그가 지정되었으나 현재 버전이 개발 빌드가 아닌 경우 서버는 오류로 종료합니다:

```
--villagesql-allow-unsafe-dev-upgrade specified, but current version (0.0.3) is not a development version.
```

또는 스키마 업그레이드가 수행되지 않는 경우:

```
--villagesql-allow-unsafe-dev-upgrade specified, but no upgrade is being performed.
```

## 확장 호환성

VillageSQL 확장은 특정 버전에 종속적입니다. 한 버전의 VillageSQL용으로 빌드된 확장은 다른 버전과 호환되지 않을 수 있습니다.

VillageSQL을 업그레이드할 때:

1. 새 버전에 대한 확장 호환성 확인
2. 필요한 경우 확장 업데이트 또는 재빌드
3. 프로덕션 배포 전 개발 환경에서 확장 테스트

자세한 업그레이드 절차는 [업그레이드 가이드](/docs/guides/upgrade)를 참조하세요.

## 0.0.3에서의 SDK 변경 사항

**프로토콜 2 확장은 재빌드가 필요합니다.** VEF 프로토콜 3은 v0.0.4부터 안정적입니다. 서버는 이제 로드 시 프로토콜 2 확장을 거부합니다. 타입화된 래퍼(`StringArg`, `IntArg`, `StringResult` 등)를 사용하여 프로토콜 3 API에 맞춰 재빌드하세요.

**`vef_version_t::extra` 타입이 `const char*`로 수정되었습니다.** 0.0.3에서는 이 필드가 `unsigned char*`였습니다. 대부분의 확장은 직접 접근하지 않습니다. 이 필드는 SDK에서 `manifest.json`의 버전 필드로부터 채워집니다. 직접 접근하는 경우 0.0.4 SDK와 컴파일할 때 `(unsigned char *)` 캐스트를 제거하세요.