21 DBNEWID Utility
DBNEWID is a database utility that can change the internal database identifier (DBID) and the database name (DBNAME) for an operational database.
See the following topics:
- What Is the DBNEWID Utility?
Describes what is new in the DBNEWID utility. - Ramifications of Changing the DBID and DBNAME
Describes the ramifications of changing the DBID and DBNAME of a database. - DBNEWID Considerations for CDBs and PDBs
The DBNEWID parameterPDB
allows you to change the DBID on pluggable databases (PDBs). - Changing the DBID and DBNAME of a Database
This section contains these topics: - DBNEWID Syntax
Describes DBNEWID syntax.
Parent topic: Other Utilities
21.1 What Is the DBNEWID Utility?
Describes what is new in the DBNEWID utility.
Before the introduction of the DBNEWID utility, you could manually create a copy of a database and give it a new database name (DBNAME) by re-creating the control file. However, you could not give the database a new identifier (DBID). The DBID is an internal, unique identifier for a database. Because Recovery Manager (RMAN) distinguishes databases by DBID, you could not register a seed database and a manually copied database together in the same RMAN repository. The DBNEWID utility solves this problem by allowing you to change any of the following:
-
Only the DBID of a database
-
Only the DBNAME of a database
-
Both the DBNAME and DBID of a database
Parent topic: DBNEWID Utility
21.2 Ramifications of Changing the DBID and DBNAME
Describes the ramifications of changing the DBID and DBNAME of a database.
Changing the DBID of a database is a serious procedure. When the DBID of a database is changed, all previous backups and archived logs of the database become unusable. This is similar to creating a database except that the data is already in the data files. After you change the DBID, backups and archive logs that were created before the change can no longer be used because they still have the original DBID, which does not match the current DBID. You must open the database with the RESETLOGS
option, which re-creates the online redo logs and resets their sequence to 1. Consequently, you should make a backup of the whole database immediately after changing the DBID.
Changing the DBNAME without changing the DBID does not require you to open with the RESETLOGS
option, so database backups and archived logs are not invalidated. However, changing the DBNAME does have consequences. You must change the DB_NAME
initialization parameter after a database name change to reflect the new name. Also, you may have to re-create the Oracle password file. If you restore an old backup of the control file (before the name change), then you should use the initialization parameter file and password file from before the database name change.
Note:
Do not change the DBID or DBNAME of a database if you are using a capture process to capture changes to the database. See Oracle Streams Concepts and Administration for more information about capture processes.
- Considerations for Global Database Names
If you are dealing with a database in a distributed database system, then each database should have a unique global database name.
Parent topic: DBNEWID Utility
21.2.1 Considerations for Global Database Names
If you are dealing with a database in a distributed database system, then each database should have a unique global database name.
The DBNEWID utility does not change global database names. This can only be done with the SQL ALTER
DATABASE
statement, for which the syntax is as follows:
ALTER DATABASE RENAME GLOBAL_NAME TO newname.domain;
The global database name is made up of a database name and a domain, which are determined by the DB_NAME
and DB_DOMAIN
initialization parameters when the database is first created.
The following example changes the database name to sales
in the domain us
.example
.com
:
ALTER DATABASE RENAME GLOBAL_NAME TO sales.us.example.com
You would do this after you finished using DBNEWID to change the database name.
See Also:
Oracle Database Administrator's Guide for more information about global database names
Parent topic: Ramifications of Changing the DBID and DBNAME
21.3 DBNEWID Considerations for CDBs and PDBs
The DBNEWID parameter PDB
allows you to change the DBID on pluggable databases (PDBs).
By default, when you run the DBNEWID utility on a container database (CDB) it changes the DBID of only the CDB; the DBIDs of the pluggable databases (PDBs) comprising the CDB remain the same. This could cause problems with duplicate DBIDs for PDBs in some cases, such as when a CDB is cloned.
As of Oracle Database 12c Release 2 (12.2), you can change the DBID on the PDBs by using the new DBNEWID PDB
parameter. You cannot specify a particular PDB; either all of them or none of them will have new DBIDs. The PDB
parameter is applicable only in a CDB environment. It has the following format:
PDB=[ALL | NONE]
-
If you specify
ALL
, then in addition to the DBID for the CDB changing, the DBIDs for all PDBs comprising the CDB are also changed. -
Specifying
NONE
(the default) leaves the PDB DBIDs the same, even if the CDB DBID is changed.
Oracle recommends that you use PDB=ALL
, but PDB=NONE
is the default for backward compatibility reasons.
Parent topic: DBNEWID Utility
21.4 Changing the DBID and DBNAME of a Database
This section contains these topics:
- Changing the DBID and Database Name
Describes how to change the DBID of a database. - Changing Only the Database ID
Describes changing the database ID without changing the database name. - Changing Only the Database Name
Describe how to change the database name without changing the DBID. - Troubleshooting DBNEWID
Describes troubleshooting hints for the DBNEWID utility.
Parent topic: DBNEWID Utility
21.4.1 Changing the DBID and Database Name
Describes how to change the DBID of a database.
The following steps describe how to change the DBID of a database. Optionally, you can change the database name as well.
Parent topic: Changing the DBID and DBNAME of a Database
21.4.2 Changing Only the Database ID
Describes changing the database ID without changing the database name.
Follow the steps in Changing the DBID and Database Name, but in Step 3 do not specify the optional database name (DBNAME). The following is an example of the type of output that is generated when only the database ID is changed.
. . . Connected to database PROD (DBID=86997811) . . . Control Files in database: /oracle/TEST_DB/data/cf1.dbf /oracle/TEST_DB/data/cf2.dbf The following datafiles are offline clean: /oracle/TEST_DB/data/tbs_61.dbf (23) /oracle/TEST_DB/data/tbs_62.dbf (24) /oracle/TEST_DB/data/temp3.dbf (3) These files must be writable by this utility. The following datafiles are read-only: /oracle/TEST_DB/data/tbs_51.dbf (15) /oracle/TEST_DB/data/tbs_52.dbf (16) /oracle/TEST_DB/data/tbs_53.dbf (22) These files must be writable by this utility. Changing database ID from 86997811 to 4004383693 Control File /oracle/TEST_DB/data/cf1.dbf - modified Control File /oracle/TEST_DB/data/cf2.dbf - modified Datafile /oracle/TEST_DB/data/tbs_01.dbf - dbid changed Datafile /oracle/TEST_DB/data/tbs_ax1.dbf - dbid changed Datafile /oracle/TEST_DB/data/tbs_02.dbf - dbid changed Datafile /oracle/TEST_DB/data/tbs_11.dbf - dbid changed Datafile /oracle/TEST_DB/data/tbs_12.dbf - dbid changed Datafile /oracle/TEST_DB/data/temp1.dbf - dbid changed Control File /oracle/TEST_DB/data/cf1.dbf - dbid changed Control File /oracle/TEST_DB/data/cf2.dbf - dbid changed Instance shut down Database ID for database TEST_DB changed to 4004383693. All previous backups and archived redo logs for this database are unusable. Database has been shutdown, open database with RESETLOGS option. Succesfully changed database ID. DBNEWID - Completed succesfully.
Parent topic: Changing the DBID and DBNAME of a Database
21.4.3 Changing Only the Database Name
Describe how to change the database name without changing the DBID.
Execute the following steps:
Parent topic: Changing the DBID and DBNAME of a Database
21.4.4 Troubleshooting DBNEWID
Describes troubleshooting hints for the DBNEWID utility.
If the DBNEWID utility succeeds in its validation stage but detects an error while performing the requested change, then the utility stops and leaves the database in the middle of the change. In this case, you cannot open the database until the DBNEWID operation is either completed or reverted. DBNEWID displays messages indicating the status of the operation.
Before continuing or reverting, fix the underlying cause of the error. Sometimes the only solution is to restore the whole database from a recent backup and perform recovery to the point in time before DBNEWID was started. This underscores the importance of having a recent backup available before running DBNEWID.
If you choose to continue with the change, then re-execute your original command. The DBNEWID utility resumes and attempts to continue the change until all data files and control files have the new value or values. At this point, the database is shut down. You should mount it before opening it with the RESETLOGS
option.
If you choose to revert a DBNEWID operation, and if the reversion succeeds, then DBNEWID reverts all performed changes and leaves the database in a mounted state.
If DBNEWID is run against a release 10.1 or later Oracle database, then a summary of the operation is written to the alert file. For example, for a change of database name and database ID, you might see something similar to the following:
*** DBNEWID utility started *** DBID will be changed from 86997811 to new DBID of 1250452230 for database PROD DBNAME will be changed from PROD to new DBNAME of TEST_DB Starting datafile conversion Setting recovery target incarnation to 1 Datafile conversion complete Database name changed to TEST_DB. Modify parameter file and generate a new password file before restarting. Database ID for database TEST_DB changed to 1250452230. All previous backups and archived redo logs for this database are unusable. Database has been shutdown, open with RESETLOGS option. Successfully changed database name and ID. *** DBNEWID utility finished successfully ***
For a change of just the database name, the alert file might show something similar to the following:
*** DBNEWID utility started *** DBNAME will be changed from PROD to new DBNAME of TEST_DB Starting datafile conversion Datafile conversion complete Database name changed to TEST_DB. Modify parameter file and generate a new password file before restarting. Successfully changed database name. *** DBNEWID utility finished successfully *** In case of failure during DBNEWID the alert will also log the failure: *** DBNEWID utility started *** DBID will be changed from 86997811 to new DBID of 86966847 for database AV3 Change of database ID failed. Must finish change or REVERT changes before attempting any database operation. *** DBNEWID utility finished with errors ***
Parent topic: Changing the DBID and DBNAME of a Database
21.5 DBNEWID Syntax
Describes DBNEWID syntax.
The following diagrams show the syntax for the DBNEWID utility.
- DBNEWID Parameters
Describes the parameters for DBNEWID. - Restrictions and Usage Notes
Describes restrictions for the DBNEWID utility. - Additional Restrictions for Releases Earlier Than Oracle Database 10g
Describes additional restrictions if the DBNEWID utility is run against an Oracle Database release earlier than 10.1.
Parent topic: DBNEWID Utility
21.5.1 DBNEWID Parameters
Describes the parameters for DBNEWID.
The following table describes the parameters in the DBNEWID syntax.
Table 21-1 Parameters for the DBNEWID Utility
Parameter | Description |
---|---|
|
Specifies the username and password used to connect to the database. The user must have the |
|
Specify |
|
Changes the database name of the database. You can change the DBID and the DBNAME of a database at the same time. To change only the DBNAME, also specify the |
|
Specify |
PDB |
Changes the DBID on either all or none of the pluggable databases (PDBs) in a multitenant container database (CDB). (By default, when you run the DBNEWID utility on a container database (CDB) it changes the DBID of only the CDB; the DBIDs of the pluggable databases (PDBs) comprising the CDB remain the same.) The PDB parameter is applicable only in a CDB environment.
|
|
Specifies that DBNEWID should write its messages to the specified file. By default the utility overwrites the previous log. If you specify a log file, then DBNEWID does not prompt for confirmation. |
|
Specify |
|
Specify |
Parent topic: DBNEWID Syntax
21.5.2 Restrictions and Usage Notes
Describes restrictions for the DBNEWID utility.
For example:
-
To change the DBID of a database, the database must be mounted and must have been shut down consistently before mounting. In the case of an Oracle Real Application Clusters database, the database must be mounted in
NOPARALLEL
mode. -
You must open the database with the
RESETLOGS
option after changing the DBID. However, you do not have to open with theRESETLOGS
option after changing only the database name. -
No other process should be running against the database when DBNEWID is executing. If another session shuts down and starts the database, then DBNEWID terminates unsuccessfully.
-
All online data files should be consistent without needing recovery.
-
Normal offline data files should be accessible and writable. If this is not the case, then you must drop these files before invoking the DBNEWID utility.
-
All read-only tablespaces must be accessible and made writable at the operating system level before invoking DBNEWID. If these tablespaces cannot be made writable (for example, they are on a CD-ROM), then you must unplug the tablespaces using the transportable tablespace feature and then plug them back in the database before invoking the DBNEWID utility.
-
The DBNEWID utility does not change global database names. See Considerations for Global Database Names.
Parent topic: DBNEWID Syntax
21.5.3 Additional Restrictions for Releases Earlier Than Oracle Database 10g
Describes additional restrictions if the DBNEWID utility is run against an Oracle Database release earlier than 10.1.
For example:
-
The
nid
executable file should be owned and run by the Oracle owner because it needs direct access to the data files and control files. If another user runs the utility, then set the user ID to the owner of the data files and control files. -
The DBNEWID utility must access the data files of the database directly through a local connection. Although DBNEWID can accept a net service name, it cannot change the DBID of a nonlocal database.
Parent topic: DBNEWID Syntax