Skip to main content

This is documentation for Caché & Ensemble. See the InterSystems IRIS version of this content.

For information on migrating to InterSystems IRIS, see Why Migrate to InterSystems IRIS?


Sets the current namespace and database.




Argument Description
dbname The namespace and corresponding database to be used by the current process as the current namespace.


The USE DATABASE command switches the current process to the specified namespace and its associated database. This allows you to change namespaces within SQL. The DATABASE keyword is optional.

The specified dbname is the name of the desired namespace and corresponding directory that contains the database files. Specify dbname as an identifier. Namespace names are not case-sensitive. For further information on using namespaces, see Namespaces and Databases in the Caché Programming Orientation Guide.

Because USER is an SQL Reserved Word, you must use a delimited identifier to specify the USER namespace, as shown in the following SQL Shell example:


If the specified dbname does not exist, Caché issues an SQLCODE -400 error.

The USE DATABASE command is a privileged operation. Prior to using USE DATABASE, it is necessary to be logged in as a user with appropriate privileges. Failing to do so results in an SQLCODE -99 error (Privilege Violation).

Use the $SYSTEM.Security.Login() method to assign a user with appropriate privileges:

   DO $SYSTEM.Security.Login("_SYSTEM","SYS")
   &sql(      )

You must have the %Service_Login:Use privilege to invoke the $SYSTEM.Security.Login method. For further information, refer to %SYSTEM.Security in the InterSystems Class Reference.

You can also switch to a different namespace using the ObjectScript ZNSPACE command, or the SET $NAMESPACE statement.

Executing via xDBC

When the USE DATABASE command is executed via xDBC, the server process performs a simulated connection reset. Data structures used by the server process are cleaned up. However, commit mode is not changed. The Read Committed setting is not changed either. If a transaction is in process, the transaction simply continues and is not committed or rolled back.

See Also