> ## 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.6-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.6-dev) is not allowed. Use --villagesql-allow-unsafe-dev-upgrade to permit this.
```

해당 플래그를 지정하면 서버는 경고를 기록하고 계속 진행합니다:

```
Upgrading from a development version (0.0.6-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.
```

### 최소 업그레이드

`--upgrade=MINIMAL` 플래그와 함께 서버를 시작하면 반드시 필요하지는 않은 업그레이드 단계를 건너뜁니다. VillageSQL 스키마 업그레이드는 건너뛰는 단계에 포함되지 않습니다. 서버 업그레이드가 필요한 상태에서 이 모드로 서버를 시작하면, 서버는 서버 업그레이드를 건너뛰었다는 경고를 기록한 다음, 저장된 VillageSQL 스키마 버전이 빌드 버전과 일치하지 않으면 VillageSQL 스키마 업그레이드를 실행합니다.

```bash theme={null}
mysqld --upgrade=MINIMAL --datadir=/path/to/data
```

이 모드에서 VillageSQL 스키마 업그레이드가 실패하면 서버는 시작을 중단합니다. 개발 빌드로 초기화된 데이터 디렉터리는 이 모드에서도 여전히 거부됩니다. 이를 허용하려면 `--villagesql-allow-unsafe-dev-upgrade` 플래그와 함께 시작하세요.

### 코드베이스 변경

모든 VillageSQL 버전은 코드베이스, 즉 서버가 빌드되는 기반이 되는 업스트림 포크에 연결되어 있습니다. 예를 들어 `mysql-9.7_0.0.6`은 `mysql-9.7` 코드베이스의 버전 0.0.6입니다. 서로 다른 코드베이스의 버전 번호는 비교할 수 없으므로, 코드베이스 간 이동은 지원되는 업그레이드가 아닙니다. 즉, `mysql-9.7_0.0.5`에서 `mysql-9.7_0.0.6`으로는 업그레이드할 수 있지만, `mysql-9.7_0.0.6`에서 `mysql-8.4_0.0.6`으로는 업그레이드할 수 없습니다.

데이터 디렉터리는 이를 생성한 서버의 코드베이스를 [`villagesql_schema_version`](/docs/ko/mysql-9.7/stable/reference#villagesql_schema_version)으로 기록합니다. 다른 코드베이스에서 빌드된 서버를 해당 데이터 디렉터리에서 시작하면 시작이 실패하고 오류 로그에는 `villagesql_schema_version`과 동일한 `{codebase}_{version}` 형식으로 두 버전이 모두 표시됩니다:

```
Cannot upgrade the VillageSQL schema across code bases: this data directory was created by a <data-directory-version> build, but this server is a <server-version> build. Use the original server binary for this data directory.
```

데이터 디렉터리를 코드베이스 간에 이동하는 지원되는 방법은 없습니다. 해당 데이터 디렉터리를 생성한 코드베이스의 서버 바이너리를 계속 사용하세요. `--upgrade=MINIMAL`은 이 검사를 우회하지 않습니다.

## 확장 호환성

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

VillageSQL을 업그레이드할 때:

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

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