foreignFileSpec

Purpose

Use the foreignFileSpec subclause to provide the information required to perform a cross-platform restore operation. This information includes the name of the backup set that contains the cross-platform backup and details of objects or files that must be restored.

Usage Notes

Specifying a foreignFileSpec is mandatory to perform a cross-platform restore operation. You can restore tablespaces even if the source platform and the destination platform use different endian formats.

Syntax

foreignFileSpec::=

Description of the illustration foreignfilespec.eps

(xfileList::=, xforeigndfList::=, handleNameList::=)

xfileList::=

Description of the illustration xfilelist.eps

xforeigndfList::=

Description of the illustration xforeigndflist.eps

privoptpdb::=

Description of the illustration privoptpdb.eps

handleNameList::=

Description of the illustration handlenamelist.eps

Semantics

xfilelist::=

Syntax Element	Description
`ALL FOREIGN DATAFILES`	Specifies that all the data files contained in the cross-platform backup set must be restored. Use `FROM BACKUPSET` along with `ALL FOREIGN DATAFILES` to specify the name of the backup set that contains the data files to be restored.
`FORMAT` `formatSpec`	Specifies a pattern for the restored data files in the destination database.
`TO NEW`	Specifies that the data files must be restored to the location specified by the `DB_CREATE_FILE_DEST` initialization parameter using Oracle Managed File (OMF) names.
`DUMP FILE` `'filename`'	Specifies that the backup set containing the Data Pump export dump file must be restored. The name of the backup set containing the dump file is specified using the `FROM BACKUPSET` clause. The dump file contains the metadata of the tablespaces that are being transported across platforms. You need this metadata to plug the restored tablespaces into the destination database. `filename` represents the name of the file into which the export dump file is restored.
`DATAPUMP DESTINATION` '`datapump_destination`'	Specifies the location to which the export dump file must be restored. If you omit this clause, the export dump file is restored to an operating system-dependent default location. The database must be opened in read-write mode when this clause is used, otherwise an error occurs.
`NOIMPORT`	Specifies that the export dump file must be restored, but not imported into the destination database. Because the export dump file is not imported, the tablespaces are not plugged in to the destination database. You need to manually import the dump file into the destination database using the Data Pump Import to plug the tablespaces.
`EXCLUDE`	Excludes statistics from the data pump export operation. To avoid creating large memory demands, you can choose to exclude statistics data in the export dump file. Use any or all of the following keywords to specify the criteria for `EXCLUDE`: `STATISTICS` `TABLE STATISTICS` `INDEX STATISTICS`
`XMLFILE filename`	Specifies the name of the unplug XML file that is created after a PDB is unplugged from a source PDB. Starting with Oracle Database 23ai, you can use regular RMAN backups of a PDB to transport the PDB from a source database to a destination database. If you are transporting a PDB using a backup of the PDB and an unplug XML file made in a previous release of Oracle Database, then you must include the `XMLFILE` clause when you perform the final restore operation on the destination database. See, Backup and Recovery User's Guide to learn more about the transporting PDBs using PDB backups.
`XMLFILE DESTINATION`	Specifies the directory where you want to extract and store the PDB unplug XML file on a destination database.
`FOREIGN DATABASE`	Specifies that the entire CDB must be restored from a cross-platform backup set. Use `FROM BACKUPSET` to specify the backup set that contains the cross-platform database backup. When `FOREIGN DATABASE` is used, the CDB must not be mounted, else an error occurs.
`FOREIGN PLUGGABLE DATABASE pdb_name`	Specifies that the pluggable database (PDB) specified by `pdb_name` must be restored from a cross-platform backup set. Use `FROM BACKUPSET` to specify the backup set that contains the cross-platform PDB backup. The CDB must not be mounted or else an error occurs.
`FOREIGN TABLESPACE` `tablespace_name`	Specifies the tablespaces that must be restored from the cross-platform backup set. The names of the tablespaces must be the original tablespaces names in the source database. Use `FROM BACKUPSET` to specify the name of the backup set that contains the cross-platform backup.

xforeigndfList::=

Syntax Element	Description
`FOREIGN DATAFILE` `integer`	Restores the specified data files that are contained in a cross-platform backup. You can choose to restore only some of the data files contained in the cross-platform backup set. Use `FROM BACKUPSET` to specify the name of the backup set that contains the cross-platform backup. `integer` specifies the absolute number of the data file in the source database.
`FORMAT formatSpec`	Specifies a pattern for the restored data files in the destination database.
`TO NEW`	Specifies that the data files must be restored to the location specified by the `DB_CREATE_FILE_DEST` initialization parameter using Oracle Managed File (OMF) names.
`FOREIGN PLUGGABLE DATABASE` `pdb_name`	Specifies that the pluggable database (PDB) specified by pdb_name must be transported to a destination database by using PDB backups. You can use regular PDB backups to transport a PDB from a source CDB to a destination CDB. When you perform the restore operation on a destination database, use the `RESTORE` command with the `FOREIGN PLUGGABLE DATABASE` clause to specify that RMAN must restore the data files from the backups of the PDB specified by pdb_name. Use the `FROM TRANSPORTLIST` or the `FROM TRANSPORTFILE` clause to specify the PDB backups that RMAN needs to use for the restore operation. See, Backup and Recovery User's Guide to learn more about transporting a PDB using a backup of the PDB.
`FOREIGN TABLESPACE` `tablespace_name`	Specifies the tablespace specified by tablespace_namethat must be transported to a destination database by using the tablespace backups. You can use regular tablespace backups to transport a tablespace from a source database to a destination database. When you perform a restore operation on the destination database, use the `RESTORE` command with the `FOREIGN TABLESPACE` command to specify that RMAN must restore the data files from the backups of the tablespace specified by tablespace_name. Use the `FROM TRANSPORTLIST` or the `FROM TRANSPORTFILE` clause to specify the tablespace backups that RMAN needs to use for the restore operation. See, Backup and Recovery User's Guide to learn more about transporting tablespaces using tablespace backups.
`FORMAT` formatSpec	Specifies a pattern for the restored data files in the destination database.
`TO NEW`	Specifies that the data files must be restored to the location specified by the `DB_CREATE_FILE_DEST` initialization parameter using Oracle Managed File (OMF) names

privoptpdb::=

Syntax Element Description

Syntax Element	Description
`OF` `PLUGGABLE DATABASE` `[` `database_name` \| `GUID` `guid_name` `]`	Specifies that RMAN must restore the data files of a new pluggable database (PDB) to an existing CDB. Specify either the name or the GUID that identifies the PDB. Use `FOREIGN DATAFILE` or `ALL FOREIGN DATAFILES` along with `OF PLUGGABLE DATABASE` `GUID` `guid_name` to restore the data files for the specified PDB in its own sub directory named with the GUID. Use `FROM BACKUPSET` to specify the name of the backup set that contains the data files that need to be restored.

OF PLUGGABLE DATABASE [ database_name | GUID guid_name ]

Specifies that RMAN must restore the data files of a new pluggable database (PDB) to an existing CDB. Specify either the name or the GUID that identifies the PDB.

Use FOREIGN DATAFILE or ALL FOREIGN DATAFILES along with OF PLUGGABLE DATABASE GUID guid_name to restore the data files for the specified PDB in its own sub directory named with the GUID. Use FROM BACKUPSET to specify the name of the backup set that contains the data files that need to be restored.

handleNameList::=

Syntax Element Description

Syntax Element	Description
`BACKUPSET` `filename`	Specifies the backup set that contains the cross-platform backup that must be restored. Most backup sets contain only one backup piece. However, you can create a backup consisting of multiple backup pieces by configuring `MAXPIECESIZE` to specify the maximum size of each backup piece. When a backup set contains multiple backup pieces, the `FROM BACKUPSET` clause must include a comma-separated list of all the backup pieces in the backup set. The order of the backup pieces must be must be from the first piece to the last piece. If this order is not followed, the restore operation fails. See Example 3-37 for a `RESTORE` command that contains multiple backup pieces. If a cross-platform backup consists of multiple backup sets, then you must use a separate `BACKUPSET` clause for each backup set that was created as part of the cross-platform backup. See Example 3-36 for a `RESTORE` command that contains multiple backup sets.
`TRANSPORTLIST`	Specifies that RMAN needs to use a transport list to identify the exact backups required for a restore operation on a destination database. You must have previously run the `RESTORE PREVIEW TO TRANSPORTLIST` command on the destination database to generate the transport list. Starting with Oracle Database 23ai, you can use regular RMAN backups to transport tablespaces and pluggable databases (PDB) from a source platform to a destination platform. On a destination database, RMAN restores the data files from the backups created on the source database, and then plugs in a tablespace or a PDB on the destination database to complete the data transport process. If the source database and the destination database are connected to the same recovery catalog, then RMAN queries the recovery catalog metadata to determine the exact backups required to perform the restore operation on a destination database. RMAN generates a transport list, which is an in memory list of backups. During the restore operation, RMAN uses the transport list to restores the data files from backups. On the destination database, connect RMAN to the same recovery catalog as the source database. Next, Use the `SET` command along with the `FOREIGN DBID` clause to set the `DBID` of the source PDB. Use the `RESTORE` command along with the `PREVIEW` clause and the `TO TRANSPORTLIST` clause to generate the transport list. You can then run the `RESTORE` command along with the `FOREIGN PLUGGABLE DATABASE` or `FOREIGN TABLESPACE` clause and the `FROM TRANSPORTLIST` clause to specify that RMAN must restore the data files using the transport file. See, Backup and Recovery User's Guide to learn about transporting PDBs and tablespaces using regular backups and recovery catalog connection.
`TRANSPORTFILE`	Specifies the `XML` file or transport file that contains the metadata about the backups of a PDB or a tablespace that is being transported to a destination database. You must have previously created the transport file on the source database. You must ensure to store the transport file in a location that is accessible to the destination database. Starting with Oracle Database 23ai, you can use regular RMAN backups to transport tablespaces and pluggable databases (PDB) from a source platform to a destination platform. On a destination database, RMAN restores the data files from the backups created on the source database, and then plugs in a tablespace or a PDB on the destination database to complete the data transport process. When a recovery catalog is not used, the transport file is used to store the backup metadata in XML format. RMAN requires the transport file to restore the data files from backups and plug in the restored tablespaces or PDBs into to a destination database. The transport file is specified using filename. On the source database, use the `RESTORE PREVIEW` command along with the `TO TRANSPORTFILE` clause to create a transport XML file. Then, run the `RESTORE` command along with the `FOREIGN PLUGGABLE DATABASE` or `FOREIGN TABLESPACE` clause and the `FROM TRANSPORTFILE` clause. In the `FROM TRANSPORTFILE` clause, specify the transport file created on the source host. See, the Backup and Recovery User's Guide to learn how to transport PDBs and tablespaces using regular backups.

BACKUPSET filename

Specifies the backup set that contains the cross-platform backup that must be restored.

Most backup sets contain only one backup piece. However, you can create a backup consisting of multiple backup pieces by configuring MAXPIECESIZE to specify the maximum size of each backup piece. When a backup set contains multiple backup pieces, the FROM BACKUPSET clause must include a comma-separated list of all the backup pieces in the backup set. The order of the backup pieces must be must be from the first piece to the last piece. If this order is not followed, the restore operation fails. See Example 3-37 for a RESTORE command that contains multiple backup pieces.

If a cross-platform backup consists of multiple backup sets, then you must use a separate BACKUPSET clause for each backup set that was created as part of the cross-platform backup. See Example 3-36 for a RESTORE command that contains multiple backup sets.

TRANSPORTLIST

Specifies that RMAN needs to use a transport list to identify the exact backups required for a restore operation on a destination database.

You must have previously run the RESTORE PREVIEW TO TRANSPORTLIST command on the destination database to generate the transport list.

Starting with Oracle Database 23ai, you can use regular RMAN backups to transport tablespaces and pluggable databases (PDB) from a source platform to a destination platform. On a destination database, RMAN restores the data files from the backups created on the source database, and then plugs in a tablespace or a PDB on the destination database to complete the data transport process.

If the source database and the destination database are connected to the same recovery catalog, then RMAN queries the recovery catalog metadata to determine the exact backups required to perform the restore operation on a destination database. RMAN generates a transport list, which is an in memory list of backups. During the restore operation, RMAN uses the transport list to restores the data files from backups.

On the destination database, connect RMAN to the same recovery catalog as the source database. Next, Use the SET command along with the FOREIGN DBID clause to set the DBID of the source PDB. Use the RESTORE command along with the PREVIEW clause and the TO TRANSPORTLIST clause to generate the transport list.

You can then run the RESTORE command along with the FOREIGN PLUGGABLE DATABASE or FOREIGN TABLESPACE clause and the FROM TRANSPORTLIST clause to specify that RMAN must restore the data files using the transport file.

See, Backup and Recovery User's Guide to learn about transporting PDBs and tablespaces using regular backups and recovery catalog connection.

TRANSPORTFILE

Specifies the XML file or transport file that contains the metadata about the backups of a PDB or a tablespace that is being transported to a destination database.

You must have previously created the transport file on the source database. You must ensure to store the transport file in a location that is accessible to the destination database.

Starting with Oracle Database 23ai, you can use regular RMAN backups to transport tablespaces and pluggable databases (PDB) from a source platform to a destination platform. On a destination database, RMAN restores the data files from the backups created on the source database, and then plugs in a tablespace or a PDB on the destination database to complete the data transport process.

When a recovery catalog is not used, the transport file is used to store the backup metadata in XML format. RMAN requires the transport file to restore the data files from backups and plug in the restored tablespaces or PDBs into to a destination database. The transport file is specified using filename.

On the source database, use the RESTORE PREVIEW command along with the TO TRANSPORTFILE clause to create a transport XML file.

Then, run the RESTORE command along with the FOREIGN PLUGGABLE DATABASE or FOREIGN TABLESPACE clause and the FROM TRANSPORTFILE clause. In the FROM TRANSPORTFILE clause, specify the transport file created on the source host.

See, the Backup and Recovery User's Guide to learn how to transport PDBs and tablespaces using regular backups.

Examples