📖 사용자 매뉴얼

Client Util App v1.3.10

사용자 매뉴얼

Node.js 통합 유틸리티 도구 완전 가이드
다국어 지원 (영어/한국어) | UTF-8 CSV 인코딩 필수

앱 다운로드 빠른 시작 📦 GitHub

Client Util App

$ node app.js

========================================

Node.js 통합 유틸리티 도구

========================================

📋 메인 메뉴

1. 데이터베이스 연결 및 권한 체크

2. 서버 텔넷 연결 체크

3. 데이터베이스 SQL 실행

4. CSV 기반 일괄 쿼리 실행 ⭐

5. 설정 관리

0. 종료

옵션을 선택하세요 (0-4):

█

비대화형 CLI (v1.3.10)

메뉴 없이 --mode와 파라미터로 바로 실행할 수 있습니다. Node/배포 EXE 모두에서 동작합니다.

--mode=db 데이터베이스 접속/권한 체크
--mode=telnet 서버 텔넷 접속 체크
--mode=sql 단일 SQL 실행
--mode=csv CSV 기반 일괄 쿼리 실행
--mode=config 설정 정보 출력

# DB 체크
node app.js --lang=kr --mode=db --csv=request/DB_sample.csv --timeout=5 --dbType=auto

# Telnet 체크
node app.js --lang=kr --mode=telnet --csv=request/server_sample.csv --timeout=3

# 단일 SQL (파일명 또는 경로, .sql 생략 가능)
node app.js --lang=kr --mode=sql --sql=SQL_001
node app.js --lang=kr --mode=sql --sql=request/sql_files/SQL_001.sql

# CSV 기반 일괄 실행
node app.js --lang=kr --mode=csv --csv=request/SQL2CSV_daily_export.csv

# 설정 정보 출력
node app.js --lang=kr --mode=config

# EXE
client-util-app.exe --lang=kr --mode=db --csv=request/DB_sample.csv

배포(EXE)에서는 상대 경로가 실행 파일 폴더 기준으로 해석됩니다.

소개

Client Util App v1.3.10은 데이터베이스 연결 관리, 서버 모니터링, SQL 실행을 통합 애플리케이션에서 처리하는 포괄적인 유틸리티 도구입니다.

v1.3.7 최신 업데이트

🐛

CSV 쿼리 결과 출력 개선

프로시저 정의 등 여러 줄 텍스트의 CSV 포맷 출력 개선

모든 줄바꿈을 공백으로 치환하여 한 줄로 저장
CSV 파일일 때만 쉼표/따옴표가 있을 때 따옴표로 감싸기
프로시저 정의가 한 줄로 깔끔하게 저장됨
Excel이나 텍스트 편집기에서 읽기 쉬운 형태
CSV 표준 준수로 호환성 향상

📊

CSV 기반 일괄 쿼리 실행 (v1.3.6+)

보안 검증 기능이 내장된 CSV 파일에서 여러 SQL 쿼리를 일괄 실행

request/ 디렉토리의 SQL2CSV_*.csv 파일에 정의된 쿼리 실행
날짜/시간 변수로 동적 파일 경로 지원: ${DATE:yyyyMMddHHmmss}
결과 파일 경로 변수 지원: ${DB_NAME} (선택한 DB 키)
출력 파일 디렉토리 자동 생성
쿼리 검증: SELECT 쿼리와 안전한 시스템 프로시저만 허용
보안 보호: INSERT, UPDATE, DELETE, DROP, TRUNCATE, ALTER, CREATE 차단

v1.3.4의 주요 특징

🌏

다국어 지원

완벽한 영어와 한국어 UI 지원 - --lang 파라미터로 언어 선택 또는 전용 실행 스크립트 사용 (run.bat / 실행하기.bat)

📝

CSV 인코딩 지원

모든 CSV 파일에 UTF-8 인코딩 필수 - 한글, 중국어, 일본어 및 기타 문자의 올바른 표시 보장

v1.3.0의 주요 특징

✅

CSV 결과 파일 생성

SQL 실행 결과를 구조화된 CSV 파일로 자동 저장

✅

전처리 지시자

#DATABASE 또는 #DB로 SQL 파일에서 접속 DB 명시

✅

JSON 파라미터 지원

CSV와 함께 JSON 형식 파라미터 파일 지원

✅

MariaDB 지원

MySQL 호환 드라이버로 MariaDB 데이터베이스 지원 추가

설치

필수 요구사항

운영체제

Windows 10+ (64-bit)

메모리

최소 100MB 사용 가능 메모리

디스크 공간

약 150MB 여유 공간

설치 단계

바이너리 릴리스 다운로드

GitHub 릴리스 페이지에서 최신 바이너리 파일을 다운로드합니다:

ClientUtilApp-v1.3.10-win-x64.zip

다운로드 링크: GitHub Releases

압축 해제

다운로드한 ZIP 파일을 원하는 위치에 압축 해제합니다:

C:\Tools\ClientUtilApp\

압축 해제 후 다음 파일들이 포함됩니다:

my-node-client-util-app.exe - 실행 파일
run.bat - 실행 배치 파일
config/ - 설정 파일 디렉토리
request/ - CSV 샘플 파일
user_manual/ - 사용자 매뉴얼

애플리케이션 실행

배치 파일을 더블클릭하여 실행합니다:

run.bat

또는 명령 프롬프트에서 직접 실행합니다:

my-node-client-util-app.exe

참고: Node.js가 설치되어 있지 않아도 실행 파일(.exe)로 바로 사용할 수 있습니다.

빠른 시작

첫 설정

1. CSV 파일 준비

request/ 디렉토리에 CSV 파일을 생성합니다:

DB 체크: DB_로 시작하는 파일 (예: DB_sample.csv)
텔넷 체크: server_로 시작하는 파일 (예: server_sample.csv)

2. CSV 파일 형식

데이터베이스 연결 체크를 위해 다음 컬럼들을 포함합니다:

                        db_name,username,password,server_ip,port,db_type,db_title,select_sql,crud_test_table,crud_test_columns,crud_test_values
                    

3. 첫 체크 실행

원하는 언어로 애플리케이션을 실행하고 데이터베이스 연결 체크를 위해 옵션 1을 선택합니다:

                        # 영어 UI:
$ run.bat

# 한국어 UI:
$ 실행하기.bat

# 또는 직접 언어 지정:
$ node app.js --lang=en
$ node app.js --lang=kr

옵션을 선택하세요 (1-6): 1
                    

데이터베이스 연결 및 권한 체크

지원 데이터베이스

🗄️

Microsoft SQL Server

연결 풀링과 암호화를 포함한 완전 지원

mssql

🐬

MySQL / MariaDB

MySQL과 MariaDB 완전 지원

mysql / mariadb

🐘

PostgreSQL

고급 PostgreSQL 기능 지원

postgresql

🔶

Oracle Database

엔터프라이즈 Oracle 데이터베이스 연결

oracle

체크되는 권한 타입

👁️

SELECT

사용자 정의 쿼리를 사용하여 테이블에서 데이터 읽기

➕

INSERT

지정된 테이블에 테스트 데이터 삽입

🗑️

DELETE

다중 컬럼 조건을 사용하여 테스트 데이터 제거

CSV 파일 형식

⚠️ 중요: UTF-8 인코딩 필수

모든 CSV 파일은 반드시 UTF-8 인코딩으로 저장해야 합니다. 다른 인코딩(EUC-KR, ANSI 등)은 지원하지 않으며 한글이 깨져서 표시됩니다.

Excel에서 UTF-8로 저장하는 방법: 파일 → 다른 이름으로 저장 → 파일 형식: "CSV UTF-8(쉼표로 분리) (*.csv)"

필수 컬럼

기본 연결 정보

db_name - 데이터베이스명
username - 데이터베이스 사용자명
password - 데이터베이스 비밀번호
server_ip - 서버 IP 또는 호스트명
port - 데이터베이스 포트 번호
db_type - 데이터베이스 타입 (mssql, mysql, postgresql, oracle)
db_title - 설명 (선택사항)

권한 테스트 (선택사항)

select_sql - 실행할 SELECT 쿼리
crud_test_table - INSERT/DELETE 테스트용 테이블명
crud_test_columns - 컬럼명 (쉼표로 구분)
crud_test_values - 테스트 값 (쉼표로 구분)

CSV 예시

                db_name,username,password,server_ip,port,db_type,db_title,select_sql,crud_test_table,crud_test_columns,crud_test_values

SampleDB,sa,password123,localhost,1433,mssql,샘플 DB,"SELECT TOP 3 * FROM users",users,"id, name, email","TEST_001, 테스트 사용자, test@example.com"

결과 분석

결과 CSV 형식

애플리케이션은 다음 컬럼들로 상세한 CSV 결과를 생성합니다:

기본 정보

timestamp - 체크 실행 시간
pc_ip - 클라이언트 PC IP 주소
server_ip - 데이터베이스 서버 IP
port - 데이터베이스 포트
db_name - 데이터베이스명
db_type - 데이터베이스 타입
db_userid - 데이터베이스 사용자 ID

연결 결과

result_code - SUCCESS / FAILED
error_code - 실패 시 에러 코드
error_msg - 실패 시 에러 메시지
collapsed_time - 실행 시간 (초)

권한 결과

perm_select - SELECT 권한 (Y/N)
perm_insert - INSERT 권한 (Y/N)
perm_delete - DELETE 권한 (Y/N)
insert_success - INSERT 실행 결과
delete_success - DELETE 실행 결과

쿼리 상세 (v1.2.0)

insert_query - 실제 실행된 INSERT 쿼리
delete_query - 실제 실행된 DELETE 쿼리
operation_errors - 상세 에러 메시지

결과 분석

✅

성공 지표

result_code = SUCCESS
perm_select = Y
insert_success = SUCCESS
delete_success = SUCCESS

❌

실패 지표

result_code = FAILED
error_code와 error_msg 확인
operation_errors에서 상세 정보 검토
연결 매개변수 확인

문제 해결

일반적인 문제

연결 시간 초과

증상: 연결 시도가 시간 초과 오류로 실패

해결 방법:

서버 IP와 포트가 올바른지 확인
방화벽 설정 확인
데이터베이스 서비스가 실행 중인지 확인
CSV에서 시간 초과 값 증가

인증 실패

증상: 로그인 실패 또는 액세스 거부 오류

해결 방법:

사용자명과 비밀번호 확인
데이터베이스에서 사용자 권한 확인
사용자가 존재하고 활성 상태인지 확인
인증 방법 확인

권한 거부

증상: SELECT/INSERT/DELETE 작업 실패

해결 방법:

사용자에게 적절한 권한 부여
테이블 존재 여부 및 액세스 권한 확인
컬럼명과 데이터 타입 확인
operation_errors에서 상세 정보 검토

CSV 파일을 찾을 수 없음

증상: 디렉토리에서 CSV 파일을 찾을 수 없음

해결 방법:

CSV 파일을 request/ 디렉토리에 배치
올바른 명명 규칙 사용 (DB_*, server_*)
파일에 .csv 확장자가 있는지 확인
파일 권한 확인

모범 사례

🔒

보안

최소 권한을 가진 전용 테스트 계정 사용
평문으로 민감한 비밀번호 저장 피하기
가능한 경우 암호화된 연결 사용
정기적으로 자격 증명 회전

📊

테스트

고유한 테스트 데이터 식별자 사용
먼저 비프로덕션 환경에서 테스트
정리 작업이 성공적으로 완료되는지 확인
문제에 대한 데이터베이스 로그 모니터링

📁

파일 관리

환경이나 목적별로 CSV 파일 구성
설명적인 파일명 사용
작동하는 구성의 백업 복사본 보관
모든 사용자 정의 수정 사항 문서화

🔄

유지보수

정기적으로 데이터베이스 드라이버 업데이트
오류에 대한 애플리케이션 로그 모니터링
데이터베이스 스키마 변경 후 테스트
최신 버전으로 애플리케이션 업데이트

버전 히스토리

v1.3.4

2025-10-18

주요 기능

다국어 지원: --lang 파라미터로 영어와 한국어 UI 지원
이중 실행 스크립트: run.bat (영어) 및 실행하기.bat (한국어)
60개 이상의 번역된 메시지로 원활한 사용 경험
올바른 문자 표시를 위한 UTF-8 CSV 인코딩 필수

개선사항

릴리스 스크립트에서 package.json으로부터 자동 버전 읽기
릴리스 패키지에서 이중 실행 스크립트 생성
한글 깨짐 문제 수정

v1.3.3

2025-10-16

중요 버그 수정

배포판 경로 해석 버그 수정
process.cwd()에서 path.dirname(process.execPath)로 변경
실행 위치와 관계없이 실행 파일이 올바르게 작동
config/, request_resources/, results/, log/ 디렉토리 올바르게 인식

v1.3.0

2025-10-08

주요 기능

SQL 실행 결과를 구조화된 CSV 파일로 자동 저장
#DATABASE 또는 #DB 전처리 지시자 도입
JSON 파라미터 파일 지원 (CSV와 함께)
조건별 결과 구분 및 메타데이터 표시
MariaDB 데이터베이스 지원 추가

개선사항

SQL 파일에서 접속 DB 자동 선택 기능
파라미터 세트별로 명확히 구분된 CSV 출력
배열 및 단일 객체 형식 JSON 지원
DB 메타데이터를 포함한 실행 결과

v1.2.0

2025-01-07

주요 기능

데이터베이스별 구분선으로 향상된 로그 출력
SELECT/INSERT/DELETE 작업의 상세 에러 캡처
스마트 필터링으로 간소화된 파일 관리
정확한 테스트를 위한 다중 컬럼 DELETE 조건

v1.1.0

2025-10-05

주요 변경사항

실제 테이블을 사용한 안전한 권한 체크
CREATE/DROP 권한 테스트 제거
Oracle 연결 오류 수정
향상된 CSV 파일 형식 지원

v1.0.0

2025-08-27

초기 릴리스

다중 데이터베이스 지원 (MSSQL, MySQL, PostgreSQL, Oracle)
데이터베이스 연결 및 권한 체크
서버 텔넷 연결 체크
SQL 실행 및 결과 저장
통합 메뉴 시스템

Client Util App v1.3.10

비대화형 CLI (v1.3.10)

목차

📋 시작하기

🗄️ 데이터베이스 기능

🌐 네트워크 기능

🔧 고급 기능

소개

v1.3.7 최신 업데이트

CSV 쿼리 결과 출력 개선

CSV 기반 일괄 쿼리 실행 (v1.3.6+)

v1.3.4의 주요 특징

다국어 지원

CSV 인코딩 지원

v1.3.0의 주요 특징

CSV 결과 파일 생성

전처리 지시자

JSON 파라미터 지원

MariaDB 지원

설치

필수 요구사항

운영체제

메모리

디스크 공간

설치 단계

바이너리 릴리스 다운로드

압축 해제

애플리케이션 실행

빠른 시작

첫 설정

1. CSV 파일 준비

2. CSV 파일 형식

3. 첫 체크 실행

데이터베이스 연결 및 권한 체크

지원 데이터베이스

Microsoft SQL Server

MySQL / MariaDB

PostgreSQL

Oracle Database

체크되는 권한 타입

SELECT

INSERT

DELETE

CSV 파일 형식

⚠️ 중요: UTF-8 인코딩 필수

필수 컬럼

기본 연결 정보

권한 테스트 (선택사항)

CSV 예시

결과 분석

결과 CSV 형식

기본 정보

연결 결과

권한 결과

쿼리 상세 (v1.2.0)

결과 분석

성공 지표

실패 지표

문제 해결

일반적인 문제

연결 시간 초과

해결 방법:

인증 실패

해결 방법:

권한 거부

해결 방법:

CSV 파일을 찾을 수 없음

해결 방법:

모범 사례

보안

테스트

파일 관리

유지보수

버전 히스토리

주요 기능

개선사항

중요 버그 수정

주요 기능

개선사항

주요 기능