11g リリース1（11.1）
E05768-02
 目次 |
 索引 |
| Oracle Databaseユーティリティ 11g リリース1（11.1） E05768-02 |
|
データ・ポンプAPI（DBMS_DATAPUMP）は、あるサイトのデータおよびメタデータのすべてまたは一部をデータベース間で移動するための高速メカニズムを提供します。データ・ポンプ・エクスポートおよびデータ・ポンプ・インポート・ユーティリティはデータ・ポンプAPIに基づいています。
この章では、データ・ポンプAPIの機能を詳細に説明します。この章の内容は、次のとおりです。
参照:
DBMS_DATAPUMPパッケージで使用可能なプロシージャの詳細は、『Oracle Database PL/SQLパッケージ・プロシージャおよびタイプ・リファレンス』を参照してください。
クライアント・インタフェースで使用されている主な構造体はジョブ・ハンドルで、コール元に対しては整数として表示されます。ハンドルは、DBMS_DATAPUMP.OPENファンクションまたはDBMS_DATAPUMP.ATTACHファンクションを使用して作成します。他のセッションをジョブに接続してその進捗状況を監視および制御できます。この機能によって、DBAは帰宅前にジョブを開始して、自宅でその進捗状況を確認できます。ハンドルはセッション固有です。同じジョブによって、セッションごとに異なるハンドルを作成できます。
次に、各フェーズに関連付けられたジョブの状態を示します。
DBMS_DATAPUMP.START_JOBプロシージャの実行時
DBMS_DATAPUMP.ATTACHが実行されてから、そのジョブを再開するためにDBMS_DATAPUMP.START_JOBが実行されるまでの期間
「アイドル」状態のジョブに対してDBMS_DATAPUMP.START_JOBを実行すると、「実行中」状態に戻ります。
すべてのユーザーがDBMS_DATAPUMP.DETACHを実行して「定義中」状態のジョブとの接続を切断すると、そのジョブはデータベースから完全に削除されます。
ジョブが異常終了した場合またはジョブを実行しているインスタンスが停止した場合、「実行中」または「アイドル」状態のジョブは「未実行」状態になります。ユーザーは、その状態からジョブを再開できます。
マスター制御プロセスは、「定義中」、「アイドル」、「実行中」、「停止処理中」、「停止保留」、「完了処理中」の状態でアクティブです。また、一時的に「停止」および「完了」の状態にもなります。ジョブのマスター表は、「未定義」状態を除いてすべての状態で存在します。ワーカー・プロセスは「実行中」および「停止保留」状態、つまりインポート・ジョブに対する「定義中」状態でのみアクティブです。
ジョブの状態が「実行中」の場合に接続を切断しても、そのジョブは停止しません。実行中のジョブにはいつでも再接続して、ジョブに関する状態情報を再度取得できます。
DBMS_DATAPUMP.DETACHプロシージャが実行されると、明示的に切断されることがあります。または、データ・ポンプAPIセッションが停止した場合や、データ・ポンプAPIがデータ・ポンプ・ジョブと通信できない場合、もしくはDBMS_DATAPUMP.STOP_JOBプロシージャが実行された場合は、暗黙的に切断されることがあります。
「未実行」状態は、実行中のジョブのコンテキストの外部にマスター表が存在することを示します。この状態は、（後で再開するために）ジョブが停止された場合またはジョブが異常終了した場合に発生します。また、この状態は、ジョブの開始時に行われるジョブの状態の移行中、およびマスター表を削除する前に行うジョブの終了時に、一時的に発生する場合があります。「未実行」状態は、DBA_DATAPUMP_JOBSビューおよびUSER_DATAPUMP_JOBSビューでのみ表示されます。GET_STATUSプロシージャから返されることはありません。
表5-1に、DBMS_DATAPUMPプロシージャを実行できる有効なジョブの状態を示します。この表に示す状態は、特に指定がないかぎり、エクスポートとインポートの両方で有効です。
| プロシージャ名 | 有効な状態 | 説明 |
|---|---|---|
ADD_FILE |
定義中（エクスポート・ジョブとインポート・ジョブの両方で有効） 実行中、アイドル（エクスポート・ジョブでダンプ・ファイルを指定する場合にのみ有効） |
ダンプ・ファイル・セット、ログ・ファイル、またはSQL_FILEの出力用のファイルを指定する。 |
ATTACH |
定義中、実行中、アイドル、停止、完了、完了処理中、未実行 |
ユーザー・セッションで、ジョブの監視または停止したジョブの再開を可能にする。ジョブのダンプ・ファイル・セットまたはマスター表が削除または変更されている場合、接続操作は失敗します。 |
DATA_FILTER |
定義中 |
ジョブが処理するデータを制限する。 |
DETACH |
すべての状態 |
ユーザー・セッションをジョブから切断する。 |
GET_DUMPFILE_INFO |
すべての状態 |
ダンプ・ファイルのヘッダー情報を取得する。 |
GET_STATUS |
完了、未実行、停止および未定義を除くすべての状態 |
ジョブの状態を取得する。 |
LOG_ENTRY |
定義中、実行中、アイドル、停止保留、完了処理中 |
ログ・ファイルにエントリを追加する。 |
METADATA_FILTER |
定義中 |
ジョブが処理するメタデータを制限する。 |
METADATA_REMAP |
定義中 |
ジョブが処理するメタデータを再マップする。 |
METADATA_TRANSFORM |
定義中 |
ジョブが処理するメタデータを変更する。 |
OPEN |
未定義 |
新しいジョブを作成する。 |
SET_PARALLEL |
定義中、実行中、アイドル |
ジョブの並列度を指定する。 |
SET_PARAMETER |
定義中1 |
ジョブのデフォルトの処理を変更する。 |
START_JOB |
定義中、アイドル |
ジョブを開始または再開する。 |
STOP_JOB |
定義中、実行中、アイドル、停止保留 |
ジョブの停止を開始する。 |
WAIT_FOR_JOB |
完了、未実行、停止および未定義を除くすべての状態 |
ジョブの終了を待機する。 |
1
ENCRYPTION_PASSWORDパラメータは、「アイドル」状態および「定義中」状態のときに入力できます。 |
データ・ポンプAPIを使用するには、DBMS_DATAPUMPパッケージで提供されるプロシージャを使用します。次の手順では、データ・ポンプAPIの使用に関連する基本操作を示します。通常操作を行う順序でこれらの手順を示します。
DBMS_DATAPUMP.OPENプロシージャを実行して、データ・ポンプ・ジョブとのそのインフラストラクチャを作成します。
これらの手順の概要は、次の項で示す使用例で説明します。
この項では、データ・ポンプAPIの使用方法を理解するために有効な例を示します。
これらの例は、PL/SQLスクリプトの形式で記述します。これらのスクリプトをコピーして実行するには、まず、SQL*Plusを使用して次の操作を実行する必要があります。
READおよびWRITE権限を付与します。たとえば、権限を持つdmpdirというディレクトリ・オブジェクトを作成するには、次のように行います。userは、ユーザー名に置き換えます。
SQL> CREATE DIRECTORY dmpdir AS '/rdbms/work'; SQL> GRANT READ, WRITE ON DIRECTORY dmpdir TO user
EXP_FULL_DATABASEロールおよびIMP_FULL_DATABASEロールを所有していることを確認します。セキュリティ・ドメイン内でユーザー自身に割り当てられているすべてのロールのリストを表示するには、次のように行います。
SQL> SELECT * FROM SESSION_ROLES;
必要なロールが割り当てられていない場合は、システム管理者に連絡してください。
SQL> SET SERVEROUTPUT ON
これを行わなかった場合は、画面に出力が表示されません。この操作は、例を実行するセッションと同じセッションで行う必要があります。この設定は、SQL*Plusを終了すると失われるため、新しいセッションの開始時に再設定する必要があります。（別のユーザー名に接続する場合も、再設定する必要があります。）
次の例のPL/SQLスクリプトは、データ・ポンプAPIを使用してHRスキーマのスキーマ・エクスポートを簡単に実行する方法を示しています。ジョブの作成、開始、監視の方法を示しています。この例の詳細は、スクリプト内のコメントを参照してください。例を簡単にしておくために、APIのコールでの例外は検出されません。ただし、本番環境でエラーが発生した場合は、例外ハンドラを定義してGET_STATUSをコールし、エラー情報の詳細を取得することをお薦めします。
このスクリプトを使用するには、ユーザーSYSTEMとして接続します。
DECLARE ind NUMBER; -- Loop index h1 NUMBER; -- Data Pump job handle percent_done NUMBER; -- Percentage of job complete job_state VARCHAR2(30); -- To keep track of job state le ku$_LogEntry; -- For WIP and error messages js ku$_JobStatus; -- The job status from get_status jd ku$_JobDesc; -- The job description from get_status sts ku$_Status; -- The status object returned by get_status BEGIN -- Create a (user-named) Data Pump job to do a schema export. h1 := DBMS_DATAPUMP.OPEN('EXPORT','SCHEMA',NULL,'EXAMPLE1','LATEST'); -- Specify a single dump file for the job (using the handle just returned) -- and a directory object, which must already be defined and accessible -- to the user running this procedure. DBMS_DATAPUMP.ADD_FILE(h1,'example1.dmp','DMPDIR'); -- A metadata filter is used to specify the schema that will be exported. DBMS_DATAPUMP.METADATA_FILTER(h1,'SCHEMA_EXPR','IN (''HR'')'); -- Start the job. An exception will be generated if something is not set up -- properly. DBMS_DATAPUMP.START_JOB(h1); -- The export job should now be running. In the following loop, the job -- is monitored until it completes. In the meantime, progress information is -- displayed. percent_done := 0; job_state := 'UNDEFINED'; while (job_state != 'COMPLETED') and (job_state != 'STOPPED') loop dbms_datapump.get_status(h1, dbms_datapump.ku$_status_job_error + dbms_datapump.ku$_status_job_status + dbms_datapump.ku$_status_wip,-1,job_state,sts); js := sts.job_status; -- If the percentage done changed, display the new value. if js.percent_done != percent_done then dbms_output.put_line('*** Job percent done = ' || to_char(js.percent_done)); percent_done := js.percent_done; end if; -- If any work-in-progress (WIP) or error messages were received for the job, -- display them. if (bitand(sts.mask,dbms_datapump.ku$_status_wip) != 0) then le := sts.wip; else if (bitand(sts.mask,dbms_datapump.ku$_status_job_error) != 0) then le := sts.error; else le := null; end if; end if; if le is not null then ind := le.FIRST; while ind is not null loop dbms_output.put_line(le(ind).LogText); ind := le.NEXT(ind); end loop; end if; end loop; -- Indicate that the job finished and detach from it. dbms_output.put_line('Job has completed'); dbms_output.put_line('Final job state = ' || job_state); dbms_datapump.detach(h1); END; /例5-2 ダンプ・ファイルのインポートおよびすべてのスキーマ・オブジェクトの再マップ
この例のスクリプトでは、例5-1（hrスキーマのエクスポート）で作成したダンプ・ファイルをインポートします。すべてのスキーマ・オブジェクトがhrスキーマからblakeスキーマに再マップされます。例を簡単にしておくために、APIのコールでの例外は検出されません。ただし、本番環境でエラーが発生した場合は、例外ハンドラを定義してGET_STATUSをコールし、エラー情報の詳細を取得することをお薦めします。
このスクリプトを使用するには、ユーザーSYSTEMとして接続します。
DECLARE ind NUMBER; -- Loop index h1 NUMBER; -- Data Pump job handle percent_done NUMBER; -- Percentage of job complete job_state VARCHAR2(30); -- To keep track of job state le ku$_LogEntry; -- For WIP and error messages js ku$_JobStatus; -- The job status from get_status jd ku$_JobDesc; -- The job description from get_status sts ku$_Status; -- The status object returned by get_status BEGIN -- Create a (user-named) Data Pump job to do a "full" import (everything -- in the dump file without filtering). h1 := DBMS_DATAPUMP.OPEN('IMPORT','FULL',NULL,'EXAMPLE2'); -- Specify the single dump file for the job (using the handle just returned) -- and directory object, which must already be defined and accessible -- to the user running this procedure. This is the dump file created by -- the export operation in the first example. DBMS_DATAPUMP.ADD_FILE(h1,'example1.dmp','DMPDIR'); -- A metadata remap will map all schema objects from HR to BLAKE. DBMS_DATAPUMP.METADATA_REMAP(h1,'REMAP_SCHEMA','HR','BLAKE'); -- If a table already exists in the destination schema, skip it (leave -- the preexisting table alone). This is the default, but it does not hurt -- to specify it explicitly. DBMS_DATAPUMP.SET_PARAMETER(h1,'TABLE_EXISTS_ACTION','SKIP'); -- Start the job. An exception is returned if something is not set up properly. DBMS_DATAPUMP.START_JOB(h1); -- The import job should now be running. In the following loop, the job is -- monitored until it completes. In the meantime, progress information is -- displayed. Note: this is identical to the export example. percent_done := 0; job_state := 'UNDEFINED'; while (job_state != 'COMPLETED') and (job_state != 'STOPPED') loop dbms_datapump.get_status(h1, dbms_datapump.ku$_status_job_error + dbms_datapump.ku$_status_job_status + dbms_datapump.ku$_status_wip,-1,job_state,sts); js := sts.job_status; -- If the percentage done changed, display the new value. if js.percent_done != percent_done then dbms_output.put_line('*** Job percent done = ' || to_char(js.percent_done)); percent_done := js.percent_done; end if; -- If any work-in-progress (WIP) or Error messages were received for the job, -- display them. if (bitand(sts.mask,dbms_datapump.ku$_status_wip) != 0) then le := sts.wip; else if (bitand(sts.mask,dbms_datapump.ku$_status_job_error) != 0) then le := sts.error; else le := null; end if; end if; if le is not null then ind := le.FIRST; while ind is not null loop dbms_output.put_line(le(ind).LogText); ind := le.NEXT(ind); end loop; end if; end loop; -- Indicate that the job finished and gracefully detach from it. dbms_output.put_line('Job has completed'); dbms_output.put_line('Final job state = ' || job_state); dbms_datapump.detach(h1); END; /例5-3 簡単なスキーマ・エクスポート実行中の例外処理機能の使用方法
この例のスクリプトでは、データ・ポンプAPIを使用した簡単なスキーマ・エクスポートを示します。例5-1の延長で、例外処理機能を使用してSUCCESS_WITH_INFOケースを捕捉する方法およびGET_STATUSプロシージャを使用したエラーの詳細を取得する方法を示します。DBMS_DATAPUMP.OPENまたはDBMS_DATAPUMP.ATTACHエラーの例外情報を取得する場合は、DBMS_DATAPUMP.KU$_STATUS_JOB_ERROR情報マスクとNULLジョブ・ハンドルを使用してDBMS_DATAPUMP.GET_STATUSをコールし、エラー情報の詳細を取得できます。
この例を使用するには、ユーザーSYSTEMとして接続します。
DECLARE ind NUMBER; -- Loop index spos NUMBER; -- String starting position slen NUMBER; -- String length for output h1 NUMBER; -- Data Pump job handle percent_done NUMBER; -- Percentage of job complete job_state VARCHAR2(30); -- To keep track of job state le ku$_LogEntry; -- For WIP and error messages js ku$_JobStatus; -- The job status from get_status jd ku$_JobDesc; -- The job description from get_status sts ku$_Status; -- The status object returned by get_status BEGIN -- Create a (user-named) Data Pump job to do a schema export. h1 := dbms_datapump.open('EXPORT','SCHEMA',NULL,'EXAMPLE3','LATEST'); -- Specify a single dump file for the job (using the handle just returned) -- and a directory object, which must already be defined and accessible -- to the user running this procedure. dbms_datapump.add_file(h1,'example3.dmp','DMPDIR'); -- A metadata filter is used to specify the schema that will be exported. dbms_datapump.metadata_filter(h1,'SCHEMA_EXPR','IN (''HR'')'); -- Start the job. An exception will be returned if something is not set up -- properly.One possible exception that will be handled differently is the -- success_with_info exception. success_with_info means the job started -- successfully, but more information is available through get_status about -- conditions around the start_job that the user might want to be aware of. begin dbms_datapump.start_job(h1); dbms_output.put_line('Data Pump job started successfully'); exception when others then if sqlcode = dbms_datapump.success_with_info_num then dbms_output.put_line('Data Pump job started with info available:'); dbms_datapump.get_status(h1, dbms_datapump.ku$_status_job_error,0, job_state,sts); if (bitand(sts.mask,dbms_datapump.ku$_status_job_error) != 0) then le := sts.error; if le is not null then ind := le.FIRST; while ind is not null loop dbms_output.put_line(le(ind).LogText); ind := le.NEXT(ind); end loop; end if; end if; else raise; end if; end; -- The export job should now be running. In the following loop, we will monitor -- the job until it completes. In the meantime, progress information is -- displayed. percent_done := 0; job_state := 'UNDEFINED'; while (job_state != 'COMPLETED') and (job_state != 'STOPPED') loop dbms_datapump.get_status(h1, dbms_datapump.ku$_status_job_error + dbms_datapump.ku$_status_job_status + dbms_datapump.ku$_status_wip,-1,job_state,sts); js := sts.job_status; -- If the percentage done changed, display the new value. if js.percent_done != percent_done then dbms_output.put_line('*** Job percent done = ' || to_char(js.percent_done)); percent_done := js.percent_done; end if; -- Display any work-in-progress (WIP) or error messages that were received for -- the job. if (bitand(sts.mask,dbms_datapump.ku$_status_wip) != 0) then le := sts.wip; else if (bitand(sts.mask,dbms_datapump.ku$_status_job_error) != 0) then le := sts.error; else le := null; end if; end if; if le is not null then ind := le.FIRST; while ind is not null loop dbms_output.put_line(le(ind).LogText); ind := le.NEXT(ind); end loop; end if; end loop; -- Indicate that the job finished and detach from it. dbms_output.put_line('Job has completed'); dbms_output.put_line('Final job state = ' || job_state); dbms_datapump.detach(h1); -- Any exceptions that propagated to this point will be captured. The -- details will be retrieved from get_status and displayed. exception when others then dbms_output.put_line('Exception in Data Pump job'); dbms_datapump.get_status(h1,dbms_datapump.ku$_status_job_error,0, job_state,sts); if (bitand(sts.mask,dbms_datapump.ku$_status_job_error) != 0) then le := sts.error; if le is not null then ind := le.FIRST; while ind is not null loop spos := 1; slen := length(le(ind).LogText); if slen > 255 then slen := 255; end if; while slen > 0 loop dbms_output.put_line(substr(le(ind).LogText,spos,slen)); spos := spos + 255; slen := length(le(ind).LogText) + 1 - spos; end loop; ind := le.NEXT(ind); end loop; end if; end if; END; /
|
 Copyright © 2007 Oracle Corporation. All Rights Reserved. |
|