Versions Compared

Version Old Version 34 New Version Current
Changes made by

Amy Smith

Amber Williams

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Package Method Name

Description

BackupRestoreOracleEphemeralInternalPdb

This is the same container that holds the dbDef to be copied. Eg. if I want to use the DEV database, the cloned db will be created on the same container as the DEV database.

Info

BackupRestoreOracleEphemeralInternalPdb is the faster and more reliable option. Usually it is 2.5 times faster, but it is important to take into account that BackupRestoreOracleEphemeralExternalPdb depends on the internet speed. BackupRestoreOracleEphemeralInternalPdb can be even faster if your internet speed becomes a bottle neck for BackupRestoreOracleEphemeralExternalPdb). We Liquibase strongly recommend recommends this option.

BackupRestoreOracleEphemeralExternalPdb

This container is different and separate from the cloned dbDef.

Info

If you are using OMF mode it should be same on both databases when the copy is made.
We strongly suggest you have
Both containers must be on the same Oracle versions if they want version to use this method.

See: Use the Required deployPackager.properties File

...

External container user privileges:

On the external database we will create a new user on oracle CDB with the following privileges. This allows us Liquibase to create an ephemeral copy and create a link to the source database.

...

Code Block
--- you need to know hostname, port and service name of DB2 database instance
--- you need to know credetialscredentials for database user which has enough priviligesprivileges 
---     to perform copy operation 
CREATE PUBLIC DATABASE LINK liquibase_db_link
    CONNECT TO c##liquibase_ephemeral_source IDENTIFIED BY password
    USING '(DESCRIPTION=
            (ADDRESS=(PROTOCOL=TCP)(HOST=172.18.0.2)(PORT=1521))
            (CONNECT_DATA=(SERVICE_NAME=ORCLCDB))
        )';

...

To check if database link has been created correctly please run query below, if you don’t get errors - database link is should be correct.

Code Block
SELECT * FROM dual@liquibase_db_link;

...

If you use TNS names in your dbDef, then you should prepare either:

  • Prepare a TNS name with _eph postfix for the ephemeral copy because

...

  • Liquibase cannot modify TNS files

...

  • .

  • Or, if you use the oracleEphemeralCopyTnsName deploy packager property, you should prepare a TNS name for the value specified in the property.

    If this is what your dbDefs look like:

Code Block
<dbDefs xsi:type="dbproject:OracleDbDef" name="DEV" hostname="localhost" driver="oracle.jdbc.OracleDriver" tnsName="dev" />
<dbDefs xsi:type="dbproject:OracleDbDef" name="DEV_EPHEMERAL" driver="oracle.jdbc.OracleDriver" tnsName="admin_sysoper" />

Then you should add a dev_eph entry, or your chosen custom name if you used oracleEphemeralCopyTnsName, in your TNS configuration that points to a PDB. To determine the service name or SID for the PDB which that this TNS will point to, use one of the following methods depending on your situation:

  • If you provided a value for oracleEphemeralCopyName , then this value will be what you add to your TNS configuration.

...

If you have a dev entry in your TNS file, then you should create an alias for the dev_eph entry which points to the ephemeral copy (admin_sysoper is just an example entry for a connection pointing to ORCLCDB.)

Example tnsnames.ora file:

Code Block
dev =
(DESCRIPTION =
  (ADDRESS =
     (PROTOCOL = TCP)
     (HOST = 172.17.0.3)
     (PORT = 1521)
  )
  (CONNECT_DATA =
     (SERVER = DEDICATED)
     (SERVICE_NAME = bucket_01)
  )
)


dev_eph =
(DESCRIPTION =
  (ADDRESS =
     (PROTOCOL = TCP)
     (HOST = 172.17.0.3)
     (PORT = 1521)
  )
  (CONNECT_DATA =
     (SERVER = DEDICATED)
     (SID = bucket_01_eph)
  )
)

admin_sysoper =
(DESCRIPTION =
  (ADDRESS =
     (PROTOCOL = TCP)
     (HOST = 172.17.0.3)
     (PORT = 1521)
  )
  (CONNECT_DATA =
     (SERVER = DEDICATED)
     (SID = ORCLCDB)
  )
)
Info

Liquibase recommends creating a dbDef definition in the datical.project but not including this dbDef on any Liquibase pipelines/plans.

...

An ephemeral dbDef must be created in the datical.project file to instruct Liquibase which database should be cloned for the ephemeral copy and to set the connection string information. Because how to connect to the cloned ephemeral copy. Because this database is transient by definition and only exists during the Deploy Packager operation, you are not able to run Status against it.

...

Follow the instructions below based on the desired method.

Info

Important note for an BackupRestoreOracleEphemeralExternalPdb method: If the source dbDef does NOT use TNS, then the ephemeral dbDef should also NOT use TNS. When we create a the PDB copy in another database we need to retrieve is created in the external container, the host and port values need to be retrieved in order to connect to it. If the ephemeral database uses TNS , then we don’t know where to connect to. and the source database does not, the connection cannot be made.

If the source dbDef uses TNS, then the ephemeral dbDef can use anything. You also need to create any connection method. As noted above, if the ephemeral dbDef also uses TNS, a TNS entry with _eph postfix to be able to connect to itmust be created for the connection to occur.

Method 1: Create the dbDef with the Liquibase Enterprise GUI

  1. Create the dbDef using instructions from Creating a Liquibase Enterprise project Using the Liquibase Enterprise GUI

  2. Ensure the Name of the database is <dbDef_to_be_cloned>_EPHEMERAL. This can be DEV, QA, STAGE, or PRODThe <dbDef to be cloned> needs to be the first database in the pipeline.

    image-20240311-142341.png

  3. Enter your Connection Settings.

    1. If you are using a TNSNAMES/LDAP connection, see the section above Use TNSNAMES/LDAP with Oracle Ephemeral Database.

    2. If you are using a BASIC connection, the Service Name is ORCLCDB or the name of the container that houses the ephemeral copy. (See Backup and Restore Package Methods section before for more information.)

      1. Enter your container name in the Hostname text box. This entry depends on if you are using an internal or external backup and restore method. (See Backup and Restore Package Methods section before for more information.)

      2. The username and password are the ORCLCDB user created in step 12. Create ORCLCDB SYSOPER User above.

        image-20240311-173432.png

  4. Contexts and Labels

    1. Contexts are left blank or set to the same context as the dbDef to be cloned.

    2. Set your Labels to either of these:

      1. To the name of the pipeline that houses the dbDef to be cloned

      2. Or use the same pattern that is in use for the dbDef to be cloned

  5. After creating the dbDef, remove the Step from the Pipeline by selecting Remove Step.

    image-20240311-143808.png

  6. Do not select the box to delete the Deployment Step from the Deployment Plan

    image-20240311-143908.png

...

  1. Create the project using the instructions from Creating a Liquibase Enterprise Using the Project Creation Script (project_creator.groovy) https://datical-cs.atlassian.net/wiki/spaces/DDOC/pages/896569181

  2. Include the ephemeral database on the ProjectNameOracle.dbdefs.tsv.txt.
    Use name: <dbDef_to_be_cloned>_EPHEMERAL

...

  1. If the password is present in the file, please note this value is Base64 encoded. If modifying this value, the new value will also need to be Base64 encoded.

  2. Clear out the dbDefsId for the new _EPHEMERAL dbDef.

    Code Block
        <dbDefs xsi:type="dbproject:OracleDbDef" name="DEV_EPHEMERAL" driver="oracle.jdbc.OracleDriver" hostname="cs-oracledb.liquibase.net" port="1521" username="c##liquibase_ephemeral_user" password="bGlxdWliYXNlX3VzZXI=" labels="current" dbDefsId="" serviceName="ORCLCDB" enableCompression="false" rowsPerBatch="10000"/>

  3. Do a Test Connection to another database in the pipeline or sync the project to the DMC to populate the dbDefsId field before checking it the datical.project changes into source control.

6. Optional Step: Associated deployPackager.properties

These are packaging properties available specifically for the ephemeral database packaging method. They are optional if you would like to override the default values.

Property Name

Description

oracleEphemeralSourceNameephemeralCleanUpBeforeStart

[Optional] Defines a source name for an Oracle source PDB in the event Liquibase has not been granted the necessary permissions to query for this name.

Necessary permissions are included below. If these grants are not present, oracleEphemeralSourceName will be required.

  • Multi-schema projects: GRANT SELECT ANY DICTIONARY TO DATICAL_ROLE;

  • Single schema projects Liquibase requires either:

    • GRANT SELECT ANY DICTIONARY TO DATICAL_SCHEMA_OWNER_ROLE;

    • ORpermission to query v$pdbs and dba_data_files

  • See Roles and Permissions for Liquibase Enterprise on Oracle Database for further information on permissions.

Property Validation: Source name should up to 30 characters long, contain no spaces [ ], slashes [/] and semicolons [;] and cannot begin with a number.

oracleEphemeralCopyName

[Optional] Defines a name for an Oracle copy PDB in the event the default name is not desired.

Default name for the ephemeral copy will be source PDB name with _eph postfix. For example, if source name is bucket_01, the copied bucket name will be bucket_01_eph.

Property Validation: Copy name should be up to 30 characters long, contain no spaces [ ], slashes [/] and semicolons [;] and cannot begin with a number.

oracleEphemeralDatabaseLinkName

[Optional] Defines a name for a database link which is used with PackageMethod BackupRestoreOracleEphemeralExternalPdb.

Default link name will be liquibase_db_link.

Property Validation: Database link name should up to 128 characters long, contain no spaces [ ], slashes [/] and semicolons [;] and cannot begin with a number. Allows Liquibase to drop any existing Ephemeral PDB if found during an Ephemeral Packaging Operation. Existing PDBs can occur from failures or cancelations from previous Ephemeral Packaging jobs.

Property Validation: true/false

Default value: false

Available in Liquibase 8.9 and later

oracleEphemeralSourceName

[Optional] Defines a source name for an Oracle source PDB in the event Liquibase has not been granted the necessary permissions to query for this name.

Necessary permissions are included below. If these grants are not present, oracleEphemeralSourceName will be required.

  • Multi-schema projects: GRANT SELECT ANY DICTIONARY TO DATICAL_ROLE;

  • Single schema projects Liquibase requires either:

    • GRANT SELECT ANY DICTIONARY TO DATICAL_SCHEMA_OWNER_ROLE;

    • OR permission to query v$pdbs and dba_data_files

  • See Roles and Permissions for Liquibase Enterprise on Oracle Database for further information on permissions.

Property Validation: Source name should up to 30 characters long, contain no spaces [ ], slashes [/] and semicolons [;] and cannot begin with a number.

oracleEphemeralCopyName

[Optional] Defines a name for an Oracle copy PDB in the event the default name is not desired.

The ephemeral copy's default name will be the source PDB name with the _eph postfix. For example, if the source name is bucket_01, the copied bucket name will be bucket_01_eph.

Property Validation: Copy name should be up to 30 characters long, contain no spaces [ ], slashes [/] and semicolons [;] and cannot begin with a number.

oracleEphemearalCopySid

[Optional] This impacts Oracle Ephemeral packaging only.

Overrides Oracle copy dbDef SID if the source dbDef uses SID as the connection type. If the property is not specified, the _eph postfix will be added to the source SID

Example: e.g., datical_sid → datical_sid_eph

Available in Liquibase 8.9 and later

oracleEphemeralCopyServiceName

[Optional] This impacts Oracle Ephemeral packaging only.
Overrides the Oracle copy dbDef SERVICE_NAME if the source dbDef uses SERVICE_NAME as a connection type. If the property is not specified, _eph postfix will be added to source SERVICE_NAME before a first dot

Example: datical.dev.com -> datical_eph.dev.com

If SERVICE_NAME does not contain dots, they will be added at the end

Example: datical_service_name -> datical_service_name_eph Available in Liquibase 8.9 and later

oracleEphemeralCopyTnsName

[Optional] This impacts Oracle Ephemeral packaging only.

Overrides the Oracle copy dbDef TNS_NAME if the source dbDef uses TNS_NAME as connection type. If the property is not specified _eph postfix will be added to source TNS_NAME

datical_tns -> datical_tns_eph

Available in Liquibase 8.9 and later

oracleEphemeralCopyWithData

[Optional] By default Liquibase will copy databases without data. (*) If you would like to copy both the structure and data, use this boolean property.

(*) There is one exception in that the data from the DATABASECHANGELOG table is included in the database copyin the database copy.

Property Validation: true/false

oracleEphemeralDatabaseLinkName

[Optional] Defines a name for a database link which is used with PackageMethod BackupRestoreOracleEphemeralExternalPdb.

Default link name will be liquibase_db_link.

Property Validation: true/false Database link name should up to 128 characters long, contain no spaces [ ], slashes [/] and semicolons [;] and cannot begin with a number.

oracleEphemeralSkipFinalDeploy

[Optional] The default value for this setting is false. Any changes being packaged are deployed to the first database in the pipeline during the Deploy Packager operation.

Setting this value to true allows changes to be packaged and changesets to be created and stored in the changelog.xml, but the deployment to the first database in the pipeline does not occur.

Property Validation: true/false

...

  • If oracleEphemeralSourceName packager property is not specified we try Liquibase attempts to get the PDB name from 3 three different tables on the DB (v$pdbs and database. These tables are v$pdbs, dba_data_files, or and v$parameter). If you already gave the user required grants according to requested grants are in place as listed on Multi-Schema Projects - Oracle Roles and Permissions, everything should work because both the PDB name can be located. Both GRANT SELECT ANY DICTIONARY TO DATICAL_ROLE; and GRANT IMP_FULL_DATABASE TO DATICAL_PACKAGER_ROLE; already give us enough permission provide the proper permissions to query the required tables. If you haven’t given such permission to us and want to use the ephemeral databaseBackupRestoreMethod - these permissions have not been granted, in order to use ephemeral databaseBackupRestoreMethod, permissions to query v$pdbs, dba_data_files and v$parameter is available tables must be granted.

Use Oracle Managed Files (OMF) with Oracle Ephemeral Database

...