MSSQL RAISERROR 사용법과 실전 예제

⚙️ RAISERROR 기본 개념과 동작 원리

MSSQL에서 RAISERROR는 데이터베이스 실행 과정에서 사용자 정의 오류 메시지를 발생시키는 명령문입니다.
기본적으로 오류를 발생시키고, 심각도(severity)와 상태(state)를 지정하여 메시지를 SQL Server나 애플리케이션에 전달할 수 있습니다.
이 기능을 활용하면 개발자는 단순히 에러를 알리는 것뿐 아니라, 오류 처리 흐름을 제어하고 문제 상황을 정확하게 로깅할 수 있습니다.

RAISERROR는 두 가지 주요 용도로 쓰입니다.
첫째, 트랜잭션 중단입니다.
조건문이나 예외 상황에서 RAISERROR를 실행하면, 해당 트랜잭션이 즉시 중단되며 이후 명령이 실행되지 않습니다.
둘째, 로그 기록입니다.
오류 메시지를 SQL Server 로그 또는 애플리케이션 로그로 남겨, 운영 환경에서 장애 원인을 추적할 수 있게 합니다.

💡 RAISERROR와 THROW의 차이

SQL Server 2012 이후부터는 THROW라는 새로운 예외 처리 명령이 추가되었습니다.
RAISERROR와 THROW 모두 오류를 발생시키지만, THROW는 구문이 간결하고 TRY…CATCH 블록 안에서 예외를 다시 발생시키는 데 유리합니다.
반면 RAISERROR는 SQL Server 2008 등 구버전에서도 사용할 수 있으며, 심각도 지정과 사용자 정의 메시지 ID 활용이 가능합니다.

-- 기본 RAISERROR 구문 예제
RAISERROR ('오류가 발생했습니다.', 16, 1);

🛠️ RAISERROR 구문 구조와 주요 매개변수

RAISERROR는 다음과 같은 기본 구문 구조를 가지고 있습니다.
이 구조를 이해하면 다양한 상황에서 유연하게 적용할 수 있습니다.

RAISERROR (message_string | message_id, severity, state 
    [ , argument [ , ...n ] ] ) 
    [ WITH option [ , ...n ] ]

🔍 주요 매개변수 설명

⚙️ WITH 옵션

WITH 옵션을 사용하면 RAISERROR의 동작 방식을 더 세부적으로 제어할 수 있습니다.
대표적인 옵션은 다음과 같습니다.

• 📝WITH LOG – 오류 메시지를 SQL Server 오류 로그와 Windows 이벤트 뷰어에 기록
• 🚫WITH NOWAIT – 버퍼링 없이 즉시 메시지를 클라이언트에 전송

💡 사용자 정의 오류 메시지 등록과 호출

운영 환경에서는 표준 오류만으로는 원인 파악이 어렵거나, 비즈니스 규칙을 명확히 전달하기에 부족할 때가 많습니다.
이럴 때 사용자 정의 오류 메시지를 등록하면, 일관된 문구와 번호 체계를 갖추어 신속한 진단과 로그 분석이 가능합니다.
MSSQL에서는 sys.sp_addmessage로 메시지를 등록하고, RAISERROR에서 메시지 ID를 사용해 호출합니다.
또한 서식 매개변수로 동적인 값을 메시지에 삽입해, 현장 상황을 구체적으로 남길 수 있습니다.

🧱 sys.sp_addmessage로 메시지 등록

메시지는 데이터베이스가 아닌 서버 범위로 관리되며, 보통 50000 이상 번호 대역을 사용합니다.
메시지 텍스트에는 %s, %d 같은 서식 지정자를 포함할 수 있습니다.
언어별 메시지를 별도로 등록할 수도 있어 다국어 운영에 유리합니다.

-- 사용자 정의 메시지 등록
EXEC sys.sp_addmessage
     @msgnum = 50001,               -- 50000 이상 권장
     @severity = 16,                 -- 사용자 오류 범주
     @msgtext = N'잘못된 주문 번호입니다. 주문번호: %d',
     @lang = N'ko-KR',
     @with_log = 'false',            -- 기본은 로그 미기록
     @replace = 'replace';           -- 기존 텍스트가 있으면 교체

🧩 RAISERROR로 메시지 호출과 매개변수 전달

등록된 메시지는 message_id를 사용해 호출합니다.
서식 지정자가 있다면 추가 인자로 값을 전달합니다.
심각도와 상태값을 적절히 부여해 오류 처리 흐름을 통제합니다.

DECLARE @OrderId INT = 12345;
RAISERROR (50001, 16, 1, @OrderId);  -- 결과: "잘못된 주문 번호입니다. 주문번호: 12345"

🧭 로그 정책: WITH LOG와 sp_altermessage

특정 메시지는 항상 서버 오류 로그에 남기고 싶을 때가 있습니다.
두 가지 방법이 있습니다.
첫째, 호출 시 WITH LOG 옵션을 사용합니다.
둘째, sys.sp_altermessage로 메시지 자체를 로그 강제 기록 대상으로 지정합니다.

-- 1) 호출 시 로그 기록
RAISERROR (50001, 16, 1, @OrderId) WITH LOG;

-- 2) 메시지를 항상 로그로
EXEC sys.sp_altermessage
     @message_id = 50001,
     @parameter = 'WITH_LOG',
     @parameter_value = 'true';

🔎 등록된 메시지 조회·수정·삭제

메시지 현황은 sys.messages 뷰에서 확인합니다.
텍스트 변경은 @replace = ‘replace’로 sp_addmessage를 다시 실행하거나, 필요 시 메시지 삭제 후 재등록합니다.

-- 조회
SELECT message_id, language_id, severity, is_event_logged, text
FROM sys.messages
WHERE message_id = 50001;

-- 삭제
EXEC sys.sp_dropmessage @msgnum = 50001, @lang = N'ko-KR';

• 🗂️메시지 번호, 심각도, 언어별 등록 현황을 정기 점검하세요.
• 🧩서식 지정자는 실제 전달 인자 수와 타입을 맞춰 런타임 오류를 방지하세요.
• 🛡️운영 반영 전 테스트 환경에서 로그 정책과 TRY…CATCH 동작을 검증하세요.

🚫 트랜잭션 중단 및 ROLLBACK과의 연계

MSSQL에서 RAISERROR를 가장 강력하게 활용하는 방법 중 하나는 트랜잭션과 연계하는 것입니다.
비즈니스 로직 실행 도중 조건이 충족되지 않거나, 데이터 무결성이 훼손될 가능성이 감지되면 즉시 오류를 발생시키고 ROLLBACK을 통해 이전 상태로 되돌릴 수 있습니다.
이를 통해 잘못된 데이터 반영을 사전에 차단하고, 시스템 안정성을 확보할 수 있습니다.

🔄 기본 트랜잭션 흐름 예제

BEGIN TRY
    BEGIN TRANSACTION;

    -- 데이터 처리 로직
    IF EXISTS (SELECT 1 FROM Orders WHERE Quantity <= 0)
    BEGIN
        RAISERROR('수량이 0 이하인 주문이 존재합니다.', 16, 1);
    END

    COMMIT TRANSACTION;
END TRY
BEGIN CATCH
    ROLLBACK TRANSACTION;

    -- 오류 정보 확인
    SELECT ERROR_NUMBER() AS ErrorNumber,
           ERROR_MESSAGE() AS ErrorMessage;
END CATCH

⚠️ 주의할 점

• 🚫RAISERROR 발생 시점 이후의 코드가 실행되지 않으므로, 커넥션 종료나 로그 저장 로직은 CATCH 블록에 배치해야 합니다.
• 🛡️ROLLBACK 후에도 연결은 유지되므로, 필요한 경우 세션 종료나 재연결 절차를 포함하세요.
• 📜운영 환경에서는 ROLLBACK 직전 상태를 별도 테이블에 기록하는 로직을 권장합니다.

🧩 RAISERROR와 조건부 ROLLBACK

모든 오류 상황에서 ROLLBACK을 수행할 필요는 없습니다.
일부 경고성 메시지는 트랜잭션을 유지한 채 로그만 남기는 것이 더 유리할 수 있습니다.
심각도(severity)를 10 이하로 설정하면 경고성 메시지로만 처리되며, 트랜잭션은 계속 유지됩니다.

IF (@재고수량 < @최소허용치)
BEGIN
    RAISERROR('재고가 부족합니다. 현재 수량: %d', 10, 1, @재고수량) WITH LOG;
END

📊 운영 환경에서의 로그 기록 활용법

RAISERROR를 단순히 오류 알림 용도로만 사용하는 것은 아깝습니다.
운영 환경에서는 로그 기록 기능을 적극적으로 활용하여 장애 대응 속도를 높이고, 문제 재발을 방지할 수 있습니다.
특히 WITH LOG 옵션과 Windows 이벤트 뷰어 연계를 통해 DB 관리자와 시스템 운영팀이 동일한 정보를 공유할 수 있습니다.

📝 SQL Server 오류 로그와의 연계

WITH LOG 옵션을 사용하면 RAISERROR 메시지가 SQL Server 오류 로그와 Windows 이벤트 뷰어에 동시에 기록됩니다.
이 방식은 운영 장애 분석에 매우 효과적이며, 보안 및 컴플라이언스 요구사항을 충족하는 데 도움이 됩니다.

RAISERROR('중요 오류 발생: %s', 16, 1, @오류내용) WITH LOG;

📂 애플리케이션 로그와 통합

웹 애플리케이션이나 ERP 시스템에서는 RAISERROR를 발생시킨 후, CATCH 블록에서 애플리케이션 로그 파일이나 중앙 로깅 서버(예: ELK Stack, Splunk)에 기록할 수 있습니다.
이를 통해 DB 이벤트와 애플리케이션 이벤트를 연결하여 전사적인 모니터링 체계를 구축할 수 있습니다.

• 🔗DB와 애플리케이션 로그를 동일 타임스탬프로 기록해 사건 추적을 용이하게 함
• 📡중앙 로깅 서버를 활용해 실시간 대시보드와 경고 알림 설정
• 🛡️로그 접근 권한을 최소화하여 민감 정보 유출 방지

📊 운영 리포트 자동화

로그 데이터를 주기적으로 수집해 운영 리포트를 자동 생성하면, 관리자와 경영진이 서비스 안정성을 빠르게 파악할 수 있습니다.
Power BI, Tableau 같은 시각화 도구를 활용하면 오류 발생 빈도, 유형, 영향 범위를 직관적으로 확인할 수 있습니다.

⚠️ 로그 관리 시 주의사항

• 🧹불필요하게 오래된 로그는 주기적으로 정리하여 저장 공간 확보
• 🔒로그 파일에 포함된 개인정보는 암호화 또는 마스킹 처리
• 📑로그 보존 정책을 사전에 문서화하여 법적 요구사항 준수

❓ 자주 묻는 질문 (FAQ)