DB2 10.5 for Linux, UNIX, and Windows

CATALOG DATABASE command

Stores database location information in the system database directory. The database can be located either on the local workstation or on a remote database partition server. The CATALOG DATABASE command can also be used to recatalog uncataloged databases, or maintain multiple aliases for one database, regardless of database location

Scope

In a partitioned database environment, when cataloging a local database into the system database directory, this command must be issued from a database partition on the server where the database is located.

Authorization

One of the following authorities:
  • SYSADM
  • SYSCTRL

Required connection

None. Directory operations affect the local directory only.

Command syntax

Read syntax diagramSkip visual syntax diagram
>>-CATALOG--+-DATABASE-+--database-name--+-----------+---------->
            '-DB-------'                 '-AS--alias-'   

>--+-------------------+---------------------------------------->
   +-ON--+-path--+-----+   
   |     '-drive-'     |   
   '-AT NODE--nodename-'   

>--+--------------------------------------------------------------+-->
   '-AUTHENTICATION--+-SERVER-----------------------------------+-'   
                     +-CLIENT-----------------------------------+     
                     +-SERVER_ENCRYPT---------------------------+     
                     +-SERVER_ENCRYPT_AES-----------------------+     
                     +-KERBEROS TARGET PRINCIPAL--principalname-+     
                     +-DATA_ENCRYPT-----------------------------+     
                     '-GSSPLUGIN--------------------------------'     

>--+------------------------+----------------------------------><
   '-WITH--"comment-string"-'   

Command parameters

DATABASE database-name
Specifies the name of the database to catalog.
AS alias
Specifies an alias as an alternate name for the database being cataloged. If an alias is not specified, the database manager uses database-name as the alias.
ON path | drive
Specifies the path on which the database being cataloged resides. On Windows operating systems, may instead specify the letter of the drive on which the database being cataloged resides (if it was created on a drive, not on a specific path).
AT NODE nodename
Specifies the name of the database partition server where the database being cataloged resides. This name should match the name of an entry in the node directory. If the node name specified does not exist in the node directory, a warning is returned, but the database is cataloged in the system database directory. The node name should be cataloged in the node directory if a connection to the cataloged database is required.
AUTHENTICATION
The authentication value is stored for remote databases (it appears in the output from the LIST DATABASE DIRECTORY command) but it is not stored for local databases.

Specifying an authentication type can result in a performance benefit.

SERVER
Specifies that authentication takes place on the database partition server containing the target database.
CLIENT
Specifies that authentication takes place on the database partition server where the application is invoked.
SERVER_ENCRYPT
Specifies that authentication takes place on the database partition server containing the target database, and that user IDs and passwords are encrypted at the source. User IDs and passwords are decrypted at the target, as specified by the authentication type cataloged at the source.
KERBEROS
Specifies that authentication takes place using Kerberos Security Mechanism.
TARGET PRINCIPAL principalname
Fully qualified Kerberos principal name for the target server; that is, the fully qualified Kerberos principal of the DB2® instance owner in the form of name/instance@REALM. For Windows Server 2003, this is the logon account of the DB2 server service in the form of userid@DOMAIN, userid@xxx.xxx.xxx.com or domain\userid.
DATA_ENCRYPT
Specifies that authentication takes place on the database partition server containing the target database, and that connections must use data encryption.
GSSPLUGIN
Specifies that authentication takes place using an external GSS API-based plug-in security mechanism.
SERVER_ENCRYPT_AES
Specifies that authentication takes place on the database partition server containing the target database, and that user IDs and passwords are encrypted with an Advanced Encryption Standard (AES) encryption algorithm at the source and decrypted at the target.
WITH "comment-string"
Describes the database or the database entry in the system database directory. The maximum length of a comment string is 30 characters. A carriage return or a line feed character is not permitted. The comment text must be enclosed by double quotation marks.

Examples

   db2 catalog database sample on /databases/sample
      with "Sample Database"

Usage notes

DB2 automatically catalogs databases when they are created. It catalogs an entry for the database in the local database directory and another entry in the system database directory. If the database is created from a remote client (or a client which is executing from a different instance on the same machine), an entry is also made in the system database directory at the client instance.

If you do not specify a path or a database partition server name, the database is assumed to be local. In this case, the location of the database is assumed to be the value of the dftdbpath database manager configuration parameter.

Databases on the same database partition server as the database manager instance are cataloged as indirect entries. Databases on other database partition servers are cataloged as remote entries.

CATALOG DATABASE automatically creates a system database directory if one does not exist. The system database directory is stored on the path that contains the database manager instance that is being used, and is maintained outside of the database.

List the contents of the system database directory using the LIST DATABASE DIRECTORY command. To list the contents of the local database directory use the LIST DATABASE DIRECTORY ON path, where path is where the database was created.

If directory caching is enabled, database, node and DCS directory files are cached in memory. To see if directory caching is enabled, check the value for the dir_cache directory cache support configuration parameter in the output from the GET DATABASE MANAGER CONFIGURATION command. An application's directory cache is created during its first directory lookup. Since the cache is only refreshed when the application modifies any of the directory files, directory changes made by other applications might not be effective until the application has restarted.

To refresh the CLP's directory cache, use the TERMINATE command. To refresh the database manager's shared cache, stop (db2stop) and then restart (db2start) the database manager. To refresh the directory cache for another application, stop and then restart that application.

In a pureScale environment, the db2cluster -cm -add -database_mounts database-name command must be run after the CATALOG DATABASE command.