dbclient

dbclient는 XML SQL 계약을 기준으로 관계형 데이터베이스 요청을 실행하는 모듈입니다. SQL Server, Oracle, MySQL/MariaDB, PostgreSQL, SQLite 데이터 원본을 설정할 수 있으며, transact에서는 CommandType=D 거래의 기본 실행 모듈로 사용합니다.

책임 범위

DataSource 설정을 읽어 애플리케이션/프로젝트별 데이터베이스 연결을 관리합니다.
XML statement 계약을 로드하고 ApplicationID|ProjectID|TransactionID|StatementID 기준으로 실행합니다.
요청 파라미터를 DB provider별 native parameter로 변환합니다.
Json, Scalar, NonQuery, Xml, SchemeOnly, CodeHelp 같은 반환 형식을 처리합니다.
SQL 실행 로그와 프로파일 로그를 설정에 따라 파일 또는 logger 모듈로 전송합니다.

주요 API

메서드	경로	용도
`GET`	`/dbclient/api/query/has`	statement 계약 존재 여부를 확인합니다.
`GET`	`/dbclient/api/query/refresh`	계약 파일을 다시 로드합니다.
`GET`	`/dbclient/api/query/retrieve`	계약 원문 또는 상세 정보를 조회합니다.
`GET`	`/dbclient/api/query/meta`	입력/출력 메타 정보를 반환합니다.
`GET`	`/dbclient/api/query/reports`	계약 기반 보고용 정보를 조회합니다.
`POST`	`/dbclient/api/query/execute`	SQL 계약을 실행합니다.

핵심 구현

Areas/dbclient/Controllers/QueryController.cs: query API 진입점입니다.
DataClient/QueryDataClient.cs: 계약 해석, 파라미터 바인딩, SQL 실행 핵심 구현입니다.
Extensions/DatabaseMapper.cs: XML statement와 데이터 원본 매핑을 관리합니다.
Events/DbClientRequestHandler.cs: 모듈 내부 DB 실행 요청을 처리합니다.
Events/ManagedRequestHandler.cs: 운영/관리 화면에서 전달되는 데이터 원본 변경 요청을 반영합니다.
Profiler: provider별 DB command 실행 프로파일을 수집합니다.

계약과 식별자

계약은 기본적으로 다음 위치에 둡니다.

contracts/dbclient/{ApplicationID}/{ProjectID}/{TransactionID}.xml

쿼리 ID는 다음 형식입니다.

ApplicationID|ProjectID|TransactionID|StatementID

statement ID는 보통 GD01, LD01, MD01, DD01처럼 조회, 목록, 수정, 삭제 성격이 드러나도록 나눕니다. 계약에는 DataSourceID, SQL 본문, 입력 파라미터, 반환 형식을 함께 선언합니다.

주요 설정

설정	설명
`ContractBasePath`	dbclient XML 계약 루트 목록입니다.
`DataSource`	애플리케이션/프로젝트별 DB provider와 연결 문자열입니다.
`DefaultCommandTimeout`	statement timeout이 없을 때 적용되는 기본 SQL 제한 시간입니다.
`IsContractFileWatching`	계약 파일 변경 감시 여부입니다.
`IsTransactionLogging`	요청/응답 거래 로그 기록 여부입니다.
`IsProfileLogging`	DB provider 호출 프로파일 로그 기록 여부입니다.
`SubscribeAction`	기본 수신 이벤트는 `dbclient.Events.DbClientRequest`, `dbclient.Events.ManagedRequest`입니다.

DataSource 예시는 다음과 같습니다.

{
  "ApplicationID": "HDS",
  "ProjectID": "*",
  "DataSourceID": "DB01",
  "DataProvider": "SQLite",
  "ConnectionString": "URI=file:../sqlite/HDS/dbclient/HDS.db;Journal Mode=Off;BinaryGUID=False;DateTimeFormat=Ticks;Version=3;",
  "IsEncryption": "N"
}

transact 연동

transact 거래 계약에서는 CommandType을 D로 둡니다.

{
  "ServiceID": "LD01",
  "CommandType": "D",
  "ReturnType": "Json"
}

라우팅 예시는 다음과 같습니다.

{
  "HDS|*|D|D": "http://localhost:8421/dbclient/api/query",
  "HDS|*|D|P": "http://localhost:8421/dbclient/api/query",
  "HDS|*|D|T": "http://localhost:8421/dbclient/api/query"
}

운영 주의사항

연결 문자열과 DB 계정은 환경별 설정으로 분리하고 실제 비밀번호를 공개 저장소에 두지 않습니다.
IsProfileLogging은 성능 분석에는 유용하지만 SQL과 파라미터가 남을 수 있으므로 운영에서는 목적과 보관 기간을 명확히 합니다.
계약 파일 hot reload를 사용할 때는 변경 배포와 refresh 시점을 운영 절차에 포함합니다.
SQL provider별 파라미터 타입과 날짜/숫자 변환 규칙이 다르므로 계약 작성 후 실제 provider에서 검증합니다.

책임 범위​

주요 API​

핵심 구현​

계약과 식별자​

주요 설정​

transact 연동​

운영 주의사항​