Because Data Pump is server-based rather than client-based, dump files, log files, and SQL files are accessed relative to server-based directory paths. Data Pump requires that directory paths be specified as directory objects. A directory object maps a name to a directory path on the file system. DBAs must ensure that only approved users are allowed access to the directory object associated with the directory path.
The following example shows a SQL statement that creates a directory object named
dpump_dir1 that is mapped to a directory located at
SQL> CREATE DIRECTORY dpump_dir1 AS '/usr/apps/datafiles';
The reason that a directory object is required is to ensure data security and integrity. For example:
If you were allowed to specify a directory path location for an input file, then you might be able to read data that the server has access to, but to which you should not.
If you were allowed to specify a directory path location for an output file, then the server might overwrite a file that you might not normally have privileges to delete.
On UNIX and Windows operating systems, a default directory object,
DATA_PUMP_DIR, is created at database creation or whenever the database dictionary is upgraded. By default, it is available only to privileged users. (The user
SYSTEM has read and write access to the
DATA_PUMP_DIR directory, by default.)
If you are not a privileged user, then before you can run Data Pump Export or Data Pump Import, a directory object must be created by a database administrator (DBA) or by any user with the
After a directory is created, the user creating the directory object must grant
WRITE permission on the directory to other users. For example, to allow the Oracle database to read and write files on behalf of user
hr in the directory named by
dpump_dir1, the DBA must execute the following command:
SQL> GRANT READ, WRITE ON DIRECTORY dpump_dir1 TO hr;
WRITE permission to a directory object only means that the Oracle database can read or write files in the corresponding directory on your behalf. You are not given direct access to those files outside of the Oracle database unless you have the appropriate operating system privileges. Similarly, the Oracle database requires permission from the operating system to read and write files in the directories.
Data Pump Export and Import use the following order of precedence to determine a file's location:
If a directory object is specified as part of the file specification, then the location specified by that directory object is used. (The directory object must be separated from the file name by a colon.)
If a directory object is not specified as part of the file specification, then the directory object named by the
DIRECTORY parameter is used.
If a directory object is not specified as part of the file specification, and if no directory object is named by the
DIRECTORY parameter, then the value of the environment variable,
DATA_PUMP_DIR, is used. This environment variable is defined using operating system commands on the client system where the Data Pump Export and Import utilities are run. The value assigned to this client-based environment variable must be the name of a server-based directory object, which must first be created on the server system by a DBA. For example, the following SQL statement creates a directory object on the server system. The name of the directory object is
DUMP_FILES1, and it is located at
SQL> CREATE DIRECTORY DUMP_FILES1 AS '/usr/apps/dumpfiles1';
Then, a user on a UNIX-based client system using
csh can assign the value
DUMP_FILES1 to the environment variable
DIRECTORY parameter can then be omitted from the command line. The dump file
employees.dmp, and the log file
export.log, are written to
%setenv DATA_PUMP_DIR DUMP_FILES1 %expdp hr TABLES=employees DUMPFILE=employees.dmp
If none of the previous three conditions yields a directory object and you are a privileged user, then Data Pump attempts to use the value of the default server-based directory object,
DATA_PUMP_DIR. This directory object is automatically created at database creation or when the database dictionary is upgraded. You can use the following SQL query to see the path definition for
SQL> SELECT directory_name, directory_path FROM dba_directories 2 WHERE directory_name='DATA_PUMP_DIR';
If you are not a privileged user, then access to the
DATA_PUMP_DIR directory object must have previously been granted to you by a DBA.
Do not confuse the default
DATA_PUMP_DIR directory object with the client-based environment variable of the same name.
Keep the following considerations in mind when working in an Oracle RAC environment.
To use Data Pump or external tables in an Oracle RAC configuration, you must ensure that the directory object path is on a cluster-wide file system.
The directory object must point to shared physical storage that is visible to, and accessible from, all instances where Data Pump and/or external tables processes may run.
The default Data Pump behavior is that worker processes can run on any instance in an Oracle RAC configuration. Therefore, workers on those Oracle RAC instances must have physical access to the location defined by the directory object, such as shared storage media. If the configuration does not have shared storage for this purpose, but you still require parallelism, then you can use the
CLUSTER=NO parameter to constrain all worker processes to the instance where the Data Pump job was started.
Under certain circumstances, Data Pump uses parallel query slaves to load or unload data. In an Oracle RAC environment, Data Pump does not control where these slaves run, and they may run on other instances in the Oracle RAC, regardless of what is specified for
SERVICE_NAME for the Data Pump job. Controls for parallel query operations are independent of Data Pump. When parallel query slaves run on other instances as part of a Data Pump job, they also require access to the physical storage of the dump file set.
If you use Data Pump Export or Import with Oracle Automatic Storage Management (Oracle ASM) enabled, then you must define the directory object used for the dump file so that the Oracle ASM disk group name is used (instead of an operating system directory path). A separate directory object, which points to an operating system directory path, should be used for the log file. For example, you would create a directory object for the Oracle ASM dump file as follows:
SQL> CREATE or REPLACE DIRECTORY dpump_dir as '+DATAFILES/';
Then you would create a separate directory object for the log file:
SQL> CREATE or REPLACE DIRECTORY dpump_log as '/homedir/user1/';
To enable user
hr to have access to these directory objects, you would assign the necessary privileges, for example:
SQL> GRANT READ, WRITE ON DIRECTORY dpump_dir TO hr; SQL> GRANT READ, WRITE ON DIRECTORY dpump_log TO hr;
You would then use the following Data Pump Export command (you will be prompted for a password):
> expdp hr DIRECTORY=dpump_dir DUMPFILE=hr.dmp LOGFILE=dpump_log:hr.log
If you simply want to copy Data Pump dump files between ASM and disk directories, you can use the
DBMS_FILE_TRANSFER PL/SQL package.
The Export DIRECTORY parameter
The Import DIRECTORY parameter
Oracle Database SQL Language Reference for information about the
Oracle Automatic Storage Management Administrator's Guide for more information about Oracle ASM
Oracle Database PL/SQL Packages and Types Reference for more information about the
DBMS_FILE_TRANSFER PL/SQL package