DBMS_PIPE 패키지(영구 메시징 파이프)

DBMS_PIPE 패키지를 사용하면 동일한 Instance에 있는 두 개 이상의 세션이 통신할 수 있습니다.

Oracle Autonomous Database on Dedicated Exadata Infrastructure는 Oracle Database 19c에서 제공하는 핵심 DBMS_PIPE 기능과 확장 기능을 지원합니다.

Oracle Database에서 제공되는 핵심 DBMS_PIPE 기능에 대한 자세한 내용은 DBMS_PIPE in Oracle Database 19c PL/SQL Packages and Types Reference 또는 Oracle Database 23ai PL/SQL Packages and Types Reference를 참조하십시오.

관련 항목

DBMS_PIPE 영구 메시징 파이프 개요

파이프 기능에는 외부 서비스 인터페이스, 디버깅, 독립 트랜잭션 및 경보와 같은 여러 가지 잠재적 응용 프로그램이 있습니다.

Autonomous Database에서 DBMS_PIPE 패키지는 영구 메시징 파이프를 지원하는 확장된 기능을 제공합니다. 자세한 내용은 DBMS_PIPE in Oracle Database 19c PL/SQL Packages and Types Reference 또는 Oracle Database 23ai PL/SQL Packages and Types Reference를 참조하십시오.

DBMS_PIPE의 영구 메시지:

  • 매우 큰 메시지를 보내고 검색하는 기능을 지원합니다.

  • 많은 수의 파이프 메시지를 지원합니다.

  • 단일 데이터베이스, 여러 데이터베이스, 여러 리전의 데이터베이스 간 메시지 공유를 지원합니다.

  • 동일한 클라우드 객체 저장소 위치 URI를 사용하여 여러 파이프를 지원합니다.

    영구 메시징 기능을 사용하면 둘 이상의 데이터베이스 세션이 클라우드 객체 저장소에 저장된 메시지와 통신할 수 있습니다. 파이프에서 이 기능 메시지를 사용하면 현재 데이터베이스에서만 사용할 수 있고, 동일한 영역의 여러 데이터베이스 또는 여러 영역에서 사용할 수 있습니다.

    영구 메시징 파이프는 지원되는 DBMS_PIPE 유형 중 하나일 수 있습니다.

    • 암시적 파이프: DBMS_PIPE.SEND_MESSAGE 함수를 사용하여 알 수 없는 파이프 이름으로 메시지를 보낼 때 자동으로 생성됩니다.
    • 명시적 파이프: 사용자가 지정한 파이프 이름과 함께 DBMS_PIPE.CREATE_PIPE 함수를 사용하여 생성됩니다.
    • 공용 파이프: DBMS_PIPE 패키지에 대해 EXECUTE 권한이 있는 모든 사용자가 액세스할 수 있습니다.
    • 전용 파이프: 파이프 작성자와 동일한 사용자가 있는 세션에서 액세스할 수 있습니다.

주:

영구 메시지를 사용하여 여러 데이터베이스에서 메시지를 보내고 받을 때 Oracle은 메시지를 보내거나 받기 전에 DBMS_PIPE.CREATE_PIPE을 호출할 것을 권장합니다. DBMS_PIPE.CREATE_PIPE를 사용하여 명시적 파이프를 만들면 PRIVATE 매개변수를 FALSE로 설정하거나 기본값 TRUE를 사용하여 원하는 액세스 권한(public 또는 private)으로 파이프가 만들어집니다.

DBMS_PIPE 제한

DBMS_PIPE 패키지는 서로 다른 문자 집합을 사용하는 데이터베이스 간의 메시지 전송을 지원하지 않습니다. 예를 들어, AL32UTF8를 사용하는 Autonomous Database 인스턴스 하나와 WE8MSWIN1252를 사용하는 다른 인스턴스가 있는 경우 이 두 데이터베이스 간에 DBMS_PIPE를 사용하는 메시지를 전송할 수 없습니다. 이 경우 두 데이터베이스 간에 DBMS_PIPE를 사용하여 메시지를 보내려고 하면 시스템에서 ORA-12704 오류가 발생합니다.

영구 메시징을 위한 DBMS_PIPE 서브 프로그램 요약

이 표에서는 DBMS_PIPE 서브 프로그램을 나열하고 이에 대해 간략하게 설명합니다.

표 - DBMS_PIPE 패키지 서브 프로그램

하위 프로그램 설명

CREATE_PIPE 함수

파이프(개인 파이프에 필요)를 작성합니다.

GET_CREDENTIAL_NAME 함수

전역 credential_name 변수 값을 반환합니다.

GET_LOCATION_URI 함수

메시지가 클라우드 객체 저장소에 저장될 때 사용할 기본 위치 URI로 사용되는 전역 location_uri 변수 값을 반환합니다.

NEXT_ITEM_TYPE 함수

버퍼에 있는 다음 항목의 데이터 유형을 반환합니다.
PACK_MESSAGE 프로시저

로컬 버퍼에서 메시지를 작성합니다.

RECEIVE_MESSAGE 함수

이름이 지정된 파이프에서 로컬 버퍼로 메시지를 복사합니다.
RESET_BUFFER 프로시저

로컬 버퍼의 내용을 비웁니다.
REMOVE_PIPE 함수

명명된 파이프를 제거합니다.

SEND_MESSAGE 함수

명명된 파이프에 메시지 보내기: 명명된 파이프가 없으면 공용 파이프를 암시적으로 작성합니다.

SET_CREDENTIAL_NAME 프로시저

클라우드 객체 저장소에 저장된 메시지에 대한 기본 인증서로 사용되는 credential_name 변수를 설정합니다.

SET_LOCATION_URI 프로시저

클라우드 객체 저장소에 저장된 메시지에 대한 기본 위치 URI로 사용되는 전역 location_uri 변수를 설정합니다.

UNIQUE_SESSION_NAME 함수

고유한 세션 이름을 반환합니다.
UNPACK_MESSAGE 프로시저

버퍼의 다음 항목에 액세스합니다.

CREATE_PIPE 함수

이 함수는 공용 또는 전용 파이프를 명시적으로 작성합니다. private 플래그가 TRUE인 경우 파이프 작성자가 개인 파이프의 소유자로 지정됩니다.

명시적으로 생성된 파이프는 REMOVE_PIPE를 호출하거나 인스턴스를 종료해야만 제거할 수 있습니다.

구문

DBMS_PIPE.CREATE_PIPE (
   pipename     IN VARCHAR2,
   maxpipesize  IN INTEGER DEFAULT 66536,
   private      IN BOOLEAN DEFAULT TRUE)
RETURN INTEGER;

매개변수

테이블 - CREATE_PIPE 함수 매개변수

매개변수 설명

pipename

만들려는 파이프의 이름입니다.

SEND_MESSAGE 및 RECEIVE_MESSAGE를 호출할 때 이 이름을 사용해야 합니다. 이 이름은 전체 인스턴스에서 고유해야 합니다.

주의: ORA$로 시작하는 파이프 이름은 사용하지 마십시오. Oracle에서 제공하는 프로시저에서 사용하도록 예약되어 있습니다. Pipename은 128바이트보다 길지 않아야 하며 대소문자를 구분하지 않습니다. 현재 이름은 Globalization Support 문자를 포함할 수 없습니다.

maxpipesize

파이프에 대해 허용된 최대 크기(바이트)입니다.

파이프에 있는 모든 메시지의 총 크기는 이 양을 초과할 수 없습니다. 이 최대값을 초과하면 메시지가 차단됩니다.

기본 maxpipesize는 66536바이트입니다.

파이프의 maxpipesize는 파이프 특성의 일부가 되며 파이프 수명 동안 지속됩니다. 값이 큰 SEND_MESSAGE를 호출하면 maxpipesize가 증가합니다. 값이 작은 호출자는 더 큰 기존 값을 사용합니다.

모든 파이프에 대해 기본값 maxpipesize 65536을 적용할 수 있습니다.

private

기본값 TRUE를 사용하여 개인 파이프를 만듭니다.

공용 파이프는 SEND_MESSAGE를 호출할 때 암시적으로 생성할 수 있습니다.

반환 값

테이블 - CREATE_PIPE 함수 반환 값

Return 설명

0

성공.

파이프가 이미 있고 파이프를 만들려는 사용자가 파이프를 사용할 권한이 있는 경우 Oracle은 성공을 나타내는 0을 반환하며 파이프에 이미 있는 모든 데이터는 남아 있습니다.

ORA-23322

이름 지정 충돌로 인해 실패했습니다.

이름이 동일한 파이프가 있고 다른 사용자가 만든 경우 Oracle은 이름 지정 충돌을 나타내는 오류 ORA-23322를 표시합니다.

예외사항

테이블 - CREATE_PIPE 함수 예외

예외사항 설명

Null pipe name

권한 오류: 동일한 이름의 파이프가 이미 있으며 사용할 수 없습니다.

예

MY_PIPE1라는 명시적 private를 생성합니다.

DECLARE
  l_status INTEGER;
BEGIN
  l_status := DBMS_PIPE.create_pipe(
      pipename  => 'MY_PIPE1',
      private   => TRUE);
END;
/

GET_CREDENTIAL_NAME 함수

이 함수는 메시지가 클라우드 객체 저장소에 저장될 때 사용할 전역 credential_name 변수 값을 반환합니다.

구문

DBMS_PIPE.GET_CREDENTIAL_NAME
         RETURN VARCHAR2;

반환 값

반환 값 설명

credential_name

클라우드 객체 스토리지에 액세스할 인증서의 이름입니다.

예

DECLARE
  credential_name     VARCHAR2(400)
BEGIN
  credential_name := DBMS_PIPE.GET_CREDENTIAL_NAME;
END;
/

GET_LOCATION_URI 함수

이 함수는 파이프 메시지가 클라우드 객체 저장소에 저장될 때 기본 위치 URI로 사용될 수 있는 전역 location_uri 변수 값을 반환합니다.

구문

DBMS_PIPE.GET_LOCATION_URI
        RETURN VARCHAR2;

반환 값

반환 값 설명
location_uri

객체 URI입니다.

예

DECLARE
  location_uri     VARCHAR2(400)
BEGIN
  location_uri := DBMS_PIPE.GET_LOCATION_URI;
END;
/

RECEIVE_MESSAGE 함수

이 함수는 메시지를 로컬 메시지 버퍼로 복사합니다.

구문

DBMS_PIPE.RECEIVE_MESSAGE (
   pipename          IN VARCHAR2,
   timeout           IN INTEGER  DEFAULT maxwait,
   credential_name   IN VARCHAR2 DEFAULT null,
   location_uri      IN VARCHAR2)
RETURN INTEGER;

매개변수

테이블 - RECEIVE_MESSAGE 함수 매개변수

매개변수 설명

pipename

메시지를 수신할 파이프의 이름입니다.

ORA$로 시작하는 이름은 Oracle에서 사용하도록 예약되어 있습니다.

timeout

메시지를 기다리는 시간(초)입니다. 시간 초과가 0이면 차단하지 않고 읽을 수 있습니다.

시간 초과에는 cache_func 매개변수로 지정된 캐시 함수를 실행하는 데 소요된 시간이 포함되지 않습니다.

기본값은 86400000(1000일)으로 정의된 상수 MAXWAIT입니다.

credential_name

메시지 저장에 사용되는 클라우드 저장소의 인증서 이름입니다.

credential_name는 기본적으로 NULL로 초기화된 패키지 인수입니다.

DBMS_PIPE.RECEIVE_MESSAGE를 호출하기 전에 이 값을 설정할 수 있습니다. 전달된 매개변수 값이 전역 변수 값보다 우선합니다.

자격 증명 객체는 DBMS_PIPE.RECEIVE_MESSAGE를 실행하는 사용자가 EXECUTE 및 READ/WRITE 권한을 가져야 합니다.

location_uri

메시지 저장에 사용되는 클라우드 저장소의 위치 URI입니다.

location_uri는 기본적으로 NULL로 초기화되는 전역 변수입니다.

DBMS_PIPE.RECEIVE_MESSAGE를 호출하기 전에 이 값을 설정할 수 있습니다. 전달된 매개변수 값이 전역 변수 값보다 우선합니다.

반환 값

테이블 - RECEIVE_MESSAGE 함수 반환 값

Return 설명

0

성공

1

시간 초과됨. 파이프가 암시적으로 작성되고 비어 있으면 제거됩니다.

2

파이프의 레코드가 버퍼에 비해 너무 큽니다.

3

인터럽트 발생.

ORA-23322

사용자에게 파이프에서 읽을 수 있는 충분한 권한이 없습니다.

사용법 참고

  • 파이프에서 메시지를 수신하려면 먼저 RECEIVE_MESSAGE을 호출합니다. 메시지를 받으면 파이프에서 제거되므로 한 번만 메시지를 받을 수 있습니다. 암시적으로 작성된 파이프의 경우 파이프에서 마지막 레코드가 제거된 후 파이프가 제거됩니다.

  • RECEIVE_MESSAGE를 호출할 때 지정한 파이프가 존재하지 않을 경우 Oracle은 암시적으로 파이프를 만들고 메시지를 받을 때까지 기다립니다. 메시지가 지정된 시간 초과 간격 내에 도착하지 않으면 호출이 반환되고 파이프가 제거됩니다.

  • 메시지를 받은 후 메시지의 개별 항목에 액세스하려면 UNPACK_MESSAGE에 대해 하나 이상의 호출을 수행해야 합니다. UNPACK_MESSAGE 프로시저는 DATE, NUMBER, VARCHAR2 유형의 항목 포장을 풀기 위해 오버로드되며 RAW 및 ROWID 항목의 포장을 풀기 위한 두 가지 추가 절차가 있습니다. 압축을 풀려는 데이터 유형을 모르는 경우 NEXT_ITEM_TYPE를 호출하여 버퍼의 다음 항목 유형을 확인합니다.

  • 지속 메시지는 정확히 하나의 프로세스에서 쓰거나 읽도록 보장됩니다. 이렇게 하면 동시 쓰기 및 읽기로 인해 메시지 내용이 일치하지 않습니다. DBMS_PIPE에서는 영구 메시징 파이프를 사용하여 한 번에 메시지 또는 수신 메시지를 보내는 작업이 하나만 활성화되도록 허용합니다. 그러나 진행 중인 작업으로 인해 작업이 불가능한 경우 timeout 값에 도달할 때까지 프로세스가 주기적으로 재시도됩니다.

  • Oracle Cloud Infrastructure Object Storage를 사용하여 메시지를 저장하는 경우 Oracle Cloud Infrastructure 고유 URI 또는 Swift URI를 사용할 수 있습니다. 그러나 위치 URI와 자격 증명은 다음과 같은 유형과 일치해야 합니다.

    • 고유 URI 형식을 사용하여 Oracle Cloud Infrastructure Object Storage에 액세스하는 경우 인증서 객체에서 고유 Oracle Cloud Infrastructure 서명 키 인증을 사용해야 합니다.

    • Swift URI 형식을 사용하여 Oracle Cloud Infrastructure Object Storage에 액세스하는 경우 인증서 객체에서 인증 토큰 인증을 사용해야 합니다.

예외사항

표 - RECEIVE_MESSAGE 함수 예외

예외사항 설명

Null pipe name

권한 오류. 권한이 부족하여 파이프에서 레코드를 제거할 수 없습니다. 파이프는 다른 사람이 소유하고 있습니다.

SEND_MESSAGE 함수

이 함수는 명명된 파이프에 메시지를 보냅니다.

메시지는 PACK_MESSAGE에 대한 호출로 채워진 로컬 메시지 버퍼에 포함됩니다. CREATE_PIPE를 사용하여 명시적으로 파이프를 만들 수 있습니다. 그렇지 않으면 암시적으로 만들어집니다.

구문

DBMS_PIPE.SEND_MESSAGE (
    pipename          IN VARCHAR2,
    timeout           IN INTEGER DEFAULT MAXWAIT,
    credential_name   IN VARCHAR2 DEFAULT null,
    location_uri      IN VARCHAR2 )
RETURN INTEGER;

매개변수

테이블 - SEND_MESSAGE 함수 매개변수

매개변수 설명
credential_name

메시지 저장에 사용되는 클라우드 저장소의 인증서 이름입니다.

credential_name는 기본적으로 NULL로 초기화된 패키지 인수입니다.

DBMS_PIPE.SEND_MESSAGE를 호출하기 전에 이 값을 설정할 수 있습니다. 전달된 매개변수 값이 전역 변수 값보다 우선합니다.

자격 증명 객체는 DBMS_PIPE.SEND_MESSAGE를 실행하는 사용자가 EXECUTE 및 READ/WRITE 권한을 가져야 합니다.

location_uri

메시지 저장에 사용되는 클라우드 저장소의 위치 URI입니다.

location_uri는 기본적으로 NULL로 초기화되는 전역 변수입니다.

DBMS_PIPE.SEND_MESSAGE를 호출하기 전에 이 값을 설정할 수 있습니다. 전달된 매개변수 값이 전역 변수 값보다 우선합니다.

maxpipesize

파이프에 허용되는 최대 크기(바이트).

파이프에 있는 모든 메시지의 총 크기는 이 양을 초과할 수 없습니다. 이 최대값을 초과하면 메시지가 차단됩니다. 기본값은 65536바이트입니다.

파이프의 maxpipesize는 파이프 특성의 일부가 되며 파이프 수명 동안 지속됩니다. 값이 큰 SEND_MESSAGE를 호출하면 maxpipesize가 증가합니다. 값이 작은 호출자는 더 큰 기존 값을 사용합니다.

maxpipesize를 SEND_MESSAGE 프로시저의 일부로 지정하면 파이프를 열기 위한 별도의 호출이 필요하지 않습니다. 파이프를 명시적으로 작성한 경우 선택적 maxpipesize 매개변수를 사용하여 작성 파이프 크기 지정을 재지정할 수 있습니다.

모든 파이프에 대해 기본값 maxpipesize 65536을 적용할 수 있습니다.

pipename

메시지를 배치할 파이프의 이름입니다.

명시적 파이프를 사용하는 경우 CREATE_PIPE를 호출할 때 지정한 이름입니다.

주의: 'ORA$'로 시작하는 파이프 이름은 사용하지 마십시오. 이러한 이름은 Oracle에서 제공하는 프로시저에서 사용하도록 예약되어 있습니다. Pipename은 128바이트보다 길지 않아야 하며 대소문자를 구분하지 않습니다. 현재 이름은 Globalization Support 문자를 포함할 수 없습니다.

timeout

파이프에 메시지를 배치하려고 시도하는 동안 기다리는 시간(초)입니다.

기본값은 상수 MAXWAIT이며 86400000(1000일)으로 정의됩니다.

반환 값

테이블 - SEND_MESSAGE 함수 반환 값

Return 설명

0

성공.

파이프가 이미 있고 파이프를 만들려는 사용자가 파이프를 사용할 권한이 있는 경우 Oracle은 성공을 나타내는 0을 반환하며 파이프에 이미 있는 모든 데이터는 남아 있습니다.

SYSDBS/SYSOPER로 연결된 사용자가 파이프를 다시 만들면 Oracle은 상태 0을 반환하지만 파이프 소유권은 변경되지 않은 상태로 유지됩니다.

1

시간 초과됨.

이 절차는 파이프에 대한 잠금을 얻을 수 없거나 파이프가 너무 가득 차서 사용할 수 없기 때문에 시간 초과될 수 있습니다. 파이프가 암시적으로 작성되고 비어 있으면 제거됩니다.

3

인터럽트 발생.

파이프가 암시적으로 작성되고 비어 있으면 제거됩니다.

ORA-23322

권한이 없습니다.

이름이 동일한 파이프가 있고 다른 사용자가 만든 경우 Oracle은 이름 지정 충돌을 나타내는 오류 ORA-23322를 표시합니다.

사용법 참고

  • 지속 메시지는 정확히 하나의 프로세스에서 쓰거나 읽도록 보장됩니다. 이렇게 하면 동시 쓰기 및 읽기로 인해 메시지 내용이 일치하지 않습니다. DBMS_PIPE에서는 영구 메시징 파이프를 사용하여 한 번에 메시지 또는 수신 메시지를 보내는 작업이 하나만 활성화되도록 허용합니다. 그러나 진행 중인 작업으로 인해 작업이 불가능한 경우 timeout 값에 도달할 때까지 프로세스가 주기적으로 재시도됩니다.

  • Oracle Cloud Infrastructure Object Storage를 사용하여 메시지를 저장하는 경우 Oracle Cloud Infrastructure 고유 URI 또는 Swift URI를 사용할 수 있습니다. 그러나 위치 URI와 자격 증명은 다음과 같은 유형과 일치해야 합니다.

    • 고유 URI 형식을 사용하여 Oracle Cloud Infrastructure Object Storage에 액세스하는 경우 인증서 객체에서 고유 Oracle Cloud Infrastructure 서명 키 인증을 사용해야 합니다.

    • Swift URI 형식을 사용하여 Oracle Cloud Infrastructure Object Storage에 액세스하는 경우 인증서 객체에서 인증 토큰 인증을 사용해야 합니다.

예외사항

테이블 - SEND_MESSAGE 함수 예외

예외사항 설명

Null pipe name

권한 오류. 권한이 부족하여 파이프에 쓸 수 없습니다. 파이프는 개인용이며 다른 사람이 소유합니다.

SET_CREDENTIAL_NAME 프로시저

이 절차에서는 파이프 메시지가 클라우드 객체 저장소에 저장될 때 기본 인증서로 사용되는 credential_name 변수를 설정합니다.

구문

DBMS_PIPE.SET_CREDENTIAL_NAME (
   credential_name   IN VARCHAR2 );

매개변수

매개변수 설명

credential_name

클라우드 객체 스토리지에 액세스할 인증서의 이름입니다.

사용법 노트

Oracle Cloud Infrastructure Object Storage를 사용하여 메시지를 저장하는 경우 Oracle Cloud Infrastructure 고유 URI 또는 Swift URI를 사용할 수 있습니다. 그러나 위치 URI와 자격 증명은 다음과 같은 유형과 일치해야 합니다.

  • 고유 URI 형식을 사용하여 Oracle Cloud Infrastructure Object Storage에 액세스하는 경우 인증서 객체에서 고유 Oracle Cloud Infrastructure 서명 키 인증을 사용해야 합니다.

  • Swift URI 형식을 사용하여 Oracle Cloud Infrastructure Object Storage에 액세스하는 경우 인증서 객체에서 인증 토큰 인증을 사용해야 합니다.

예

BEGIN
     DBMS_PIPE.SET_CREDENTIAL_NAME(
       credential_name =>  'my_cred1');
END;
/

SET_LOCATION_URI 프로시저

이 절차에서는 전역 location_uri 변수를 설정합니다.

구문

DBMS_PIPE.SET_LOCATION_URI (
   location_uri   IN VARCHAR2 );

매개변수

매개변수 설명
location_uri

객체 또는 파일 URI입니다. URI의 형식은 사용 중인 클라우드 오브젝트 스토리지 서비스에 따라 다릅니다. 자세한 내용은 클라우드 오브젝트 스토리지 URI 형식을 참조하십시오.

사용법 노트

Oracle Cloud Infrastructure Object Storage를 사용하여 메시지를 저장하는 경우 Oracle Cloud Infrastructure 고유 URI 또는 Swift URI를 사용할 수 있습니다. 그러나 위치 URI와 자격 증명은 다음과 같은 유형과 일치해야 합니다.

  • 고유 URI 형식을 사용하여 Oracle Cloud Infrastructure Object Storage에 액세스하는 경우 인증서 객체에서 고유 Oracle Cloud Infrastructure 서명 키 인증을 사용해야 합니다.

  • Swift URI 형식을 사용하여 Oracle Cloud Infrastructure Object Storage에 액세스하는 경우 인증서 객체에서 인증 토큰 인증을 사용해야 합니다.

예

BEGIN
  DBMS_PIPE.GET_LOCATION_URI(
      location_uri  => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname1/');
END;
/