Breaking Changes - Upgrade Guide

ansible-oracle 5.x supports ansible-core 2.16 - 2.19. ansible-oracle 4.x supports ansible-core 2.14 - 2.18, so ansible-core 2.19 requires ansible-oracle 5.x.

The minimum version is defined by requires_ansible in meta/runtime.yml and min_ansible_version in meta/main.yml of all roles.

Check the version on the controller or in your execution environment:

The dependencies in galaxy.yml are limited to versions, which support the minimum ansible-core version and Python 3.6 on the target hosts:

ansible-galaxy collection install fails with a dependency conflict, when your requirements.yml pins a version outside of these ranges. Remove the pinning or adjust it to the ranges above.

ansible-core 2.19 requires a real boolean as result of a conditional (when, failed_when, changed_when, until, assert: that). Older versions converted strings like "false" or "yes" silently. Now the task fails:

ansible-oracle 5.0.0 evaluates all boolean variables from the inventory with | bool. Strings like "true", "yes", "false" or extra-vars like -e oracle_sw_copy=false work as before.

Your own playbooks and roles are affected, when they use variables directly in conditionals:

The bool filter accepts true/false, yes/no, on/off, 1/0 (case-insensitive). Other values (e.g. "enabled" or an empty string) result in a deprecation warning and false. This will be an error in ansible-core 2.23.

ansible-core 2.19 has a new templating engine. The result of a template has a different type in some cases. ansible-oracle 5.0.0 is adapted, but templates in your inventory are used as they are.

Examples of failing expressions with ansible-core 2.19:

Recommendations:

An empty template in environment: sets the environment variable to the text None, e.g. _JAVA_OPTIONS=None lets Java fail with Unrecognized option: None. Use "{{ my_value | default('', true) }}" for environment variables, which can be empty.

Embedding these values into other strings is not affected: "gridSetup.sh {{ my_param }}" renders an empty string for None in all versions.

ansible-oracle 5.0.0 is checked for these changes. They are relevant for your own playbooks, inventories and ansible.cfg:

The complete list is in the ansible-core 2.19 Porting Guide.

The defaults of oracle_sw_copy and oracle_sw_unpack depend on install_from_nfs. Until 4.x the defaults were the strings "true" or "false". The string "false" is not empty and was evaluated as true in most conditionals. The documented behavior for install_from_nfs: true (no copy, no unpack) was therefore not active, unless both variables were set explicitly in the inventory.

As of 5.0.0 both defaults are real booleans.

Affected variables with changed default value: oracle_sw_copy, oracle_sw_unpack, oracle_stage_install, oracle_patch_install.

Keep the behavior of 4.x:

Until 4.x the role orahost stopped and disabled firewalld on RHEL/OL by default (disable_firewall: true). As of 5.0.0 firewalld stays active and the role opens the ports of the Oracle listeners:

The change applies only to RHEL/OL target hosts with installed firewalld. SUSE is not changed.

What orahost does with the new defaults:

Other ports are not opened automatically, e.g. EM Express (5500), ORDS/APEX or the Enterprise Manager agent. Add them to oracle_extra_firewall_ports:

Combinations of both variables:

Keep the behavior of 4.x:

The role orasw_meta checks db_homes_config. It is a dependency of nearly all roles, so the check runs in nearly every playbook. As of 5.0.0 only Oracle 19c and 26ai are accepted as version:

version is the base release of the ORACLE_HOME. Release Updates are not part of it, e.g. an ORACLE_HOME with 19.32 uses version: 19.3.0.0.

An ORACLE_HOME with another version stops the playbook with a failed assert, even when the ORACLE_HOME is not used by the playbook. Upgrade the databases to 19c or 26ai, e.g. with the role autoupgrade, and remove the old ORACLE_HOMEs from db_homes_config afterwards.

The assert can be disabled in emergency cases:

python-oracledb (Python package oracledb) is the successor of cx_Oracle. All modules of ansible-oracle are migrated from cx_Oracle to python-oracledb. cx_Oracle is no longer used.

The new role pyoracledb installs python-oracledb with pip3 on the target hosts. The playbook os.yml executes pyoracledb instead of cxoracle.

The modules require python-oracledb on the target hosts instead of cx_Oracle. python-oracledb is used in thick mode, so the Oracle Client libraries must be found (ORACLE_HOME and LD_LIBRARY_PATH), like with cx_Oracle before.

Migrated modules:

The role pyoracledb installs a fixed version of python-oracledb, depending on the Python version of the target host (ansible_python_interpreter, needs gather_facts):

Without changes in the inventory, pyoracledb installs this version from the Python package index (pip install oracledb==<version>). The installation fails, when the target hosts have no access to the package index.

The wheel files of python-oracledb need pip 19.3 or newer (manylinux2014). The system pip of Oracle Linux / RHEL 8 is 9.0.3, it would try to build python-oracledb from source, which fails. Therefore pyoracledb installs pip>=19.3 first, if pip is older (Python 3.6: pip 21.3.1 in /usr/local).

The role pyoracledb uses own variables with the prefix pyoracledb_. The variables of the removed role cxoracle are not used by pyoracledb, even use_proxy, http_proxy and extra_args:

cx_oracle_source / cx_oracle3_source pointed to one package or file. pyoracledb_wheel_dir points to a directory with wheel files of python-oracledb, pip selects the file matching the Python version (pip install --no-index --find-links <pyoracledb_wheel_dir> oracledb==<version>). One directory can contain the wheel files for all Python versions of the target hosts (e.g. cp36 and cp39):

use_proxy, http_proxy and extra_args can be kept in the inventory, if they are used for other purposes.

Example of the migration of the inventory:

Download the wheel files for the target hosts on a host with access to the package index, one command per Python version with the matching version from the table above:

Skip the installation of python-oracledb:

The modules oracle_profile, oracle_job, oracle_directory, oracle_grants and oracle_privs handle names like SQL (ANSI): a name in double quotes (") is case sensitive, a name without quotes is converted to uppercase. All other modules are not changed. The functions for this are in plugins/module_utils/oracle_identifier.py and can be used by more modules in the future. Such a change will be listed here.

PDB names are not affected: Oracle stores them always in uppercase, oracle_pdb converts the name to uppercase as before.

For most inventories nothing changes, because names without " are stored in uppercase as before.

An existing profile with a name in lower or mixed case (created outside of ansible-oracle) was found before with a name in any case. Now the name must be given exactly in ", otherwise the module creates a new profile in uppercase.

The same applies to oracle_grants: a grant on an existing object or role with a lower or mixed case name, which was found before with a name in any case, must be given exactly in ". Otherwise the module tries to grant the privilege on the uppercase name (ORA-00942 or ORA-01919) and, with grants_mode: enforce, revokes the existing grant.

This is a bugfix (#542), but it changes the address used for the database connection.

oracle_db ignored the option hostname (alias host) and always connected to the local host name (os.uname()[1]). This forced a listener on that address, which is not allowed in all environments. Now oracle_db connects to hostname, without hostname to os.uname()[1] as before.

The roles oradb_manage_db, oradb_manage_parameters and oradb_datapatch pass oracle_hostname as hostname, like all other oradb_manage_* roles already do. oracle_hostname defaults to ansible_fqdn, so all roles connect to ansible_fqdn unless oracle_hostname is set in inventory.

For most inventories nothing changes, because the other oradb_manage_* roles already need a listener on oracle_hostname.

This is a new feature (#312), not a breaking change.

Quotas are only removed, if the inventory says so: with size: 0 for a tablespace in quotas, or with quotas_mode: enforce for all tablespaces not in quotas.

oracle_user and the users of oracle_databases / oracle_pdbs (role oradb_manage_users) have two new options:

Oracle rounds a quota up to whole blocks of the tablespace, e.g. size: 1000 is stored as 8192 bytes with a block size of 8K. The comparison uses blocks, so the module is idempotent for such sizes.

This is not a breaking change for inventories, the variables were internal (prefix _). It is listed here for own playbooks or roles which used them.

The role oraasm_manage_diskgroups built the attributes for oracle_asmdg in the variables _oraasm_manage_diskgroups_attr_name and _oraasm_manage_diskgroups_attr_value. For a disk group without attributes they contained the string None, which was passed to oracle_asmdg as attribute (#491). The variables are removed, the role passes attributes of asm_diskgroups directly to oracle_asmdg, a disk group without attributes gets no attributes.

The autostart with autostartup_service: true (Single Instance without Grid Infrastructure / Oracle Restart) uses new systemd units (#265). The solution of 4.x is still available with autostartup_service_mode: legacy.

The service oracle-rdbms.service of 4.x had some problems:

The migration is done by the next run of oradb_manage_db (playbook manage_db.yml). The databases and listeners are not restarted: the new units are started and attach the running databases and listeners. oracle-rdbms.service is disabled. Its unit file is removed, when the service is inactive, otherwise in the first run after the next reboot. An active service without unit file would be stopped without its stop script during a shutdown.

The default of autostartup_service is true since 5.0.0 (4.x: false). A Single Instance without Grid Infrastructure / Oracle Restart gets the autostart of the databases and listeners with the next run of oraswdb_install and oradb_manage_db, when autostartup_service is not set in the inventory. The solution is selected with autostartup_service_mode, see Autostart of databases with one systemd unit per database and listener.

autostartup_service is not used with Grid Infrastructure / Oracle Restart, the databases are started by the Clusterware.

The databases are written with the flag Y into /etc/oratab (as before with autostartup_service: true).

init_parameters in oracle_databases and oracle_pdbs support the new attribute sid (#677). It is the SID clause of ALTER SYSTEM SET, e.g. for local_listener per RAC instance. Without sid or with sid: '*' the parameter is set for all instances as before.

dbca has no SID clause for initialization parameters. A parameter for one instance would be set for all instances during the creation of the database. Therefore sid other than * together with dbca: true is not allowed, the assert of oracle_databases in orasw_meta fails. Entries with sid and without dbca are not passed to dbca (default dbca: false for these entries), they are set by oradb_manage_parameters after the creation of the database.

control_file_record_keep_time defines, how many days the controlfile keeps the records of backups. Without RMAN catalog, RMAN knows only the backups in the controlfile: a value smaller than the recovery window makes backups unusable for RMAN, although they exist.

As of 5.0.0 oradb_rman asserts for every database with rman_jobs:

The playbook stops with a failed assert, when the parameter is missing or too small.

The assert can be disabled in emergency cases:

See RMAN Backups with oradb_rman.

The logging of rman_backup.sh and of the RMAN cron jobs was rebuilt. Before 5.0.0 the output was written into two growing files per job, which mixed the output of parallel executions and were only cleaned up by an external logrotate (e.g. orahost_logrotate).

Changes in detail:

Who is affected:

Required actions:

See RMAN Guide - Logfiles.

With Grid Infrastructure or Oracle Restart oradb_manage_db registers every listener of listener_installed with srvctl add/modify listener (module oracle_crs_listener). As of 5.0.0 the listener resource uses the ORACLE_HOME of the entry:

Changes in detail:

Who is affected:

Required actions:

See LISTENER.md.

As of 5.0.0 the assert of oracle_databases in orasw_meta requires local_listener in init_parameters for every Single Instance database (with and without Oracle Restart) with state: present. RAC and RAC One Node databases are not checked, Clusterware sets local_listener.

Why:

DBCA sets local_listener to an alias, e.g. LISTENER_<DB_NAME>, and writes the alias into tnsnames.ora of the ORACLE_HOME (with Read-Only Oracle Homes in $ORACLE_BASE/homes/<oracle_home_name>/network/admin). After a switch of the ORACLE_HOME (Out-of-Place Patching, see out_of_place_patching.adoc) the alias is missing in tnsnames.ora of the new ORACLE_HOME. The instance cannot resolve local_listener and does not register its services at the listener (ORA-12514 for clients). An EZConnect address in local_listener needs no entry in tnsnames.ora.

Who is affected:

Required actions:

As of 5.0.0 the attributes is_container and omf of oracle_databases are true by default. They need not to be defined in oracle_databases anymore.

Why:

26ai supports only Container Databases and ansible-oracle uses Oracle Managed Files for tablespaces by default. The defaults simplify the inventory.

Who is affected:

Required actions:

As of 5.0.0 the assert of oracle_databases in orasw_meta requires db_create_file_dest and db_recovery_file_dest in init_parameters for every database with state: present and omf: true (default).

Why:

The parameters are needed in different situations, e.g. for dbca, standby databases (RMAN duplicate) and the directories of a new database. They are defined directly in init_parameters instead of deriving them from other variables. dbca uses the values for the datafile and recovery area destination. The global defaults oracle_dbf_dir_fs and oracle_reco_dir_fs are only used with omf: false (only storage_type: FS, own DBCA template, not tested).

Who is affected:

Required actions:

As of 5.0.0 the attributes datafile_dest and recoveryfile_dest of oracle_databases are removed. They are redundant to db_create_file_dest and db_recovery_file_dest in init_parameters. datafile_dest in oracle_pdbs is not affected.

Who is affected:

Required actions:

As of 5.0.0 the assert of oracle_databases in orasw_meta fails for a database with storage_type: ASM and omf: false. ASM without OMF makes no sense in practice. The variables oracle_dbf_dir_asm and oracle_reco_dir_asm are removed, the disk groups are taken from db_create_file_dest and db_recovery_file_dest in init_parameters.

oradb_rman: the templates parameter_rac and parameter_fra_disk use db_create_file_dest from init_parameters for the snapshot controlfile instead of oracle_dbf_dir_asm. Before, parameter_fra_disk created a wrong name with two ` (`+DATA).

Who is affected:

Required actions:

As of 5.0.0 the assert of oracle_databases in orasw_meta fails for a Container Database (is_container: true, default as of 5.0.0) with state: present without max_pdbs in init_parameters (without sid or sid: '*'). max_pdbs defines explicitly how many PDBs are allowed by the license. The value must be an integer:

Who is affected:

Required actions:

As of 5.0.0 the assert of oracle_databases in orasw_meta fails for a database of an Enterprise Edition home (edition: EE in db_homes_config) with state: present without control_management_pack_access in init_parameters (without sid or sid: '*'). control_management_pack_access defines explicitly which Management Packs are licensed. Without the parameter, the Oracle default for Enterprise Edition is DIAGNOSTIC+TUNING, which needs a license for the Diagnostics and Tuning Pack.

The parameter is optional for Standard Edition 2. If it is defined, the value must be NONE, the Management Packs are not available for Standard Edition 2.

Who is affected:

Required actions:

As of 5.0.0 the assert of oracle_databases in orasw_meta fails for a database with state: present without sga_target or pga_aggregate_target in init_parameters. These are the essential memory parameters of an Oracle database and must be defined explicitly. Entries with sid are accepted (instance specific values for RAC).

oracle_db_mem_totalmb (totalMemory in dbca) is not supported anymore, the assert fails if it is set. Before, the assert required either oracle_db_mem_totalmb or sga_target in init_parameters.

Who is affected:

Required actions:

As of 5.0.0 the assert of oracle_databases in orasw_meta fails for a database with state: present with memory_target or memory_max_target in init_parameters (also with sid) if Hugepages are configured (configure_hugepages: true, default of orahost). Automatic Memory Management (AMM) prevents the usage of Hugepages. Entries with state: absent are allowed to remove the parameters from the spfile.

Who is affected:

Required actions:

The role oraswahf_install was an empty placeholder for the installation of Oracle Autonomous Health Framework (AHF) - it had no tasks and no variables. It is removed and replaced by the new role ahf, which installs, upgrades and configures AHF. The central web interface AHF Fleet Insights is installed with the new role ahf_fleet_insights.

The variables and the decisions for an installation are described in Oracle Autonomous Health Framework (AHF).

As of 5.0.0 the assert of oracle_databases in orahost_meta fails for a database with state: present without processes in init_parameters, or with a value which is not an integer > 0. Entries with sid are accepted (instance specific values for RAC).

processes is needed to calculate kernel.sem in orahost_meta and by further asserts. Before, a database without processes failed with an undefined variable (oracle_databases_processes_max), or kernel.sem was calculated without the databases lacking processes.

The assert is in orahost_meta, because orahost_meta runs before the asserts of orasw_meta and the role orahost uses only orahost_meta. It is disabled together with the other asserts of oracle_databases by orasw_meta_assert_oracle_databases: false.

Who is affected:

Required actions:

As of 5.0.0 the default of oracle_install_version_gi is 26.1.0.0 (26ai) instead of 19.3.0.0 (19c). New installations should use the current release, an older release as default makes no sense anymore.

oracle_install_version_gi is only used with oracle_install_option_gi: HA_CONFIG or CRS_CONFIG. Inventories without Grid Infrastructure or Oracle Restart are not affected.

Who is affected:

Required actions: