> ## 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에서 업그레이드하기

> 업스트림 MySQL에서 VillageSQL로 업그레이드하는 단계별 가이드입니다.

> [card] [VillageSQL is a drop-in replacement for MySQL with extensions.](https://villagesql.com/docs/en/8.4/stable/install-server.md)
>
> All examples on this page work on VillageSQL. Install Now →

VillageSQL Server는 MySQL의 드롭인 대체품입니다. 서드파티 플러그인이 없는 평범한 단일 인스턴스 MySQL 8.4 설치라면, VillageSQL로 마이그레이션하는 것은 기능적으로 마이너 버전 업그레이드(예: 8.4.5에서 8.4.6)와 같고, 기존 데이터를 보존합니다. 비표준 플러그인에 의존하는 것은 무엇이든 복사본에서 먼저 테스트해야 합니다.

## 사전 요구 사항

* **VillageSQL 바이너리**: VillageSQL 바이너리를 준비하세요(소스에서 컴파일하거나 다운로드).
* **MySQL 버전**: VillageSQL은 MySQL 8.4 LTS를 기반으로 합니다. MySQL 8.4에서 업그레이드하는 것이 지원되는 경로입니다.

> [!WARNING]
>
> **업그레이드를 수행하기 전에 항상 데이터를 백업하세요.**
> 이 과정은 안전하도록 설계되었지만, 데이터베이스 업그레이드에는 항상 위험이 따릅니다.

## 1단계: 데이터 백업

시스템 파일이나 서비스를 건드리기 전에, 데이터베이스의 전체 백업을 만드세요.

### 옵션 A: 논리 백업(mysqldump)

모든 데이터베이스의 SQL 덤프를 만듭니다. 가장 안전하고 이식성이 높은 방법입니다.

```bash theme={null}
mysqldump -u root -p --all-databases --events --routines --triggers > full_backup.sql
```

### 옵션 B: 물리 백업(데이터 디렉터리)

데이터 세트가 크면, 서버를 중지하고 데이터 디렉터리를 복사하세요.

```bash theme={null}
# Stop the server first (see Step 2)
cp -r /var/lib/mysql /var/lib/mysql-backup
```

## 2단계: MySQL 서버 중지

데이터 파일의 잠금을 해제하기 위해 현재 실행 중인 MySQL 서버 인스턴스를 중지하세요.

**Systemd 사용(Linux):**

```bash theme={null}
sudo systemctl stop mysql
# OR
sudo systemctl stop mysqld
```

**SysV Init 사용:**

```bash theme={null}
sudo service mysql stop
```

**수동 설치:**

```bash theme={null}
mysqladmin -u root -p shutdown
```

## 3단계: 바이너리 교체

업그레이드의 핵심은 실행 파일(`mysqld`, `mysql` 등)을 업스트림 MySQL 버전에서 VillageSQL 버전으로 바꾸는 것입니다.

### 방법 A: 설치 디렉터리 교체(권장)

MySQL을 tarball로 설치했다면(예: `/usr/local/mysql`에), 가장 깔끔한 방법은 VillageSQL을 그 옆에 설치하고 심볼릭 링크를 바꾸는 것입니다.

1. **VillageSQL을 압축 해제/설치**하세요. 새 디렉터리에, 예를 들어 `/usr/local/villagesql-8.4`에 설치합니다.
2. **심볼릭 링크를 업데이트**하세요:
   ```bash theme={null}
   # Remove link to old MySQL
   sudo unlink /usr/local/mysql

   # Link to VillageSQL
   sudo ln -s /usr/local/villagesql-8.4 /usr/local/mysql
   ```
3. **권한을 확인**하세요: 데이터베이스를 실행하는 사용자(보통 `mysql`)가 새 바이너리에 대한 실행 권한을 가지는지 확인합니다.

### 방법 B: 바이너리 덮어쓰기

VillageSQL을 소스에서 컴파일했고 시스템 설치(예: `/usr/bin` 또는 `/usr/local/bin`)를 덮어쓰고 싶다면:

```bash theme={null}
# Assuming you are in the VillageSQL build directory
sudo make install
```

> [!NOTE]
>
> MySQL을 패키지 관리자(`apt`, `yum`)로 설치했다면, 바이너리를 수동으로 덮어쓰는 것은 위험합니다. 패키지 관리자가 업데이트 중에 다시 덮어쓸 수 있기 때문입니다. `mysql-server` 패키지를 제거하거나(데이터 파일은 유지하세요!), 가능하다면 `update-alternatives`를 사용하는 것이 좋습니다.

## 4단계: 구성 확인

구성 파일(보통 `/etc/my.cnf` 또는 `/etc/mysql/my.cnf`)이 기존 데이터 디렉터리를 가리키는지 확인하세요.

```ini theme={null}
[mysqld]
datadir=/var/lib/mysql  # Should point to your EXISTING data
socket=/var/run/mysqld/mysqld.sock
```

VillageSQL은 표준 MySQL 구성 옵션을 사용하므로, 기존 `my.cnf`는 수정 없이 동작합니다.

## 5단계: VillageSQL 시작

서비스 관리자를 사용하거나 수동으로 서버를 시작하세요.

**Systemd 사용:**

```bash theme={null}
sudo systemctl start mysql
```

**수동 시작:**

```bash theme={null}
/usr/local/mysql/bin/mysqld_safe --user=mysql &
```

### 자동 업그레이드

시작할 때 VillageSQL은 데이터 파일이 이전 버전의 것인지 자동으로 감지하고 시스템 테이블에 필요한 업그레이드를 수행합니다.

오류 로그(보통 `/var/log/mysql/error.log`에 있거나 `datadir` 안에 있음)를 확인해 업그레이드가 성공적으로 끝났는지 확인하세요. 다음을 찾으세요:
`[System] [MY-013381] [Server] Server upgrade from '...' to '...' completed.`

## 6단계: 설치 확인

서버에 연결해 VillageSQL을 실행하고 있는지 확인하세요.

```bash theme={null}
mysql -u root -p
```

다음 쿼리를 실행하세요:

```sql theme={null}
SELECT @@version, @@version_comment;
```

이제 데이터가 온전한지 확인하고 `INSTALL EXTENSION` 같은 VillageSQL 전용 기능을 사용하기 시작할 수 있습니다.

## 문제 해결

* **"Data Dictionary Upgrade Failed"**: 서버가 시작을 거부하면, 다운그레이드(예: 8.4에서 8.0)를 시도하고 있거나 데이터 파일이 손상되었을 수 있습니다. 오류 로그를 확인하세요.
* **권한 오류**: `mysql` OS 사용자가 `datadir`와 새 VillageSQL 설치 디렉터리를 소유하는지 확인하세요.
  ```bash theme={null}
  sudo chown -R mysql:mysql /var/lib/mysql
  ```

## 함께 보기

* [MySQL의 스키마 마이그레이션](https://villagesql.com/docs/ko/guides/schema-migrations.md) — 업그레이드 후 안전한 DDL 변경 실행하기
* [MySQL 백업 전략](https://villagesql.com/docs/ko/guides/backup-strategies.md) — 업그레이드 전에 백업하기
* [Docker에서 MySQL 실행하기](https://villagesql.com/docs/ko/guides/mysql-on-docker.md) — 대신 컨테이너에서 MySQL이나 VillageSQL 실행하기
* [지원 종료 후 MySQL 8.0을 8.4로 업그레이드하기](https://villagesql.com/docs/ko/guides/mysql-80-eol-upgrade.md) — 아직 8.0이라면 먼저 8.4로 가기


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