...

During packager operation it will create a pluggable PDB copy, package all the changes on it and drop the PDB copy after it, if final deploy is not skipped - it will deploy newly packaged changes on desired db def (which is DEV in most of the examples)>.

Image Added

Backup and Restore Package Methods

...

See: Use the Required deployPackager.properties File

BackupRestoreOracleEphemeralInternalPdb

1. Create ORCLCDB SYSOPER User

First you must decide if you are using the internal or external Ephemeral method. Once that is decided, you will create a user.

BackupRestoreOracleEphemeralInternalPdb

You must create a new user on oracle CDB with the following privileges to create an ephemeral copy.

...

BackupRestoreOracleEphemeralExternalPdb

BackupRestoreOracleEphemeralExternalPdb differs from BackupRestoreOracleEphemeralInternalPdb, that it . It makes a copy between two different DB instances, so in all info the guide below covers we are going to have database A and B, so we would like to make an ephemeral copy of the A’s database PDB to database B. To be able to use BackupRestoreOracleEphemeralExternalPdb as databaseBackupRestoreMethod our customer would need to prepare an additional set up for us.

Create ORCLCDB SYSOPER User

On the database A we will to create a new user on oracle CDB with the following privileges to be able to create an ephemeral copy

...

Associated deployPackager.properties

These are packaging properties available specifically for the ephemeral database packaging method.

...

Property Name

...

Description

...

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 GRANT SELECT ON DBA_SYS_PRIVS TO DATICAL_SCHEMA_OWNER_ROLE;, GRANT SELECT ON DBA_ROLE_PRIVS TO DATICAL_SCHEMA_OWNER_ROLE; and GRANT SELECT ON DBA_COL_PRIVS TO DATICAL_SCHEMA_OWNER_ROLE;

• 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 in the even the default name is not desired.

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.

...

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 copy.

Property Validation: true/false

...

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

See: Use the Required deployPackager.properties File

Changes to the Project Repository and datical.project

Follow these steps to implement the ephemeral database configuration for your workflow.

Create an Ephemeral dbDef

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 this database is transient by definition and only exists during the Deploy Packager operation, it is not eligible on a Liquibase pipeline to have Status run against it.

Methods for creating the Ephemeral dbDef

In order to create a dbDef without including the dbDef on an existing pipeline Liquibase recommends using ONE of the following methods:

Create an Ephemeral dbDef

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 this database is transient by definition and only exists during the Deploy Packager operation, it is not eligible on a Liquibase pipeline to have Status run against it.

1. Using TNSNAMES/LDAP with Oracle Ephemeral Database

Learn more about traditional LDAP connections here: LDAP Connection to an Oracle Database

If a customer uses TNS names in dbDef, then customer should prepare a TNS name with _eph postfix him self for the ephemeral copy which we are going to create, as in most cases we are not able to modify TNS files or they can be even stored on remote servers (e.g. OID). So if customer’s dbDefs look like that

<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 customer should also add dev_eph entry in TNS config pointing to a PDB which we are going to create. To determine service name or SID for the PDB which this TNS will point to, use the next logic:

1. If you provided value for oracleEphemeralCopyName , then it will be it

2. If you didn’t provide value for oracleEphemeralCopyName, but provided it for oracleEphemeralSourceName - it will be oracleEphemeralCopyName value + _eph postfix, e.g. if oracleEphemeralCopyName is bucket_01, then your value will be bucket_01_eph

3. If you didn’t provide any of these values, just add _eph postfix to your source PDB name, e.g if your source PDB name is bucket_01, then your value will be bucket_01_eph

This is tnsnames.ora file example that contains dev alias for DEV DbDef, dev_eph alias which customer needs to create, and admin_sysoper alias for DEV_EPHEMERAL DbDef:

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)
  )
)

2. Methods for creating the Ephemeral dbDef

In order to create a dbDef without including the dbDef on an existing pipeline Liquibase recommends using ONE of the following methods:

• Method 1: Create the dbDef using the Liquibase Enterprise GUI and then delete the dbDef from the pipeline.

• Method 2: Include the ephemeral dbDef on the Project Creation Script but do not include the dbDef on any pipelines.

• Method 3: Manually copy the dbDef from an existing dbDef in the pipeline.

Follow the instructions below based on the desired method.

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 PROD.

   Image Removed

3. Enter your Connection Settings.

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

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

      1. You will need to enter your container name in the Hostname text box. This entry will depend 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 should be the ORCLCDB user created in step 1. Create ORCLCDB SYSOPER User above.

         Image Removed

4. Contexts and Labels

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

   2. Labels should generally be set

      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 Removed

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

   Image Removed

Method 2: Create the dbDef with the Project Creation Script

...

Create the project using the instructions from Creating a Liquibase Enterprise Using the Project Creation Script (project_creator.groovy)

...

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 PROD.

   Image Added

3. Enter your Connection Settings.

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

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

      1. You will need to enter your container name in the Hostname text box. This entry will depend 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 should be the ORCLCDB user created in step 1. Create ORCLCDB SYSOPER User above.

         Image Added

4. Contexts and Labels

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

   2. Labels should generally be set

      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 Added

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

   Image Added

Method 2: Create the dbDef with the Project Creation Script

1. Create the project using the instructions from Creating a Liquibase Enterprise Using the Project Creation Script (project_creator.groovy)

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

3. Do not reference the ephemeral database as part of any pipeline on ProjectNameOracle.pipelines.tsv.txt

...

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 to populate the dbDefsId field before checking into source control.

Using TNSNAMES/LDAP with Oracle Ephemeral Database

Learn more about traditional LDAP connections here: LDAP Connection to an Oracle Database

If a customer uses TNS names in dbDef, then customer should prepare a TNS name with _eph postfix him self for the ephemeral copy which we are going to create, as in most cases we are not able to modify TNS files or they can be even stored on remote servers (e.g. OID). So if customer’s dbDefs look like that

<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 customer should also add dev_eph entry in TNS config pointing to a PDB which we are going to create. To determine service name or SID for the PDB which this TNS will point to, use the next logic:

...

If you provided value for oracleEphemeralCopyName , then it will be it

...

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.

...

If you didn’t provide any of these values, just add _eph postfix to your source PDB name, e.g if your source PDB name is bucket_01, then your value will be bucket_01_eph

This is tnsnames.ora file example that contains dev alias for DEV DbDef, dev_eph alias which customer needs to create, and admin_sysoper alias for DEV_EPHEMERAL DbDef:

...

See: Use the Required deployPackager.properties File

Troubleshooting:

Potential grants issues

If oracleEphemeralSourceName packager property is not specified we try to get PDB name from 2 tables on the DB (v$pdbs and dba_data_files), if customer already gave the user required grants according to Multi-Schema Projects - Oracle Roles and Permissions , everything should work because both GRANT SELECT ANY DICTIONARY TO DATICAL_ROLE; and GRANT IMP_FULL_DATABASE TO DATICAL_PACKAGER_ROLE; already give us enough permission to query the tables, but if customer hasn’t given such permission to us and want to use the ephemeral databaseBackupRestoreMethod - permissions to query v$pdbs and dba_data_files should be provided.

Using Oracle Managed Files (OMF) with Oracle Ephemeral Database

If using OMF with BackupRestoreOracleEphemeralExternalPdb then OMF mode should be the same on both instances of the Oracle database.