Using the dbaascli Utility on Exadata Cloud@Customer

Learn to use the dbaascli utility on Exadata Cloud@Customer.

About Using the dbaascli Utility on Exadata Cloud@Customer

You can use the dbaascli utility to perform various database lifecycle and administration operations on Exadata Cloud@Customer such as changing the password of a database user, starting a database, managing pluggable databases (PDBs), scaling the CPU core count in disconnected mode, and more.

You must use DBaaS console or command-line interface to scale resources. The capabilities of the dbaascli utility are in addition to, and separate from, the Oracle Cloud Infrastructure Console, API, or command-line interface (CLI).

To use the utility, you must be connected to an Exadata Cloud@Customer compute node. See "Connecting to a Compute Node with SSH".

Many dbaascli commands can be run as the oracle user. However, some commands require root administrator privileges.

To scale OCPUs up or down in a VM cluster in disconnected mode, run the dbaascli cpuscale update and dbaascli cpuscale get_status commands from any node inside a VM cluster to change the CPU core count for that cluster. If you have more than one VM cluster, then run a separate command from any node inside each VM cluster you want to scale up or down. These commands are designed to not work if issued during the normal connected mode and will time out 600 seconds (10 minutes).

dbaascli database bounce

To shut down and restart a specified Exadata Cloud@Customer database, use the command dbaascli database bounce.

Prerequisites

Run the command as the oracle user.

To use the utility, you must be connected to an Exadata Cloud@Customer compute node.

See "Connecting to a Compute Node with SSH".

Syntax

dbaascli database bounce --dbname dbname

In the command, dbname specifies the name of the database that you want to act on.

Options

The dbname option of database bounce specifies the name of the database that you want to shut down and restart. The dbname option is prefixed with two minus signs (--).

Usage Notes

The command performs a database shutdown in immediate mode. The database is then restarted and opened. In Oracle Database 12c or later, all of the PDBs are also opened.

Example 16-1 Shut Down and Restart the Database

In the following command, you shut down and restart the database sales1

$ dbaascli database bounce --dbname sales1

dbaascli database changepassword

To change the password of a database user, use the command dbaascli database changepassword.

Prerequisites

Run the command as the root user.

Syntax

dbaascli database changepassword --dbname dbname

In the command, dbname specifies the name of the database that you want to act on.

Options

The dbname option of database changepassword specifies the name of the database that you want to shut down and restart. The dbname option is prefixed with two minus signs (--).

Usage Notes

Enter the database user name and new password when prompted.

dbaascli cpuscale get_status

To check the status of current or last scale request performed, use the command dbaascli cpuscale get_status.

Prerequisites

Run the command as the root user.

See "Connecting to a Compute Node with SSH".

Syntax

Displays various command execution states as it progresses from scheduled, running, and finally to success or failure.

$ dbaascli cpuscale get_status

dbaascli cpuscale update

To scale up or down the CPU core count for a virtual machine in a VM cluster in disconnected mode, use the command dbaascli cpuscale update.

Prerequisites

Run the command as the root user.

See "Connecting to a Compute Node with SSH".

Syntax

Exadata Cloud@Customer is considered to be in a "Disconnected" mode when there is a loss of connectivity with the DBaaS control plane running on Oracle Cloud Infrastructure (OCI).

$  dbaascli cpuscale update --coreCount coreCount --message message

In the command, coreCount specifies the number of CPUs that you want to scale up or down per VM in a cluster. Optionally, you can include a message for your reference.

dbaascli database move

To move a database to another Oracle Home directory location, use the command dbaascli database move.

Prerequisites

  • Before performing a move operation, ensure that all of the database instances associated with the database are up and running.

  • Run the command as the root user.

Syntax

# dbaascli database move --dbname dbname --ohome oraclehome

In the command:

  • dbname specifies the name of the database that you want to move.
  • oraclehome specifies the path to an existing Oracle Home directory location, which you want the specified database to use.

dbaascli database start

To start the specified database use the command dbaascli database start.

Prerequisites

Run the command as the Oracle user.

Syntax

 dbaascli database start --dbname dbname

In the command, dbname specifies the name of the database that you want to start.

Usage Notes

The command starts and opens the database. In Oracle Database 12c or later, all of the PDBs are also opened.

dbaascli database status

To check the status of the specified database, use the command dbaascli database status.

Prerequisites

Run the command as the Oracle user.

Syntax

dbaascli database status --dbname dbname

In the command, dbname specifies the name of the database for which you want to check the status.

Usage Notes

Output from the command includes the open mode of the database, the software release and edition of the database, and release version of other software components.

dbaascli database stop

To stop the specified database, use the command dbaascli database stop.

Prerequisites

Run the command as the Oracle user.

Syntax

 dbaascli database stop --dbname dbname

In the command, dbname specifies the name of the database that you want to stop.

Usage Notes

The command performs a database shutdown in immediate mode. No new connections or new transactions are permitted. Active transactions are rolled back, and all connected users are disconnected.

dbaascli database update

To modify the globally unique database name or to reconfigure online redo log files, use dbaascli database update.

Prerequisites

For all options, run the command as the root user.

Modifying the Globally Unique Database Name

Run the following command to modify a globally unique database name:

dbaascli database update --dbname dbname --db_unique_name dbname_uniquename [--precheck]

In the command, dbname specifies the name of the database that you want to update and dbname_uniquename specifies the user configurable portion of the new globally unique database name.

The command modifies the DB_UNIQUE_NAME database parameter and related configuration entries that reference it, including entries in the Oracle Cluster Registry (OCR) and database server parameter file (SPFILE). File locations that reference the globally unique database name are also updated, including the location of the data files and keystore.

The value for the --db_unique_name option must begin with the dbname value, followed by an underscore character. If you do not use this convention, then the command fails with an error .

To ensure that the update can proceed before you perform the update operation, you can use the option --precheck to run a series of prerequisite checks. No changes are made when using the --precheck option.

Reconfiguring Online Redo Logs

dbaascli database update --dbname dbname --redosize redosize [--groups numgroups] [--precheck]

Run the following command to reconfigure online redo logs:

In the command, the variable dbname specifies the name of the database that you want to move and the variable redosize specifies the size of each online redo log file in megabytes. The valid range is for redosize is between 1000m and 16000m, and the value that you enter for the variable numgroups optionally specifies the number of online redo log groups to create. The default value for the variable numgroups is 4.

Before performing the update operation, you can use the --precheck option to run a series of prerequisite checks to ensure that the update can proceed. No changes are made when you use the --precheck option.

dbaascli dbhome info

Use the dbaascli dbhome info command to view information about Oracle Home directory locations.

Prerequisites

Run the command as root user.

Syntax

dbaascli dbhome info

When prompted:

  • Press Enter to view information about all of the Oracle homes that are registered in the VM cluster.
  • To view information about a particular Oracle home, specify an Oracle home name.

dbaascli dbhome purge

Use the command dbaascli dbhome purge to delete unused Oracle home directory locations.

Prerequisite

Run the command as the root user.

Syntax

 dbaascli dbhome purge

Options

When prompted, enter:

  • 1 to specify the Oracle home name for the location being purged.
  • 2 to specify the Oracle home directory path for the location being purged.

When next prompted, enter the Oracle home name or directory path for the location being purged. If your entries are valid, and the Oracle home is not associated with a database, then the Oracle binaries are removed from the Oracle home directory location. The associated metadata is also removed from the system.

dbaascli dbimage list

To display information about Oracle Database software images that are downloaded to your Exadata Cloud@Customer environment, use the command dbaascli dbimage list.

Prerequisites

Run the command as the root user.

Syntax

# dbaascli dbimage list

Usage Notes

The command displays a list of software images that are downloaded to your Exadata Cloud@Customer environment, including version and bundle patch information.

dbaascli listener bounce

To stop and restart the Oracle Net listener that is associated with the specified database, run the command dbaascli listener bounce.

Prerequisites

Run the dbaascli listener bounce command as the oracle user.

Syntax

dbaascli listener bounce --dbname dbname

In the preceeding command dbname specifies the name of the database that you want to stop and restart.

dbaascli listener start

To start an Oracle Net listener that is associated with the specified database, run the command dbaascli listener start.

Prerequisites

Run the dbaascli listener start command as the oracle user:

Syntax

dbaascli listener start --dbname dbname

In the preceeding command dbname specifies the name of the database that you want to move.

dbaascli listener status

To obtain the status of the Oracle Net listener that is associated with the specified database, use the command dbaascli listener status.

Prerequisites

Run the command as the oracle user.

Syntax

dbaascli listener stop --dbname dbname

In the command, dbname specifies the name of the database whose listener you want to stop.

dbaascli listener stop

To stop the Oracle Net listener that is associated with the specified database, use the command dbaascli listener stop.

Prerequisites

Run the command as the oracle user.

Syntax

dbaascli listener stop --dbname dbname

In the command, dbname specifies the name of the database whose listener you want to stop.

dbaascli patch db apply

To apply an Oracle Database or Oracle Grid Infrastructure patch, use the command dbaascli patch db apply.

Prerequisites

Run the command as the root user.

Syntax

You can use this command to apply an Oracle Database or Oracle Grid Infrastructure patch.

To apply a patch to a specific instance, use the following command:

# dbaascli patch db apply --patchid patchid --instance1 hostname:oracle_home [--dbnames dbname[,dbname2 ...]] [--run_datasql 1]

To apply a patch by specifying only database names, use the following command:

# dbaascli patch db apply --patchid patchid --dbnames dbname[,dbname2 ...] [--run_datasql 1] [-alldbs]

In the preceding commands:

  • patchid identifies the patch that you want to apply.
  • --instance1 specifies a compute node and Oracle home directory that is subject to the patching operation. In this context, an Oracle home directory can be either an Oracle Database home directory, or the Oracle Grid Infrastructure home directory.

    If you use this argument to specify a shared Oracle home directory and you do not specify the --dbnames argument, then all of the databases that share the specified Oracle Home are patched. After the operation, the Oracle home directory location remains unchanged; however, the patch level information embedded in the Oracle home name is adjusted to reflect the patching operation.

  • --dbnames specifies the database names for the databases that are the target of the patching operation.

    If you use this argument to patch a database that uses a shared Oracle home, and you do not specify the -alldbs option, then a new Oracle home containing the patched Oracle Database binaries is created, and the database is moved to the new Oracle home.

  • -alldbs patches all of the databases that share the same Oracle Database binaries (Oracle home) as the databases specified in the --dbnames argument.

    After the operation, the Oracle home directory location remains unchanged; however, the patch level information embedded in the Oracle home name is adjusted to reflect the patching operation.

  • --run_datasql 1 instructs the command to execute patch-related SQL commands.

Usage Notes

  • Patch-related SQL should only be run after all of the compute nodes are patched. Take care not to specify this argument if you are patching a node and further nodes remain to be patched.

  • This argument can only be specified along with a patching operation on a compute node. If you have patched all of your nodes and you did not specify this argument, you need to manually execute the SQL commands associated with the patch, which typically involves running the catbundle.sql script for Oracle Database 11g or the datapatch utility for Oracle Database 12c, or later. Refer to the patch documentation for full details.

dbaascli patch db list

To check whether Oracle Database or Oracle Grid Infrastructure patches are available, run the command dbaascli patch db list.

Prerequisites

Run the command as the root user.

Syntax

dbaascli patch db list --oh hostname:oracle_home

In the preceding command, --oh hostname: specifies a compute node, and oracle_home specifies the Oracle home directory for which you want to list the available patches. In this context, an Oracle home directory may be an Oracle Database home directory or the Oracle Grid Infrastructure home directory

Usage Notes

The list of available patches is determined by interrogating the database to establish the patches that have already been applied. When a patch is applied, the corresponding database entry is made as part of the SQL patching operation, which is run at the end of the patch workflow. Therefore, the list of available patches may include partially applied patches along with patches that are currently being applied.

dbaascli patch db prereq

To check the prerequisites for an Oracle Database or Oracle Grid Infrastructure patch, use the command dbaascli patch db prereq.

Prerequisites

You must run the command as the root user.

Syntax

To check patch prerequisites on a specific instance, use the following command:

# dbaascli patch db prereq --patchid patchid --instance1 hostname:oracle_home [--dbnames dbname[,dbname2 ...]]

To check patch prerequisites by specifying only database names, use the following command:

# dbaascli patch db prereq --patchid patchid --dbnames dbname[,dbname2 ...] [-alldbs]

In the preceding commands:

  • patchid identifies the patch identifier for which you want prerequisites to be checked before installing the patch.
  • --instance1 specifies a compute node and Oracle home directory on which you want the prerequisite checks to be performed. In this context, an Oracle home directory can be an Oracle Database home directory, or it can be the Oracle Grid Infrastructure home directory.
  • --dbnames specifies the database names for the databases on which you want prerequisite checks to be performed.
  • -alldbs specifies that you want to check all of the databases that share the same Oracle home (the same Oracle Database binaries) as the specified databases.

dbaascli patch db switchback

To roll back an Oracle Database or Oracle Grid Infrastructure patch, use the command dbaascli patch db switchback.

Prerequisites

You must run the command as the root user.

Syntax

To roll back a patch on specific instances, use the following command syntax:

# dbaascli patch db switchback --patchid patchid --instance1 hostname:oracle_home [--dbnames dbname[,dbname2 ...]] [--run_datasql 1]

To roll back a patch by specifying only database names, use the following command:

# dbaascli patch db switchback --patchid patchid --dbnames dbname[,dbname2 ...] [--run_datasql 1] [-alldbs]

In the preceding commands:

  • patchid identifies the patch to be rolled back.
  • --instance1 specifies a compute node and Oracle Home directory that is subject to the rollback operation. In this context, an Oracle home directory can be an Oracle Database home directory or the Oracle Grid Infrastructure home directory.

    If you use this argument to specify a shared Oracle home directory, and you do not specify the --dbnames argument, then all of the databases that share the specified Oracle home are rolled back.

  • --dbnames specifies the database names for the databases that are the target of the rollback operation.
  • -alldbs specifies that you want to roll back all of the databases that share the same Oracle Database binaries (Oracle home) as the databases specified in the --dbnames argument.
  • --run_datasql 1 instructs the command to run rollback-related SQL commands.

Usage Notes

  • You can only run rollback-related SQL after all of the compute nodes are rolled back. Take care not to specify this argument if you are rolling back a node, and further nodes remain to be rolled back.
  • You can only specify this argument with a rollback operation on a compute node. Therefore, if you have rolled back all of your nodes, and you did not specify this argument, then you must manually run the SQL commands associated with the rollback operation. Refer to the patch documentation for full details.

dbaascli patch tools apply

To download and apply a cloud tooling update, run the command dbaascli patch tools apply.

Prerequisite

Run the command as the root user.

Syntax

  • To update to the latest available cloud tooling, use the command:

    dbaascli patch tools apply --patchid LATEST
  • To update to a specific cloud tooling release, use the following command:

    dbaascli patch tools apply --patchid patchid

In the preceding command, patchid is a cloud tooling patch identifier, as reported in the output of the dbaascli patch db list command.

Usage Notes

The cloud tooling update is applied to all nodes in the VM cluster.

dbaascli patch tools list

To display information about your installed cloud tools and to list the available updates, use the command dbaascli patch tools list.

Prerequisites

Run the command as the root user.

Syntax

# dbaascli patch tools list

Usage Notes

The command output displays:.

  • The version of the cloud tooling that is installed on the compute node.
  • The list of available updates.
  • Notification of the cloud tooling version that is installed on the other compute nodes in the VM cluster.

dbaascli pdb checkdb

To display information about a container database (CDB), run the command dbaascli pdb checkdb --dbname.

Prerequisites

Run the command as the oracle user.

Syntax

# dbaascli pdb checkdb --dbname dbname

Options

In the command, dbname specifies the name of the CDB for which you want to display information.

Usage Notes

The information returned by this command includes the number of instances, and the CPU count that is associated with the CDB.

dbaascli pdb checknode

To display information about pluggable databases (PDBs) that are associated with a specific container database (CDB) and a specific compute node run the command dbaascli pdb checknode.

Prerequisites

Run the command as the oracle user.

Syntax

$ dbaascli pdb checknode --node nodenum --dbname dbname

Options

In the command:

  • nodenum specifies the node number for a compute node in the Exadata Cloud@Customer environment. You can display a list of compute nodes and corresponding node numbers by using the olsnodes command.
  • dbname specifies the name of the container database that hosts the PDB.

Usage Notes

The command displays statuses for all PDBs that are associated with the specified compute node and CDB, including the open mode for each PDB.

dbaascli pdb checkpdb

To display information about a pluggable database (PDB) run the command dbaascli pdb checkpdb.

Prerequisites

Run the command as the oracle user.

Syntax

$ dbaascli pdb checkpdb --pdbname pdbname --dbname dbname

Options

In the command:

  • pdbname specifies the name of the PDB that you want to check.
  • dbname specifies the name of the container database that hosts the PDB.

Usage Notes

The command displays the status for the specified PDB, including the open mode and restricted status.

dbaascli pdb close

To close a pluggable database (PDB) run the command dbaascli pdb close.

Prerequisite

Run the command as the oracle user.

Syntax

dbaascli pdb close --pdbname pdbname --dbname dbname

Options

In the command:

  • pdbname specifies the name of the PDB that you want to close.
  • dbname specifies the name of the container database that hosts the PDB.

Usage Notes

Upon successful completion of running this command, the PDB is closed on all of the container database instances.

dbaascli pdb connect_info

To retrieve network connection information for a pluggable database (PDB) run the command dbaascli pdb connect_info.

Prerequisite

Run the command as the oracle user.

Syntax

dbaascli pdb connect_info --pdbname pdbname --dbname dbname

Options

In the command:

  • pdbname specifies the name of the PDB for which you want to retrieve connection information
  • dbname specifies the name of the container database that hosts the PDB

Usage Notes

The command outputs a zip file that contains tnsnames.ora, sqlnet.ora, and ojdbcs properties for the PDB.

dbaascli pdb connect_string

To display Oracle Net connect string information for a pluggable database (PDB) run the command dbaascli pdb connect_string.

Prerequisite

Run the command as the oracle user.

Syntax

dbaascli pdb connect_string --pdbname pdbname --dbname dbname

Options

In the command:
  • pdbname specifies the name of the PDB for which you want to display connect string information
  • dbname specifies the name of the container database that hosts the PDB

dbaascli pdb create

To create a new pluggable database (PDB) run the command dbaascli pdb create.

Prerequisite

Run the command as the oracle user.

Syntax

dbaascli pdb create --pdbname pdbname --dbname dbname [--maxsize maxsize] [--maxcpu maxcpu]

Options

In the command:

  • pdbname specifies the name of the new PDB that you want to create.
  • dbname specifies the name of the container database that hosts the new PDB.
  • maxsize optionally specifies the maximum total size of data files and temporary files for tablespaces belonging to the PDB. Setting this option is effectively the same as setting the MAXSIZE PDB storage clause in the CREATE PLUGGABLE DATABASE SQL command. You can impose a limit by specifying an integer followed by a size unit (K, M, G, or T), or you can specify UNLIMITED to explicitly enforce no limit.
  • maxcpu optionally specifies the maximum number of CPUs that are available to the PDB. Setting this option is effectively the same as setting the CPU_COUNT parameter in the PDB.

Usage Notes

During the PDB creation process, you are prompted to specify the administration password for the new PDB.

dbaascli pdb delete

To delete a pluggable database (PDB) run the command dbaascli pdb delete.

Prerequisite

Run the command as the oracle user.

Syntax

dbaascli pdb delete --pdbname pdbname --dbname dbname

Options

In the command:
  • pdbname specifies the name of the PDB that you want to delete
  • dbname specifies the name of the container database that hosts the PDB

dbaascli pdb info

To display more detailed information about a pluggable database (PDB) use the command dbaascli pdb info.

Prerequisite

(Run the command as the oracle user.

Syntax

dbaascli pdb info [--pdbname pdbname] --dbname dbname [--detailed]

Options

In the command:
  • pdbname optionally specifies the name of the PDB for which you want to display information. If this you do not specify this option, then the command displays information about all of the PDBs in the specified container database.
  • dbname specifies the name of the container database that hosts the PDB.

Usage Notes

The command displays information such as the CPU count and storage usage that is associated with a PDB. You can add the optional --detailed argument to display extra information, including the list of compute nodes where a PDB is open in read/write mode.

dbaascli pdb local_clone

To create a new pluggable database (PDB) as a clone of an existing PDB in the same container database (CDB) run the command dbaascli pdb local_clone.

Prerequisite

Run the command as the oracle user.

Syntax

dbaascli pdb local_clone --pdbname sourcepdbname --target_pdbname targetpdbname --dbname dbname

Options

In the command:
  • sourcepdbname specifies the name of the PDB that you want to clone
  • targetpdbname specifies the name of the new PDB that you want to create
  • dbname specifies the name of the container database that hosts the PDBs

Usage Notes

The newly cloned PDB inherits administration passwords from the source PDB.

dbaascli pdb open

To open a pluggable database (PDB) run the command dbaascli pdb open.

Prerequisite

Run the command as the oracle user.

Syntax

dbaascli pdb open --pdbname pdbname --dbname dbname

Options

In the command:

  • pdbname specifies the name of the PDB that you want to open
  • dbname specifies the name of the container database that hosts the PDB.

Usage Notes

Upon successful completion, the PDB is opened on all of the container database instances.

dbaascli pdb remote_clone

To create a new pluggable database (PDB) as a clone of an existing PDB in another container database (CDB), run the command dbaascli pdb remote_clone.

Prerequisite

Run the command as the oracle user.

Syntax

$ dbaascli pdb remote_clone --pdbname sourcepdbname --source_db sourcedbname --source_db_scan sourcedbscan --dbname dbname

Options

In the command:
  • pdbname specifies the name of the source PDB that you want to clone.
  • sourcedbname specifies the name (DB_UNIQUE_NAME) of the CDB that hosts the source PDB.
  • sourcedbscan specifies the Single Client Access Name (SCAN) that is used to connect to the source database.
  • dbname specifies the name (DB_NAME) of the CDB that hosts the newly cloned PDB.

Usage Notes

When promoted, you must supply the SYS user password for the source PDB.

The newly cloned PDB inherits administration passwords from the source PDB. The cloned PDB is named using the following format: dbname_sourcepdbname

This command is supported only for databases that are not in a Data Guard configuration and use Oracle Database version 12.2.0.1, or later.

dbaascli pdb rename

To change the name of a pluggable database (PDB) use the command dbaascli pdb rename.

Prerequisite

Run the command as the oracle user.

Syntax

dbaascli pdb rename --pdbname oldname --newname newname --dbname dbname

Options

In the command:

  • oldname specifies the old name of the PDB that you want to rename
  • newname specifies the new name of the PDB that you want to rename
  • dbname specifies the name of the container database that hosts the PDB

dbaascli pdb resize

To modify the size limits for a pluggable database (PDB) use the commad dbaascli pdb resize.

Prerequisite

Run the command as the oracle user.

Syntax

dbaascli pdb resize --pdbname pdbname --dbname dbname [--maxsize maxsize] [--maxcpu maxcpu]

Options

In the command:
  • pdbname specifies the name of the new PDB that you want to modify
  • dbname specifies the name of the container database that hosts the PDB
  • maxsize optionally specifies the maximum total size of data files and temporary files for tablespaces belonging to the PDB. Setting this option is effectively the same as setting the MAXSIZE PDB storage clause in the CREATE PLUGGABLE DATABASE SQL command. You can impose a limit by specifying an integer followed by a size unit (K, M, G, or T), or you can specify UNLIMITED to explicitly enforce no limit
  • maxcpu optionally specifies the maximum number of CPUs that are available to the PDB. Setting this option is effectively the same as setting the CPU_COUNT parameter in the PDB.

Usage Notes

When you run the command, you must specify at least one of optional attributes, --maxsize or --maxcpu. You can specify both optional attributes in one command.

dbaascli tde rotate masterkey

To change or rotate the master encryption key for the specified database, run the command dbaascli tde rotate masterkey.

Prerequisite

Run the command as the oracle user.

Syntax

dbaascli tde rotate masterkey --dbname dbname

Options

--dbname dbname specifies the name of the database that you want to act on.

Usage Notes

Enter the keystore password when prompted. The keystore password is initially set to the administration password that you specified when you created the database.

dbaascli tde status

To display information about the keystore for the specified database run the command dbaascli tde status.

Prerequisite

Run the command as the oracle user.

Syntax

$ dbaascli tde status --dbname dbname

Options

In the command, dbname specifies the name of the database that you want to check.

Usage Notes

Output from the command includes the type of keystore, and the status of the keystore.