REGISTER EXTRACT

This command applies to Oracle Database and PostgreSQL.

Oracle database

For Oracle database, use REGISTER EXTRACT to register a primary Extract group with an Oracle database to:

Enable integrated capture mode
Specify options for integrated Extract from a multitenant container database
Enable Extract in classic capture mode to work with Oracle Recovery Manager to retain the archive logs needed for recovery

REGISTER EXTRACT is not valid for a data pump Extract.

To unregister an Extract group from the database, use the UNREGISTER EXTRACT command.

Syntax

For classic Extract:

REGISTER EXTRACT group_name LOGRETENTION

For integrated Extract:

REGISTER EXTRACT group-name>
 ( LOGRETENTION | DATABASE
          ( [ CONTAINER container-list |
              ADD   CONTAINER container-list |
              DROP  CONTAINER container-list ]  
            [ SCN   scn   ]  
            [ SHARE ( AUTOMATIC | group-name | NONE ) ]  
            [ [NO]OPTIMIZED ]  
)
)

Container-list is a comma separated list of PDB names, for example (pdb1, pdb2); or wildcarded PDB names, for example (pdb* or pdb?); or both, for example (cdb1_pdb1, pdb*). Supported wildcards are ? and *.

The OPTIMIZED option improves Extract fast startup. The default value is NOOPTIMIZED. The OPTIMIZED option only impacts an upstream non multitenant configuration.

group_name

The name of the Extract group that is to be registered. Do not use a wildcard.

LOGRETENTION

Valid for classic Extract only. Enables an Extract group in classic capture mode to work with Oracle Recovery Manager (RMAN) to retain the logs that Extract needs for recovery. LOGRETENTION is ignored if the Extract group is configured for integrated capture.

The logs are retained from the time that REGISTER EXTRACT is issued, based on the current database SCN. The log-retention feature is controlled with the LOGRETENTION option of the TRANLOGOPTIONS parameter.

Before using REGISTER EXTRACT with LOGRETENTION, issue the DBLOGIN command with the privileges.

DATABASE [

CONTAINER (container[, ...]) |

ADD CONTAINER (container[, ...]) |

DROP CONTAINER (container[, ...])

]

Without options, DATABASE enables integrated capture from a non-CDB database for the Extract group. In this mode, Extract integrates with the database logmining server to receive change data in the form of logical change records (LCR). Extract does not read the redo logs. Extract performs capture processing, transformation, and other requirements. The DML filtering is performed by the logmining server.

Before using REGISTER EXTRACT with DATABASE, use the DBLOGIN command for all Extracts with the privileges granted using the dbms_goldengate_auth.grant_admin_privilege procedure. If you have a downstream configuration, then you must also issue the MININGDBLOGIN command. If the source database you are registering is a CDB database and Extract will fetch data, then grant_admin_privilege must be called with the CONTAINER=>'ALL' parameter.

After using REGISTER EXTRACT, use ADD EXTRACT with the INTEGRATED TRANLOG option to create an Extract group of the same name.

CONTAINER (container[, ...])

Applies the registration to a list of one or more pluggable databases (containers) of a multitenant container database (CDB). Specify one or more pluggable databases as a comma-delimited list within parentheses, for example: CONTAINER (pdb1, pdb2, pdb3). If you list the pluggable databases, they must exist in the database. You can also specify the pluggable databases using the wildcards * and ?. For example, CONTAINER (pdb*).

ADD CONTAINER (container[, ...])

Adds the specified pluggable database to an existing Extract capture configuration. Specify one or more pluggable databases as a comma-delimited list within parentheses or using the wildcards * and ?. For example: ADD CONTAINER (pdb1, pdb2, pdb3). Before issuing REGISTER EXTRACT with this option, stop the Extract group.

For Oracle, adding containers at particular SCN on an existing Extract is not supported.

DROP CONTAINER (container[, ...])

Drops the specified pluggable database from an existing Extract capture configuration. Specify one or more pluggable databases as a comma-delimited list within parentheses or using the wildcards * and ?. For example,DROP CONTAINER (pdb1, pdb2, pdb3).

A register drop container does not fully happen until the Extract has been started and it reads a committed transaction from a dropped pluggable database greater than the Extract checkpoint SCN. Extract then fully drops the containers then shutdowns with a message.

Before issuing REGISTER EXTRACT with this option, stop the Extract group.

SCN system_change_number

Registers Extract to begin capture at a specific system change number (SCN) in the past. Without this option, capture begins from the time that REGISTER EXTRACT is issued. The specified SCN must correspond to the begin SCN of a dictionary build operation in a log file. You can issue the following query to find all valid SCN values:

SELECT first_change#
   FROM v$archived_log 
   WHERE dictionary_begin = 'YES' AND 
      standby_dest = 'NO' AND
      name IS NOT NULL AND 
      status = 'A';

When used alone, the SCN value is the beginning SCN of the dictionary build operation in a log file.

When used in conjunction with SHARE AUTOMATIC or SHARE extract_name, then the specified SCN is the start_scn for the capture session and has the following restrictions:

Should be lesser than or equal to the current SCN.
Should be greater than the minimum (first SCN) of the existing captures.

{SHARE [

AUTOMATIC |

extract |

NONE]}

Registers the Extract to return to an existing LogMiner data dictionary build with a specified SCN creating a clone. This allows for faster creation of Extracts by leveraging existing dictionary builds.

SHARE cannot be used on a CDB.

The following commands are supported:

REGISTER EXTRACT extract database SCN #### SHARE AUTOMATIC 
REGISTER EXTRACT extract database SCN #### SHARE extract 
REGISTER EXTRACT extract database SHARE NONE 
REGISTER EXTRACT extract database SCN #### SHARE NONE

Or

REGISTER EXTRACT extract DATABASE SHARE NONE
REGISTER EXTRACT extract DATABASE SCN #### SHARE NONE

In contrast, the following commands are not supported in a downstream configuration:

REGISTER EXTRACT extract DATABASE SHARE AUTOMATIC
REGISTER EXTRACT extract DATABASE SHARE extract

AUTOMATIC: Clone from the existing closest capture. If no suitable clone candidate is found, then a new build is created.
extract: Clone from the capture session associated for the specified Extract. If this is not possible, then an error occurs the register does not complete.
NONE: Does not clone or create a new build; this is the default.

In a downstream configuration, the SHARE clause must be used in conjunction with the SCN clause when registering for Extract.

Examples

REGISTER EXTRACT sales LOGRETENTION

REGISTER EXTRACT sales DATABASE

REGISTER EXTRACT sales DATABASE CONTAINER (sales, finance, hr)

REGISTER EXTRACT sales DATABASE ADD CONTAINER (customers)

REGISTER EXTRACT sales DATABASE DROP CONTAINER (finance)

REGISTER EXTRACT sales DATABASE SCN 136589

The beginning SCN of the dictionary build is 136589.

REGISTER EXTRACT sales DATABASE SCN 67000 SHARE ext2

The valid start SCN, 67000 in this case; it is not necessarily the current SCN.

REGISTER EXTRACT sales DATABASE CONTAINER (sales, finance, hr) SCN 136589

PostgreSQL

For PostgreSQL, this command will work with GGSCI. Using this command, a replication slot is created in the connected database for PostgreSQL. This command ensures that the PostgreSQL database does not purge the transaction log until the replication slot is moved or removed. The REGISTER EXTRACT command must be run before running the ADD EXTRACT command. You would also needs to run DBLOGIN before registering an Extract.

Syntax

REGISTER EXTRACT Extract

REGISTER EXTRACT Extract with DATABASE database_name

A replication slot is created in the database for the given Extract group name.

Examples

REGISTER EXTRACT Extract

REGISTER EXTRACT esales WITH DATABASE salesdb