Oracle ORA-02019 오류 원인과 해결 방법 완벽 가이드

ORA-02019 connection description for remote database not found 는?

ORA-02019 에러는 Oracle 데이터베이스에서 원격 데이터베이스에 접속하려 할 때, 해당 원격 데이터베이스에 대한 연결 설명(Connection Description)을 찾을 수 없을 때 발생하는 에러입니다. 주로 데이터베이스 링크(Database Link)를 통해 원격 데이터베이스에 접근하거나, 분산 트랜잭션(Distributed Transaction)을 수행하는 과정에서 발생합니다. 이 에러는 tnsnames.ora 파일의 잘못된 설정, 데이터베이스 링크 자체의 오류, 또는 Oracle Net 구성 문제로 인해 발생하는 경우가 대부분입니다.

---

주요 발생 원인

1. 데이터베이스 링크(Database Link)가 존재하지 않거나 잘못 생성된 경우

데이터베이스 링크는 원격 데이터베이스와의 연결 통로 역할을 합니다. 링크 자체가 존재하지 않거나, 링크 생성 시 잘못된 TNS 서비스명 또는 접속 정보를 사용한 경우 ORA-02019가 발생합니다. 특히 DBA가 아닌 일반 개발자가 링크를 생성할 때 오탈자나 대소문자 오류로 인해 자주 발생하는 패턴입니다.

2. tnsnames.ora 파일에 원격 데이터베이스 항목이 없거나 잘못 구성된 경우

Oracle Net은 tnsnames.ora 파일을 참조하여 원격 서버의 호스트, 포트, 서비스명 등을 파악합니다. 해당 파일에 연결하려는 원격 데이터베이스의 TNS 항목이 누락되어 있거나, 호스트명·포트·서비스명 등이 잘못 기재된 경우 연결 설명을 찾지 못해 에러가 발생합니다. 여러 서버 환경에서 tnsnames.ora 파일이 동기화되지 않을 때도 이 문제가 반복적으로 발생합니다.

3. ORACLE_HOME 또는 TNS_ADMIN 환경 변수가 잘못 설정된 경우

Oracle은 TNS_ADMIN 환경 변수나 ORACLE_HOME 경로를 통해 tnsnames.ora 파일의 위치를 결정합니다. 환경 변수가 잘못 설정되어 있거나, 여러 Oracle 홈이 혼재하는 환경에서 잘못된 tnsnames.ora 파일이 참조될 경우, 유효한 연결 설명을 찾지 못해 ORA-02019 에러가 발생합니다. 이는 특히 운영 서버에서 Oracle 버전 업그레이드 후 환경 변수가 재설정되지 않은 경우에 자주 나타납니다.

---

해결 방법

원인 1: 데이터베이스 링크 확인 및 재생성

먼저 현재 존재하는 데이터베이스 링크 목록을 확인합니다.

-- 현재 사용자의 DB 링크 확인
SELECT db_link, username, host, created
FROM user_db_links;

-- DBA 권한으로 전체 DB 링크 확인
SELECT owner, db_link, username, host, created
FROM dba_db_links
ORDER BY owner, db_link;

링크가 없거나 잘못 생성된 경우 아래와 같이 삭제 후 재생성합니다.

-- 기존 DB 링크 삭제
DROP DATABASE LINK remote_db_link;

-- DB 링크 재생성 (TNS 서비스명 방식)
CREATE DATABASE LINK remote_db_link
  CONNECT TO remote_user
  IDENTIFIED BY remote_password
  USING 'REMOTE_TNS_ALIAS';

-- DB 링크 재생성 (직접 접속 문자열 방식 - tnsnames.ora 없이도 사용 가능)
CREATE DATABASE LINK remote_db_link_direct
  CONNECT TO remote_user
  IDENTIFIED BY remote_password
  USING '(DESCRIPTION=
            (ADDRESS=(PROTOCOL=TCP)(HOST=remote_host_ip)(PORT=1521))
            (CONNECT_DATA=(SERVICE_NAME=remote_service_name)))';

-- DB 링크 동작 확인
SELECT * FROM dual@remote_db_link;

원인 2: tnsnames.ora 파일 수정 및 확인

tnsnames.ora 파일의 위치를 확인하고 항목을 추가합니다.

-- sqlplus에서 현재 TNS 설정 경로 확인 (OS 명령어 활용)
-- Linux/Unix 환경
-- $ echo $TNS_ADMIN
-- $ echo $ORACLE_HOME
-- $ cat $ORACLE_HOME/network/admin/tnsnames.ora

-- tnsnames.ora 파일에 추가할 내용 예시 (파일 직접 편집)
/*
REMOTE_TNS_ALIAS =
  (DESCRIPTION =
    (ADDRESS = (PROTOCOL = TCP)(HOST = 192.168.1.100)(PORT = 1521))
    (CONNECT_DATA =
      (SERVER = DEDICATED)
      (SERVICE_NAME = REMOTEDB)
    )
  )
*/

-- tnsping으로 연결 가능 여부 테스트 (OS 레벨)
-- $ tnsping REMOTE_TNS_ALIAS

-- Oracle 내부에서 글로벌 이름 확인
SELECT global_name FROM global_name;

-- 연결 가능한 서비스 확인 (리스너 상태)
-- $ lsnrctl status

수정 후 데이터베이스 링크를 재테스트합니다.

-- 링크 테스트
SELECT sysdate FROM dual@remote_db_link;

-- 원격 테이블 조회 테스트
SELECT COUNT(*) FROM some_table@remote_db_link;

-- 원격 DB의 현재 사용자 확인
SELECT user FROM dual@remote_db_link;

원인 3: 환경 변수 및 Oracle Net 설정 재확인

-- Oracle 파라미터에서 글로벌 이름 사용 여부 확인
SHOW PARAMETER global_names;

-- 글로벌 이름 강제 사용 해제 (필요 시)
ALTER SYSTEM SET global_names = FALSE SCOPE = BOTH;

-- 현재 세션에서만 변경
ALTER SESSION SET global_names = FALSE;

-- DB 링크 생성 시 글로벌 이름과 일치 여부 확인
-- (global_names=TRUE인 경우 db_link 이름이 원격 DB의 global_name과 일치해야 함)
SELECT global_name FROM global_name@remote_db_link;

-- 공유 DB 링크(Public) 생성 예시 (DBA 권한 필요)
CREATE PUBLIC DATABASE LINK remote_db_link
  CONNECT TO remote_user
  IDENTIFIED BY remote_password
  USING 'REMOTE_TNS_ALIAS';

---

예방 방법

1. 데이터베이스 링크 및 TNS 설정 표준화 및 문서화

모든 데이터베이스 링크와 tnsnames.ora 항목은 반드시 표준 네이밍 규칙에 따라 생성하고, 변경 이력을 관리 문서에 기록해야 합니다. 운영 환경, 개발 환경, 테스트 환경 간의 tnsnames.ora 파일을 주기적으로 동기화하고, Ansible이나 Chef 같은 형상 관리 도구를 활용하여 자동 배포 체계를 구축하는 것을 강력히 권장합니다. 아울러 신규 DB 링크 생성 시에는 반드시 DBA 검토 후 적용하는 변경 관리 프로세스를 수립해야 합니다.

2. 정기적인 데이터베이스 링크 유효성 검사 스크립트 운영

아래와 같은 스크립트를 주기적(일별 또는 주별)으로 실행하여 모든 DB 링크의 정상 동작 여부를 사전에 점검하는 모니터링 체계를 갖추는 것이 중요합니다. 링크 이상 감지 시 즉시 담당자에게 알림이 가도록 알림 체계와 연동하면 장애로 이어지기 전에 선제적으로 대응할 수 있습니다.

-- DB 링크 유효성 정기 점검 스크립트 예시
BEGIN
  FOR rec IN (SELECT db_link FROM user_db_links) LOOP
    BEGIN
      EXECUTE IMMEDIATE 'SELECT 1 FROM dual@' || rec.db_link;
      DBMS_OUTPUT.PUT_LINE('OK: ' || rec.db_link);
    EXCEPTION
      WHEN OTHERS THEN
        DBMS_OUTPUT.PUT_LINE('FAIL: ' || rec.db_link || ' - ' || SQLERRM);
    END;
  END LOOP;
END;
/

---

관련 에러

• ORA-12154: TNS:could not resolve the connect identifier specified — tnsnames.ora에서 지정한 연결 식별자를 찾을 수 없을 때 발생하며, ORA-02019와 함께 가장 빈번하게 나타나는 연관 에러입니다.
• ORA-02085: database link connects to — DB 링크 이름이 원격 데이터베이스의 글로벌 이름과 일치하지 않을 때 발생합니다.
• ORA-01017: invalid username/password — DB 링크에 설정된 원격 사용자 계정 정보가 잘못된 경우 발생합니다.
• ORA-12541: TNS:no listener — 원격 데이터베이스 서버의 리스너가 실행 중이지 않을 때 발생합니다.
• ORA-02063: preceding line/lines from — 원격 DB에서 반환된 에러를 로컬 DB가 전달할 때 함께 나타나는 에러로, ORA-02019 발생 시 스택 트레이스에서 자주 볼 수 있습니다.

---

본 포스트는 AI가 생성한 기술 가이드입니다. 운영 환경 적용 전 충분한 검토를 권장합니다.