14
DBNEWID Utility

DBNEWID is a database utility that can change the internal database identifier (DBID) and the database name (DBNAME) for an operational database.

This chapter contains the following sections:

What Is the DBNEWID Utility?

Prior to 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

Ramifications of Changing the DBID and DBNAME

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. After you change the DBID, you must open the database with the RESETLOGS option, which re-creates the online redo logs and resets their sequence to 1 (see the Oracle9i Database Administrator's Guide). 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.

Changing the DBID and DBNAME of a Database

This section contains these topics:

Changing the DBID and Database Name

The following steps describe how to change the DBID of a database. Optionally, you can change the database name as well.

Ensure that you have a recoverable whole database backup.
Ensure that the target database is mounted but not open, and that it was shut down consistently prior to mounting. For example:
```
SHUTDOWN IMMEDIATE
STARTUP MOUNT
```
Invoke the DBNEWID utility on the command line, specifying a valid user with the SYSDBA privilege. For example:
```
% nid TARGET=SYS/oracle@test_db
```
To change the database name in addition to the DBID, specify the DBNAME parameter. This example changes the name to test_db2:
```
% nid TARGET=SYS/oracle@test DBNAME=test_db2
```
The DBNEWID utility performs validations in the headers of the datafiles and control files before attempting I/O to the files. If validation is successful, then DBNEWID prompts you to confirm the operation (unless you specify a log file, in which case it does not prompt), changes the DBID for each datafile (including offline normal and read-only datafiles), and then exits. The database is left mounted but is not yet usable. For example:
```
DBNEWID: Release 9.2.0.1.0

(c) Copyright 2002 Oracle Corporation.  All rights reserved.

Connected to database TEST_DB (DBID=3942195360)

Control Files in database:
    /oracle/dbs/cf1.f
    /oracle/dbs/cf2.f

Change database id of database SOLARIS? (Y/[N]) => y

Proceeding with operation
    Datafile /oracle/dbs/tbs_01.f - changed
    Datafile /oracle/dbs/tbs_02.f - changed
    Datafile /oracle/dbs/tbs_11.f - changed
    Datafile /oracle/dbs/tbs_12.f - changed
    Datafile /oracle/dbs/tbs_21.f - changed

New DBID for database TEST_DB is 3942196782.
All previous backups and archived redo logs for this database are unusable
Proceed to shutdown database and open with RESETLOGS option.
DBNEWID - Database changed.
```
If validation is not successful, then DBNEWID terminates and leaves the target database intact. You can open the database, fix the error, and then either resume the DBNEWID operation or continue using the database without changing its DBID.
After DBNEWID successfully changes the DBID, shut down the database:
```
SHUTDOWN IMMEDIATE
```
Mount the database. For example:
```
STARTUP MOUNT
```
Open the database in RESETLOGS mode and resume normal use. For example:
```
ALTER DATABASE OPEN RESETLOGS;
```
Make a new database backup. Because you reset the online redo logs, the old backups and archived logs are no longer usable in the current incarnation of the database.

Changing Only the Database Name

The following steps describe how to change the database name without changing the DBID.

Ensure that you have a recoverable whole database backup.
Ensure that the target database is mounted but not open, and that it was shut down consistently prior to mounting. For example:
```
SHUTDOWN IMMEDIATE
STARTUP MOUNT
```
Invoke the utility on the command line, specifying a valid user with the SYSDBA privilege. You must specify both the DBNAME and SETNAME parameters. This example changes the name to test_db2:
```
% nid TARGET=SYS/oracle@test_db DBNAME=test_db2 SETNAME=YES
```
DBNEWID performs validations in the headers of the control files (not the datafiles) before attempting I/O to the files. If validation is successful, then DBNEWID prompts for confirmation, changes the database name in the control files, and exits. After DBNEWID completes successfully, the database is left mounted but is not yet usable.
```
DBNEWID: Release 9.2.0.1.0

(c) Copyright 2002 Oracle Corporation.  All rights reserved.


Connected to database TEST_DB (DBID=3942196782)

Control Files in database:
    /oracle/dbs/cf1.f
    /oracle/dbs/cf2.f

Change database name of database TEST_DB to TEST_DB2? (Y/[N]) => Y

Proceeding with operation

Database name changed from TEST_DB to TEST_DB2 - database needs to be 
shutdown.
Modify parameter file and generate a new password file before restarting.

DBNEWID - Successfully changed database name
```
If validation is not successful, then DBNEWID terminates and leaves the target database intact. You can open the database, fix the error, and then either resume the DBNEWID operation or continue using the database without changing the database name.
Shut down the database. For example:
```
SHUTDOWN IMMEDIATE
```
Set the DB_NAME initialization parameter in the initialization parameter file to the new database name.
Create a new password file.
Start up the database and resume normal use. For example:
```
STARTUP
```

Troubleshooting a DBID Change Operation

If the DBNEWID utility succeeds in its validation stage but detects an error while changing the DBID, 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 the DBID change operation rather than revert it, reexecute your original command. The DBNEWID utility resumes and attempts to continue the change until all datafiles and control files have the new DBID. At this point, the database is left mounted. You should shut it down and then mount it again prior to 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.

To revert a stalled DBID change operation, run the DBNEWID utility again, specifying the REVERT keyword. For example:

% nid TARGET=SYS/oracle REVERT=YES LOGFILE=$HOME/nid.log

Troubleshooting a Database Name Change Operation

If you specify that only the database name should be changed (and not the DBID), then the validation process is the same as for a DBID change except that DBNEWID checks only the control files. It does not read the datafiles. If the validation encounters a problem, then the database is left mounted.

It is possible for validation to succeed, but for the actual database name change to fail. The possible failure scenarios depend on how many control files are in the database, as follows:

If you have one or more control files and DBNEWID fails on the first control file, then the database name is not changed in the control file. You can either try the operation again or open the database and resume normal database use.
If you have more than one control file and DBNEWID fails on the second control file or on any one thereafter, then some control files will have the old DBNAME and some will have the new DBNAME. In this case, you must either manually copy the first changed control file to all CONTROL_FILES locations, or revert by copying the unchanged control files to all CONTROL_FILES locations.

DBNEWID Syntax

The following diagrams show the syntax for the DBNEWID utility.

Text description of the illustration nid.gif

Text description of the illustration nid2.gif

Text description of the illustration nid3.gif

Parameters

Table 14-1 describes the parameters in the DBNEWID syntax.

Table 14-1 Parameters for the DBNEWID Utility

Parameter	Description
`TARGET`	Specifies the username and password used to connect to the database. The user must have the `SYSDBA` privilege. If you are using operating system authentication, then you can connect with the slash (`/`). If the `$ORACLE_HOME` and `$ORACLE_SID` variables are not set correctly in the environment, then you can specify a secure (IPC or BEQ) service to connect to the target database. A target database must be specified in all invocations of the DBNEWID utility.
`REVERT`	Specify `YES` to indicate that a failed change of DBID should be reverted (default is `NO`). The utility signals an error if no change DBID operation is in progress on the target database. A successfully completed change of DBID cannot be reverted. `REVERT=YES` is only valid when a DBID change failed.
`DBNAME=`new_db_name	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 `SETNAME` parameter.
`SETNAME`	Specify `YES` to indicate that DBNEWID should change the database name of the database but should not change the DBID (default is `NO`). When you specify `SETNAME=YES`, the utility only writes to the target database control files.
`LOGFILE=`logfile	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.
`APPEND`	Specify `YES` to append log output to the existing log file (default is `NO`).
`HELP`	Specify `YES` to print a list of the DBNEWID syntax options (default is `NO`).

Restrictions and Usage Notes

The DBNEWID utility has the following restrictions:

The utility is available only on the UNIX and Windows NT operating systems.
The nid executable file should be owned and run by the Oracle owner because it needs direct access to the datafiles and control files. If another user runs the utility, then set the user ID to the owner of the datafiles and control files.
The DBNEWID utility must access the datafiles 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.
To change the DBID of a database, the database must be mounted and must have been shut down consistently prior to 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. Note that you do not have to open with the RESETLOGS 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 aborts.
All online datafiles should be consistent without needing recovery.
Normal offline datafiles should be accessible and writable. If this is not the case, 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 prior to 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 (see the Oracle9i Database Administrator's Guide).
You can only specify REVERT when changing only the DBID.

Examples of Using DBNEWID

Changing Only the DBID

The following example connects with operating system authentication and changes only the DBID:

% nid TARGET=/

Changing the DBID and Database Name

The following example connects as user SYS and changes the DBID and also changes the database name to test2:

% nid TARGET=SYS/oracle@test1 DBNAME=test2

Changing Only the Database Name

The following example connects as user SYSTEM and changes only the database name, and also specifies a log file for the output:

% nid TARGET=SYSTEM/manager@test2 DBNAME=test3 SETNAME=YES LOGFILE=dbid.out

14 DBNEWID Utility

What Is the DBNEWID Utility?

Ramifications of Changing the DBID and DBNAME

Changing the DBID and DBNAME of a Database

Changing the DBID and Database Name

Changing Only the Database Name

Troubleshooting a DBID Change Operation

Troubleshooting a Database Name Change Operation

DBNEWID Syntax

Parameters

Table 14-1 Parameters for the DBNEWID Utility

Restrictions and Usage Notes

Examples of Using DBNEWID

Changing Only the DBID

Changing the DBID and Database Name

Changing Only the Database Name

14
DBNEWID Utility