ExaCC/CS: modify database parameters in batch mode using dbaascli

This post briefly describes how to use a JSON responseFIle to modify (container) database parameters on Oracle Cloud ExaCC/ExaCS service.

What are our options with dbaascli?

Well, we can simply go ahead and apply single changes one by one.

time sudo dbaascli database modifyParameters --dbname CDBZ001T  --setParameters _fix_control="23473108:off"

DBAAS CLI version 25.1.2.0.0

Executing command database modifyParameters --dbname CDBZ001T --setParameters _fix_control=23473108:off<br><br>Job id: c5f5e1ba-39b6-4ab1-a5fa-c7f1211c037a
Session log: /var/opt/oracle/log/CDBZ001T/database/modifyParameters/dbaastools_2025-06-03_09-15-44-PM_220508.log

Loading PILOT...
Session ID of the current execution is: 18947<br><br>Log file location: /var/opt/oracle/log/CDBZ001T/database/modifyParameters/pilot_2025-06-03_09-15-48-PM_220935
-----------------
Running Plugin_Initialize job
Completed Plugin_Initialize job
-----------------
Running Validate_Parameters job
Completed Validate_Parameters job
-----------------
Running Apply_Dynamic_Parameters_Changes job
Completed Apply_Dynamic_Parameters_Changes job
-----------------
Running Apply_Static_Parameters_Changes job
Completed Apply_Static_Parameters_Changes job

dbaascli execution completed

real    0m20.481s
user    0m0.007s
sys     0m0.008s

What a lucky test, we just set a single hidden parameter without any database restart. But hold on, more then 20 seconds to run a simple ALTER SYSTEM that’s okay but not pretty fast. A database restart was even unnecessary for this testcase.

Well, the best is always to check the Oracle documentation first. Especially, the section about “dbaascli database modifyParameters”

dbaascli database modifyParameters --dbname <value> --setParameters <values>| --resetParameters <values> | --responseFile
[--backupPrepared]
[--instance]
[--allowBounce]

--responseFile specifies the absolute location of the response JSON file to modify the database parameters 

We Oracle DBA folk do certainly understand what is meant when there is a mention about a responseFile 🙂

Where is the –reponseFile option gone?

Well, at the time of writing this article we are using the latest Oracle CloudToolings version available (RPM: dbaastools_exa-1.0-25.1.2.0.0_250505.1725.x86_64) but the option isn’t referenced in the command-line synoposis

# dbaascli database modifyParameters --help
DBAAS CLI version 25.1.2.0.0
Executing command database modifyParameters --help
    database modifyParameters - modifies or resets initialization parameters for a given Oracle database.

      Usage: dbaascli database modifyParameters --dbname <value>
        {
            --setParameters <value> [--instance <value>] [--backupPrepared] [--allowBounce]
            | --resetParameters <value> [--instance <value>] [--backupPrepared] [--allowBounce]
        }
        [--waitForCompletion <value>]

      Where:
        --dbname - Oracle database name.
        --setParameters | --resetParameters
        --setParameters - comma separated list of parameters to be modified with new values. For blank values use ''. E.g. parameter1=valueA,parameter2='',etc.
            [--instance - name of the instance on which the parameters will be processed. If not specified, the operation will be performed at the database level.]
            [--backupPrepared - flag to acknowledge that a proper database backup is in place prior to modifying critical or sensitive parameters.]
            [--allowBounce - flag to grant permission to bounce the database in order to reflect the changes on applicable static parameters.]
        --resetParameters - comma separated list of parameters to be reset to their corresponding default values. E.g. parameter1,parameter2,etc.
            [--instance - name of the instance on which the parameters will be processed. If not specified, the operation will be performed at the database level.]
            [--backupPrepared - flag to acknowledge that a proper database backup is in place prior to modifying critical or sensitive parameters.]
            [--allowBounce - flag to grant permission to bounce the database in order to reflect the changes on applicable static parameters.]
        [--waitForCompletion - specifies false to run the operation in background. Valid values : true|false.]

How to use the JSON file?

Well, here due to the inaccurate information and misleading Synopsis we had to strike back with Oracle support. Indeed, How shall the JSON being formatted ? Which combination are required to “–setParameters” or “–resetParameters” a parameter.

Finally, after some internal research the Oracle support came back (after a while) with the expected JSON format

{
"setParameters":"param1=value,param2=value,param3=value"
}

Sounds pretty logic if you omit all information from Oracle documenation and “dbaascli database modifyParameters” command synopsis.

dbaascli option “–allowBounce”

Changing sequentially static database parameters and restarting the the container database may drastically increase the configuration of (container) database depending on the amount of parameters to modify.

As such, the combination between the dbaascli “–responseFile” and –allowBounce” is an excellent comprise to apply them all at once (batch processing).

And indeed, Oracle executes in background an “ALTER SYSTEM … SCOPE=SPFILE” for all static parameters which requires are database restart. Of course, the restart occurs only once.

Are we obligated to use dbaascli ?

Luckily not, but they are a lot of automation running in background. For instance, if you do not the by yourself the Oracle System Global Area (aka. SGA) anytime you reshape the VMcluster memory, the Oracle SGA will be implicitly reshaped too.

You can check all of them by using following command

# sudo dbaascli database getDetails --dbname CDBZ001T

<snipped truncated for readability>
  "dbName" : "CDBZ001T",
  "dbUniqueName" : "CDBZ001T_SITE2",
  "dbDomain" : "jewlab.ch",
  "dbId" : 3776747013,
  "cpuCount" : 12,
  "sgaTarget" : "8192MB",
  "pgaAggregateTarget" : "5000MB",
  "dbSize" : "7141GB",

<snipped truncated for readability>

Knowing, this you may think about some basic configuration-as-code techniques to manage database parameters.

Wrap-up & Caveats

Using JSON to manage database parameters is quite cool as it can be the starting to point for any kind of configuration as code and even enable documentation-as-code techniques.

Imagine maintaining all your database parameters over a simple YAML file.

  - name: "db_files"
    value: "8192"
    bounce_db: true
    description: "Oracle Bug 33888381 - ORA-1152 after Flashback Pluggable Database (Doc ID 33888381.8)"

As usual, we have always exceptions with Oracle 😉

• dbaascli expect a list of comma separated parameters.
  
  --setParameters specifies a comma-delimited list of parameters to modify with new values. For example: parameter1=valueA,parameter2=valueB, and so on. For blank values use parameter1=valueA,parameter2=”,etc.
  
  As such, you can’t apply with dbaascli parameter with multiple values such as hidden parameter “_fix_control”, but this applies to parameters like event, db_file_name_convert, aso …
  
• dbaascli can’t apply multiple times the same modification at least for parameter db_domain it fails (all the other we tested ran fine)
  
  Running Validate_Parameters job
  Execution of Validate_Parameters failed
  [FATAL] [DBAAS-70154] The modification of the following parameter is not allowed: db_domain.
     ACTION: Verify the requested parameter and try again.
  *** Executing jobs which need to be run always… ***
  
  

Enjoy!