docs: 배포본에 없는 CLI 대신 관리자 DB업그레이드 절차 안내
This commit is contained in:
whitedot
@@ -67,13 +67,7 @@ cd gnuboard5
|
||||
|
||||
### 기존 설치 업데이트
|
||||
|
||||
소스 코드를 업데이트한 뒤 데이터베이스 변경이 포함된 버전은 관리자 메뉴의 **환경설정 → DB업그레이드**에서 변경 내용을 확인하고 명시적으로 실행합니다. 배포 자동화에서는 CLI 실행을 권장합니다.
|
||||
|
||||
```bash
|
||||
php bin/db-migrate.php status
|
||||
php bin/db-migrate.php migrate
|
||||
php bin/check-runtime-ddl.php
|
||||
```
|
||||
소스 코드를 업데이트한 뒤 데이터베이스 변경이 포함된 버전은 관리자 메뉴의 **환경설정 → DB업그레이드**에서 변경 내용을 확인하고 명시적으로 실행합니다.
|
||||
|
||||
운영 절차와 마이그레이션 작성 규칙은 [데이터베이스 마이그레이션 문서](docs/database-migrations.md)를 확인하십시오.
|
||||
|
||||
|
||||
@@ -16,25 +16,13 @@
|
||||
|
||||
## 실행 방법
|
||||
|
||||
CLI를 권장한다.
|
||||
|
||||
```bash
|
||||
php bin/db-migrate.php status
|
||||
php bin/db-migrate.php record-existing
|
||||
php bin/db-migrate.php migrate
|
||||
php bin/db-migrate.php migrate 20260416_001_member_auto_login
|
||||
php bin/check-migration-schema.php
|
||||
php bin/check-migration-runner.php
|
||||
php bin/check-migration-existing.php
|
||||
php bin/check-shop-install.php
|
||||
php bin/check-runtime-ddl.php
|
||||
```
|
||||
공식 배포본에서는 관리자 화면으로 실행한다. `bin/`은 Git 추적 및 배포 대상에서 제외한 로컬 운영·검증 스크립트 디렉터리이므로 아래 검증 스크립트 설명은 해당 파일을 별도로 보유한 개발 환경에만 적용한다.
|
||||
|
||||
웹에서는 최고관리자가 **환경설정 → DB업그레이드**에서 전체 또는 특정 마이그레이션을 명시적으로 실행할 수 있다. 성공한 마이그레이션의 개별 실행 버튼은 비활성화되며, 전체 실행에서도 성공 이력과 체크섬이 일치하는 항목은 건너뛴다. 화면 조회만으로는 DDL이 실행되지 않는다.
|
||||
|
||||
기존 설치본처럼 이력이 비어 있으면 상태 조회 시 실제 실행 조건을 읽기 전용으로 검사한다. 일부 이력이 있는 경우에도 미기록 항목은 검사한다. 현재 조건에서 모든 SQL을 건너뛰는 항목은 `실행 불필요 (미기록)`로 표시하며 개별 실행 버튼을 비활성화한다. 이는 과거 실행 성공이나 컬럼 정의 전체의 일치를 보증하는 표시가 아니다. 게시판별 컬럼도 검사하며, 조건 없는 DDL·데이터 보정·검사 오류는 대기로 남긴다. 조회 요청 안에서는 메타데이터를 공유해 중복 조회를 줄이고, 다음 요청에서는 다시 검사하므로 외부 변경이나 선행 작업 후 상태가 반영된다.
|
||||
|
||||
`기존 상태 확인 이력 등록` 버튼 또는 CLI `record-existing`은 실행 잠금 아래 다시 검사하고, 처음부터 연속해서 실행 불필요한 미기록 항목만 성공 이력으로 등록한다. 등록 시각은 확인한 시각이며 실제 과거 적용 시각이 아니다. 이 동작은 필요하면 이력 테이블을 생성하지만, 마이그레이션 SQL 자체는 실행하지 않는다. 변경이 필요한 항목이나 실패 이력을 만나면 중단하며, 성공 이력의 체크섬 불일치는 오류로 처리한다. 화면 진입만으로 등록하지 않으며 웹 등록은 최고관리자 권한과 POST 토큰 검증을 거친다. 전체 마이그레이션 실행도 기존처럼 실행 조건을 다시 확인하고 건너뛴 항목의 이력을 함께 기록한다.
|
||||
`기존 상태 확인 이력 등록` 버튼은 실행 잠금 아래 다시 검사하고, 처음부터 연속해서 실행 불필요한 미기록 항목만 성공 이력으로 등록한다. 등록 시각은 확인한 시각이며 실제 과거 적용 시각이 아니다. 이 동작은 필요하면 이력 테이블을 생성하지만, 마이그레이션 SQL 자체는 실행하지 않는다. 변경이 필요한 항목이나 실패 이력을 만나면 중단하며, 성공 이력의 체크섬 불일치는 오류로 처리한다. 화면 진입만으로 등록하지 않으며 웹 등록은 최고관리자 권한과 POST 토큰 검증을 거친다. 전체 마이그레이션 실행도 기존처럼 실행 조건을 다시 확인하고 건너뛴 항목의 이력을 함께 기록한다.
|
||||
|
||||
전체 실행은 파일명 오름차순, 즉 오래된 마이그레이션부터 처리하며 하나가 실패하면 이후 실행을 중단한다. 개별 실행도 대상보다 앞선 모든 마이그레이션의 성공 이력과 체크섬이 유효해야 한다. 선행 항목이 누락·실패·변경된 경우 대상만 건너뛰기 성공으로 기록하지 않고 오류로 차단한다.
|
||||
|
||||
@@ -61,7 +49,7 @@ php bin/check-runtime-ddl.php
|
||||
|
||||
## 권한과 배포
|
||||
|
||||
운영 환경에서는 웹 런타임 DB 계정에서 DDL 권한을 제거하고, 배포 단계에서 별도의 권한을 가진 계정으로 CLI 마이그레이션을 실행하는 구성을 권장한다. 웹 실행 기능을 사용하는 환경은 실행 시에만 필요한 DDL 권한이 있어야 한다.
|
||||
관리자 DB업그레이드 실행 시에는 DB 계정에 필요한 DDL 권한이 있어야 한다. 평상시 DDL 권한을 제거한 운영 환경에서는 업그레이드 시점에 필요한 권한을 부여하고, 완료 후 운영 권한으로 복원한다.
|
||||
|
||||
배포 전에는 백업과 테이블 크기, 예상 잠금 시간을 확인한다. MySQL 계열 DB의 DDL은 트랜잭션으로 완전히 되돌릴 수 없으므로 실패한 마이그레이션의 오류를 확인하고 수동 복구 후 재실행한다.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user