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

ORA-02010 missing host connect string 는?

ORA-02010 에러는 Oracle 데이터베이스에서 데이터베이스 링크(Database Link)를 생성하거나 사용할 때, 원격 호스트에 대한 연결 문자열(connect string)이 누락되었을 경우 발생하는 에러입니다. 쉽게 말해, CREATE DATABASE LINK 구문에서 USING 절에 해당하는 TNS 연결 정보나 호스트 연결 문자열이 비어 있거나 잘못 지정되었을 때 Oracle 엔진이 이를 감지하고 발생시키는 오류입니다. 주로 DBA 또는 개발자가 데이터베이스 링크를 처음 설정하거나, 기존 링크를 수정하는 과정에서 실수로 연결 문자열을 생략하여 발생하는 경우가 많습니다.

---

주요 발생 원인

• CREATE DATABASE LINK 구문에서 USING 절 누락 또는 빈 문자열 지정

가장 흔한 원인으로, 데이터베이스 링크를 생성할 때 USING 절 자체를 빠뜨리거나, USING ''처럼 빈 문자열을 입력하는 경우입니다. Oracle은 데이터베이스 링크가 원격 인스턴스에 접속하기 위해 반드시 유효한 TNS 서비스명 또는 Easy Connect 문자열이 필요하며, 이 값이 없으면 어디에 접속해야 할지 알 수 없어 에러를 발생시킵니다. 실무에서 스크립트를 급하게 작성하거나 복사-붙여넣기 과정에서 해당 절이 누락되는 사례가 자주 발생합니다.

• TNS 서비스명이 tnsnames.ora에 등록되지 않았거나 잘못된 값 입력

USING 절에 TNS 서비스명을 지정하더라도, 해당 서비스명이 Oracle 클라이언트의 tnsnames.ora 파일에 정의되어 있지 않거나 오타가 있는 경우 연결 문자열을 인식하지 못할 수 있습니다. 특히 서버 환경이 변경되거나 새로운 서버로 마이그레이션 후 TNS 설정을 업데이트하지 않았을 때 이 문제가 빈번하게 발생합니다. tnsnames.ora 파일의 경로 설정 문제(TNS_ADMIN 환경 변수 미설정 등)도 함께 점검해야 합니다.

• 동적 SQL 또는 스크립트에서 변수 바인딩 오류로 인한 빈 연결 문자열 전달

PL/SQL 또는 외부 스크립트에서 데이터베이스 링크를 동적으로 생성할 때, 연결 문자열을 담은 변수가 NULL이거나 빈 값인 채로 DDL이 실행되는 경우가 있습니다. 이 경우 런타임에 ORA-02010 에러가 발생하며, 로그에서 원인을 추적하기 어려울 수 있습니다. 동적 SQL로 DDL을 실행할 때는 반드시 변수 값을 사전에 검증하는 로직을 포함해야 합니다.

---

해결 방법

원인 1 해결: USING 절을 올바르게 포함한 DATABASE LINK 생성

잘못된 예시 (ORA-02010 발생):

-- USING 절이 누락된 경우
CREATE DATABASE LINK my_remote_link
CONNECT TO remote_user IDENTIFIED BY "password";

-- USING 절에 빈 문자열을 지정한 경우
CREATE DATABASE LINK my_remote_link
CONNECT TO remote_user IDENTIFIED BY "password"
USING '';

올바른 예시:

-- TNS 서비스명을 사용하는 경우
CREATE DATABASE LINK my_remote_link
CONNECT TO remote_user IDENTIFIED BY "password"
USING 'REMOTE_DB_SERVICE';

-- Easy Connect 문자열을 직접 사용하는 경우 (tnsnames.ora 불필요)
CREATE DATABASE LINK my_remote_link
CONNECT TO remote_user IDENTIFIED BY "password"
USING '192.168.1.100:1521/ORCL';

-- 생성된 링크 확인
SELECT db_link, username, host
FROM dba_db_links
WHERE db_link = 'MY_REMOTE_LINK';

원인 2 해결: TNS 서비스명 유효성 확인 및 Easy Connect로 대체

-- tnsping을 통해 서비스명 확인 (SQL*Plus 외부 명령)
-- $ tnsping REMOTE_DB_SERVICE

-- 현재 등록된 DB Link 목록과 호스트 정보 확인
SELECT db_link, username, host, created
FROM dba_db_links
ORDER BY created DESC;

-- 기존 잘못된 링크 삭제 후 재생성
DROP DATABASE LINK my_remote_link;

CREATE DATABASE LINK my_remote_link
CONNECT TO remote_user IDENTIFIED BY "password"
USING '(DESCRIPTION=
          (ADDRESS=(PROTOCOL=TCP)(HOST=192.168.1.100)(PORT=1521))
          (CONNECT_DATA=(SERVICE_NAME=ORCL)))';

-- 링크 동작 테스트
SELECT * FROM dual@my_remote_link;

원인 3 해결: 동적 SQL에서 변수 검증 후 실행

DECLARE
  v_link_name   VARCHAR2(128) := 'MY_DYNAMIC_LINK';
  v_remote_user VARCHAR2(128) := 'remote_user';
  v_password    VARCHAR2(128) := 'password123';
  v_connect_str VARCHAR2(512) := '192.168.1.100:1521/ORCL';
  v_sql         VARCHAR2(1000);
BEGIN
  -- 연결 문자열 유효성 검사 (핵심!)
  IF v_connect_str IS NULL OR TRIM(v_connect_str) = '' THEN
    RAISE_APPLICATION_ERROR(-20001, 
      'Connect string cannot be NULL or empty. ORA-02010 would occur.');
  END IF;

  -- 동적 DDL 구성
  v_sql := 'CREATE DATABASE LINK ' || v_link_name ||
           ' CONNECT TO ' || v_remote_user ||
           ' IDENTIFIED BY "' || v_password || '"' ||
           ' USING ''' || v_connect_str || '''';

  DBMS_OUTPUT.PUT_LINE('Executing: ' || v_sql);
  EXECUTE IMMEDIATE v_sql;
  DBMS_OUTPUT.PUT_LINE('Database link created successfully.');

EXCEPTION
  WHEN OTHERS THEN
    DBMS_OUTPUT.PUT_LINE('Error: ' || SQLERRM);
    RAISE;
END;
/

-- 링크 생성 후 정상 동작 확인
SELECT sysdate FROM dual@MY_DYNAMIC_LINK;

기존 링크 상태 점검 쿼리

-- 현재 세션에서 사용 가능한 DB Link 전체 조회
SELECT owner, db_link, username, host, created
FROM dba_db_links
ORDER BY owner, db_link;

-- 특정 사용자의 DB Link 조회
SELECT db_link, username, host
FROM user_db_links;

-- DB Link를 통한 원격 테이블 접근 테스트
SELECT COUNT(*) FROM some_table@my_remote_link;

---

예방 방법

• 데이터베이스 링크 생성 표준 템플릿 및 검증 스크립트 운영

조직 내에서 데이터베이스 링크를 생성할 때 반드시 표준 템플릿을 사용하도록 규정하고, 생성 전 v_connect_str이 NULL인지 확인하는 PL/SQL 래퍼 프로시저를 작성하여 활용하세요. 링크 생성 후에는 즉시 SELECT * FROM dual@링크명 쿼리로 접속 테스트를 수행하고 그 결과를 로그로 남기는 습관을 들이는 것이 좋습니다. CI/CD 파이프라인에 DDL 스크립트 검증 단계를 포함시키면 운영 환경 배포 전에 오류를 사전 차단할 수 있습니다.

• tnsnames.ora 및 네트워크 설정 변경 이력 관리

서버 이전, IP 변경, 서비스명 변경 등 네트워크 환경이 바뀔 때마다 tnsnames.ora 파일을 즉시 업데이트하고, 변경 이력을 Git 등의 버전 관리 시스템으로 관리하세요. 또한 Easy Connect 형식(host:port/service_name)을 사용하면 tnsnames.ora 의존성을 줄일 수 있어 환경 변화에 더 유연하게 대응할 수 있습니다. 주기적으로 dba_db_links 뷰를 조회하여 유효하지 않은 링크가 있는지 감사(Audit)하는 것도 권장합니다.

---

관련 에러

• ORA-02011: 데이터베이스 링크 이름이 중복될 때 발생 (duplicate database link name)
• ORA-12154: TNS 서비스명을 찾을 수 없을 때 발생 (TNS:could not resolve the connect identifier specified) — USING 절에 잘못된 TNS 명을 입력한 경우 ORA-02010 이후 연계 발생 가능
• ORA-02019: 원격 데이터베이스에 대한 연결 설명이 존재하지 않을 때 (connection description for remote database not found)
• ORA-01017: 원격 DB 접속 시 사용자명/패스워드가 잘못된 경우 (invalid username/password; logon denied) — 링크 생성 후 테스트 단계에서 함께 점검 필요

---

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