influence/.cursor/rules/mariadb-ddl-rules.mdc

# MariaDB 호환 DDL 스크립트 작성 규칙

## 📋 기본 원칙

**모든 DDL 스크립트는 MariaDB 호환성을 최우선으로 작성한다.**

## 🔧 MariaDB 전용 구문 규칙

### 1. 컬럼 삭제 (DROP COLUMN)

#### ❌ 사용 금지 (MySQL 8.0+ 전용)
```sql
ALTER TABLE table_name DROP COLUMN IF EXISTS column_name;
```

#### ❌ 문제 있는 동적 SQL (MariaDB에서 불안정)
```sql
-- 이 방식은 MariaDB에서 PREPARE/EXECUTE 오류 발생 가능
SET @sql = (SELECT IF(...));
PREPARE stmt FROM @sql;
EXECUTE stmt;
DEALLOCATE PREPARE stmt;
```

#### ✅ MariaDB 안전 방식 (권장)
```sql
-- 1. 컬럼 존재 여부 확인 (정보성)
SELECT COUNT(*) as column_exists 
FROM INFORMATION_SCHEMA.COLUMNS 
WHERE TABLE_SCHEMA = 'database_name' 
  AND TABLE_NAME = 'table_name' 
  AND COLUMN_NAME = 'column_name';

-- 2. 사용자 안내 메시지 제공
SELECT 
    CASE 
        WHEN COUNT(*) > 0 THEN '⚠️ 컬럼이 존재합니다. 다음 명령을 별도로 실행하세요: ALTER TABLE table_name DROP COLUMN column_name;'
        ELSE '✅ 컬럼이 존재하지 않습니다.'
    END as column_check
FROM INFORMATION_SCHEMA.COLUMNS 
WHERE TABLE_SCHEMA = 'database_name' 
  AND TABLE_NAME = 'table_name' 
  AND COLUMN_NAME = 'column_name';

-- 3. 주석으로 수동 실행 명령 제공
-- ALTER TABLE `table_name` DROP COLUMN `column_name`;
```

### 2. 인덱스 생성

#### ✅ 권장 방식
```sql
-- MariaDB에서 지원하는 안전한 인덱스 생성
CREATE INDEX IF NOT EXISTS `index_name` ON `table_name` (`column1`, `column2`);
```

#### ❌ 주의사항
```sql
-- MariaDB 오래된 버전에서는 IF NOT EXISTS 미지원할 수 있음
-- 이 경우 DROP INDEX IF EXISTS 후 CREATE INDEX 사용
DROP INDEX IF EXISTS `index_name` ON `table_name`;
CREATE INDEX `index_name` ON `table_name` (`column1`, `column2`);
```

### 3. 외래키 제약조건

#### ✅ 안전한 외래키 처리
```sql
-- 외래키 체크 임시 비활성화 (TRUNCATE 시 필요)
SET FOREIGN_KEY_CHECKS = 0;

-- 작업 수행
TRUNCATE TABLE `child_table`;
TRUNCATE TABLE `parent_table`;

-- 외래키 체크 재활성화
SET FOREIGN_KEY_CHECKS = 1;
```

### 4. 테이블 수정 (ALTER TABLE)

#### ✅ 단계별 안전한 수정
```sql
-- 1. 백업 테이블 생성
CREATE TABLE IF NOT EXISTS `table_backup_YYYYMMDD` AS 
SELECT * FROM `original_table`;

-- 2. 컬럼 추가
ALTER TABLE `original_table` 
ADD COLUMN IF NOT EXISTS `new_column` varchar(50) DEFAULT NULL;

-- 3. 컬럼 수정 (MariaDB 호환)
ALTER TABLE `original_table` 
MODIFY COLUMN `existing_column` varchar(100) NOT NULL;
```

### 5. 데이터 타입

#### ✅ MariaDB 호환 데이터 타입
```sql
-- 문자열
varchar(255) COLLATE utf8mb4_unicode_ci
text COLLATE utf8mb4_unicode_ci

-- 숫자
bigint(20)
int(11)
decimal(10,2)

-- 날짜/시간
datetime DEFAULT current_timestamp()
timestamp DEFAULT current_timestamp() ON UPDATE current_timestamp()

-- 불린
char(1) DEFAULT 'N'  -- 'Y'/'N' 방식 권장
```

## 📝 DDL 스크립트 템플릿

### 기본 구조
```sql
-- ============================================================================
-- [작업 설명]
-- 작성일: YYYY-MM-DD
-- 목적: [목적 설명]
-- 호환성: MariaDB 10.x+
-- ============================================================================

USE database_name;

-- 1. 백업 생성 (필수)
CREATE TABLE IF NOT EXISTS `backup_table_YYYYMMDD` AS 
SELECT * FROM `original_table`;

-- 2. 외래키 체크 비활성화 (필요시)
SET FOREIGN_KEY_CHECKS = 0;

-- 3. 작업 수행
-- ... DDL 작업 ...

-- 4. 외래키 체크 재활성화 (필요시)
SET FOREIGN_KEY_CHECKS = 1;

-- 5. 컬럼 존재 확인 및 안내 (필요시)
SELECT 
    CASE 
        WHEN COUNT(*) > 0 THEN '⚠️ 추가 작업이 필요합니다: [수동 명령]'
        ELSE '✅ 모든 작업이 완료되었습니다.'
    END as manual_check
FROM INFORMATION_SCHEMA.COLUMNS 
WHERE TABLE_SCHEMA = 'database_name' 
  AND TABLE_NAME = 'table_name' 
  AND COLUMN_NAME = 'column_name';

-- 6. 테이블 구조 확인
DESCRIBE `modified_table`;

-- 7. 완료 메시지
SELECT '작업 완료' as message;
SELECT '백업 테이블: backup_table_YYYYMMDD' as backup_info;
```

## 🚨 주의사항

### 1. 백업 필수
- 모든 DDL 작업 전 백업 테이블 생성
- 백업 테이블명: `원본테이블명_BACKUP_YYYYMMDD` 형식

### 2. 동적 SQL 제한
- MariaDB에서 PREPARE/EXECUTE 구문은 불안정할 수 있음
- 가능하면 정적 SQL 사용하고, 필요시 수동 실행 안내

### 3. 트랜잭션 제한
- DDL은 자동 커밋되므로 롤백 불가
- 중요한 작업은 단계별로 분리하여 실행

### 4. 외래키 처리
- TRUNCATE 전 반드시 외래키 체크 비활성화
- 작업 완료 후 즉시 재활성화

### 5. 컬럼/인덱스 존재 확인
- 중복 생성 방지를 위해 존재 여부 확인
- INFORMATION_SCHEMA 활용하여 확인 후 안내

## ✅ 검증 체크리스트

DDL 스크립트 작성 시 다음 사항을 확인:

- [ ] MariaDB 호환 구문 사용
- [ ] 동적 SQL 대신 정적 SQL + 수동 안내 방식 사용
- [ ] 백업 테이블 생성 포함
- [ ] 외래키 처리 포함 (필요시)
- [ ] 컬럼 존재 확인 및 안내 메시지 포함
- [ ] 테이블 구조 확인 포함
- [ ] 완료 메시지 포함
- [ ] 주석으로 작업 내용 명시

## 🔍 테스트 방법

```sql
-- 1. 구문 검사
-- DDL 스크립트를 테스트 DB에서 먼저 실행

-- 2. 백업 확인
SELECT COUNT(*) FROM backup_table_YYYYMMDD;

-- 3. 구조 확인
DESCRIBE modified_table;

-- 4. 제약조건 확인
SHOW CREATE TABLE modified_table;

-- 5. 수동 작업 확인
-- 스크립트 실행 후 안내 메시지에 따라 추가 작업 수행
```

**모든 DDL 스크립트는 이 규칙을 준수하여 MariaDB 호환성을 보장한다.**
description:
globs:
alwaysApply: false
---