# 외부 DB 연결 관리 기능 가이드

## 개요

외부 DB 연결 관리 기능은 다양한 외부 데이터베이스와의 연결을 설정하고 관리하는 기능을 제공합니다. 이 기능을 통해 PostgreSQL, MySQL, MariaDB 등 다양한 데이터베이스에 연결하여 데이터를 조회하고 저장할 수 있습니다.

## 주요 기능

### 1. 연결 관리

- 새 연결 생성
- 기존 연결 수정
- 연결 삭제
- 연결 활성화/비활성화
- 연결 테스트

### 2. 지원하는 데이터베이스 타입

- PostgreSQL
- MySQL
- MariaDB
- Oracle
- SQL Server
- SQLite

### 3. 연결 설정 항목

#### 기본 정보
- 연결명 (필수)
- DB 타입 (필수)
- 설명 (선택)

#### 연결 정보
- 호스트 (필수)
- 포트 (필수)
- 데이터베이스명 (필수)
- 사용자명 (필수)
- 비밀번호 (필수)

#### 고급 설정
- 연결 타임아웃 (기본값: 30초)
- 쿼리 타임아웃 (기본값: 60초)
- 최대 연결 수 (기본값: 10)
- SSL 사용 여부
- SSL 인증서 경로 (SSL 사용 시)

## 사용 방법

### 1. 새 연결 생성

1. "외부 DB 연결 관리" 화면에서 "새 연결 추가" 버튼 클릭
2. 기본 정보 입력
   - 연결명: 고유한 식별자로 사용
   - DB 타입: 연결할 데이터베이스 종류 선택
   - 설명: 연결에 대한 부가 설명 (선택사항)
3. 연결 정보 입력
   - 호스트: 데이터베이스 서버 주소
   - 포트: DB 타입에 따라 기본값 제공
   - 데이터베이스명: 연결할 데이터베이스 이름
   - 사용자명: 데이터베이스 접속 계정
   - 비밀번호: 계정 비밀번호
4. 필요한 경우 고급 설정 구성
5. "연결 테스트" 버튼으로 연결 가능 여부 확인
6. "생성" 버튼으로 연결 저장

### 2. 연결 수정

1. 연결 목록에서 수정할 연결의 "편집" 버튼 클릭
2. 필요한 정보 수정
   - 비밀번호는 변경 시에만 입력
   - 비밀번호 필드를 비워두면 기존 비밀번호 유지
3. "연결 테스트"로 수정된 정보 확인
4. "수정" 버튼으로 변경사항 저장

### 3. 연결 테스트

- 새 연결 생성 시: 임시 연결을 생성하여 테스트 후 삭제
- 기존 연결 수정 시: 현재 연결로 테스트 실행
- 테스트 결과에 서버 버전, 응답 시간 등 상세 정보 표시
- 실패 시 상세한 오류 메시지 제공

### 4. 연결 삭제

1. 연결 목록에서 삭제할 연결의 "삭제" 버튼 클릭
2. 확인 대화상자에서 "삭제" 선택
3. 해당 연결과 관련된 모든 설정 제거

## 보안 고려사항

1. 비밀번호 관리
   - 비밀번호는 AES-256-CBC로 암호화하여 저장
   - 비밀번호는 UI에 표시되지 않음
   - 수정 시 비밀번호 필드를 비워두면 기존 비밀번호 유지

2. SSL 연결
   - SSL 사용 옵션 제공
   - 인증서 경로 설정 가능
   - 자체 서명 인증서 지원

3. 접근 제어
   - 회사 코드별 연결 관리
   - 활성/비활성 상태 관리
   - 연결별 최대 연결 수 제한

## 문제 해결

### 일반적인 문제

1. 연결 테스트 실패
   - 호스트/포트 접근 가능 여부 확인
   - 데이터베이스명 정확성 확인
   - 사용자 계정 권한 확인
   - 방화벽 설정 확인

2. 타임아웃 발생
   - 연결 타임아웃 값 조정
   - 네트워크 상태 확인
   - 데이터베이스 서버 부하 확인

3. SSL 연결 오류
   - 인증서 파일 경로 확인
   - 인증서 유효성 확인
   - SSL 설정 일치 여부 확인

### 오류 메시지 해석

1. "ECONNREFUSED"
   - 원인: 호스트/포트에 연결할 수 없음
   - 해결: 호스트/포트 정확성 확인, 방화벽 설정 확인

2. "password authentication failed"
   - 원인: 사용자명/비밀번호 불일치
   - 해결: 계정 정보 정확성 확인

3. "database does not exist"
   - 원인: 데이터베이스가 존재하지 않음
   - 해결: 데이터베이스명 정확성 확인

## 모범 사례

1. 연결명 작성
   - 용도를 명확히 알 수 있는 이름 사용
   - 회사/환경 정보 포함 권장
   - 예: "운영_회계DB", "개발_테스트DB"

2. 보안 설정
   - 가능한 SSL 사용
   - 최소 권한의 계정 사용
   - 연결 타임아웃 적절히 설정

3. 성능 최적화
   - 필요한 최소한의 최대 연결 수 설정
   - 쿼리 타임아웃 적절히 설정
   - 주기적인 연결 테스트 수행

## API 참조

### ExternalDbConnectionAPI

#### 연결 관리
```typescript
// 연결 목록 조회
getConnections(filter: ExternalDbConnectionFilter): Promise<ExternalDbConnection[]>

// 연결 상세 조회
getConnectionById(id: number): Promise<ExternalDbConnection>

// 새 연결 생성
createConnection(data: ExternalDbConnection): Promise<ExternalDbConnection>

// 연결 수정
updateConnection(id: number, data: ExternalDbConnection): Promise<ExternalDbConnection>

// 연결 삭제
deleteConnection(id: number): Promise<void>
```

#### 연결 테스트
```typescript
// 연결 테스트
testConnection(connectionId: number, password?: string): Promise<ConnectionTestResult>
```

#### 데이터 조회/저장
```typescript
// 테이블 목록 조회
getTables(connectionId: number): Promise<string[]>

// 테이블 컬럼 정보 조회
getTableColumns(connectionId: number, tableName: string): Promise<ColumnInfo[]>

// 테이블 데이터 조회
getTableData(connectionId: number, tableName: string, options?: QueryOptions): Promise<any[]>

// 테이블 데이터 저장
saveTableData(connectionId: number, tableName: string, data: any[], options: SaveOptions): Promise<{ affected_rows: number }>
```

## 향후 계획

1. 기능 개선
   - 연결 풀 모니터링
   - 연결 통계 대시보드
   - 쿼리 실행 이력 관리

2. 지원 예정 기능
   - 연결 복제
   - 연결 설정 임포트/익스포트
   - 연결 그룹 관리

3. 보안 강화
   - 역할 기반 접근 제어
   - 감사 로그 강화
   - 연결 암호화 강화