Configurar o Oracle para ingestão no Databricks

info

Beta

Este recurso está em Beta. Os administradores do workspace podem controlar o acesso a esse recurso na página Pré-visualizações . Consulte Gerenciar prévias do Databricks.

Esta página descreve as tarefas de banco de dados de origem necessárias para a ingestão do Oracle no Databricks Lakeflow Connect.

O conector Oracle usa o LogMiner no modo de transação não confirmada para ler alterações de redo logs online e logs de arquivo.

Requisitos

• Versão do Oracle 12c ou acima (12c, 18c, 19c, 21c, 23ai e 26ai).
• Modo de log de arquivo habilitado.
• Log suplementar habilitado para as tabelas que você deseja replicar. O log suplementar de key primária é o mínimo; o log suplementar completo é necessário para tabelas que recebem instruções UPDATE em colunas de key primária ou key exclusiva. O log suplementar mínimo por si só não é suficiente. Consulte Qual método de log suplementar devo escolher?.
• Um banco de dados primário (não em espera). Oracle RAC e dados criptografados com Transparent Data Encryption (TDE) com uma carteira fechada não são suportados.
• Para bancos de dados multi-tenant, um usuário comum em CDB$ROOT com os privilégios necessários.

Visão geral da configuração da fonte

Conclua as seguintes tarefas no Oracle antes de ingerir dados no Databricks. Faça a execução de cada passo como o usuário SYSDBA, ou como o usuário ADMIN para bancos de dados Amazon RDS. [[ ## completed ##]]

1. Verificar o modo de log de arquivo e a retenção de log.
2. Ativar registros suplementares.
3. Criar um usuário de replicação usando o script de configuração.
4. Observe os detalhes da conexão, incluindo o nome do serviço e o domínio do banco de dados.

O passo 1: Verificar o modo de Logs de arquivo e a retenção de Logs [[ ## completed ##]]

O conector CDC integrado do Oracle lê logs de arquivo. A seguinte query deve retornar ARCHIVELOG:

SQL

SELECT LOG_MODE FROM V$DATABASE;

Se a query retornar NOARCHIVELOG, habilite o modo de log de arquivo antes de continuar.

os passos para habilitar Logs de arquivo

Non-RDS database

Para bancos de dados Oracle padrão:

SQL

SHUTDOWN IMMEDIATE;
STARTUP MOUNT;
ALTER DATABASE ARCHIVELOG;
ALTER DATABASE OPEN;

Amazon RDS database

Para Oracle no AWS RDS, habilite backups automáticos.

Garantir a retenção de Logs de arquivo

A Databricks recomenda reter logs de arquivo por pelo menos 48 horas. Se o Oracle limpar os logs de arquivo antes que o pipeline possa processá-los, você deve realizar um refresh completo nas tabelas afetadas. Planeje sua capacidade de disco adequadamente para armazenar os arquivos de log de arquivo retidos.

Non-RDS database

Faça a execução do seguinte no Recovery Manager (RMAN). [[ ## completed ##]]

SQL

CONFIGURE RETENTION POLICY TO RECOVERY WINDOW OF 2 DAYS;

Amazon RDS database

Para Oracle no AWS RDS, consulte a documentação da AWS.

SQL

BEGIN
    rdsadmin.rdsadmin_util.set_configuration(
        name  => 'archivelog retention hours',
        value => '48');
END;

o passo 2: Ativar o log suplementar

O conector requer pelo menos registro suplementar de key primária em cada tabela que você replicar. Registro suplementar completo é necessário para tabelas que recebem instruções UPDATE em colunas de key primária ou key exclusiva. Para obter detalhes, consulte Qual método de registro suplementar devo escolher?.

Você pode habilitar o log suplementar em cada tabela ou no nível do banco de dados para que todas as tabelas o herdem. Os comandos diferem dependendo se a execução do seu banco de dados ocorre no Amazon RDS.

Para habilitar o registro suplementar de key primária no nível da tabela: [[ ## completed ##]]

SQL

ALTER TABLE <schema>.<table> ADD SUPPLEMENTAL LOG DATA (PRIMARY KEY) COLUMNS;

Para habilitar o log suplementar completo no nível da tabela:

SQL

ALTER TABLE <schema>.<table> ADD SUPPLEMENTAL LOG DATA (ALL) COLUMNS;

Para habilitar o log suplementar de key primária no nível do banco de dados (opcional; cada tabela o herda):

Non-RDS database

SQL

ALTER DATABASE ADD SUPPLEMENTAL LOG DATA (PRIMARY KEY) COLUMNS;

Amazon RDS database

SQL

BEGIN
  rdsadmin.rdsadmin_util.alter_supplemental_logging(
    p_action => 'ADD',
    p_type   => 'PRIMARY KEY'
  );
END;

Consulte a documentação da AWS para obter mais detalhes.

O passo 3: Criar um usuário de replicação usando o script de configuração

O Databricks fornece uma ferramenta de configuração Oracle PL/SQL (dbx_oracle_setup_util) que automatiza a criação de usuários e a concessão de privilégios para CDC. O pacote expõe os seguintes procedimentos:

Procedimento	Descrição
create_user(...)	Cria um usuário de replicação CDC com um tablespace default especificado, um tablespace temporário e cota ilimitada no tablespace default.
grant_permissions(...)	Concede os privilégios de sistema e de objeto necessários para o CDC do LogMiner. Consulte requisitos de usuário do banco de dados Oracle.
grant_select_permissions(...)	Concede SELECT em todas as tabelas de um esquema.
grant_select_on_table(...)	Concede SELECT em uma tabela específica.
validate_setup(...)	Valida o ambiente de banco de dados, a configuração de banco de dados necessária, o usuário de replicação e os privilégios necessários.
drop_user(...)	Remove um usuário de replicação criado anteriormente. Use isto para limpar ou recriar o usuário.

Procedimento	Descrição
create_user(...)	Cria um usuário de replicação CDC com um tablespace default especificado, um tablespace temporário e cota ilimitada no tablespace default.
grant_permissions(...)	Concede os privilégios de sistema e de objeto necessários para o CDC do LogMiner. Consulte requisitos de usuário do banco de dados Oracle.
grant_select_permissions(...)	Concede SELECT em todas as tabelas de um esquema.
grant_select_on_table(...)	Concede SELECT em uma tabela específica.
validate_setup(...)	Valida o ambiente de banco de dados, a configuração de banco de dados necessária, o usuário de replicação e os privilégios necessários.
drop_user(...)	Remove um usuário de replicação criado anteriormente. Use isto para limpar ou recriar o usuário.

Instalar a ferramenta de configuração

1. Faça o download da ferramenta de configuração: dbx-oracle-setup-pacote.sql. [[ ## completed ##]]

2. Faça a execução do script para criar o pacote PL/SQL dbx_oracle_setup_util. Execute-o com privilégios SYSDBA (ou como o usuário ADMIN no Amazon RDS).

   Para um banco de dados multi-tenant, faça a execução do script no contêiner CDB$ROOT.

Criar o usuário de replicação

Crie um usuário de replicação dedicado. O nome de usuário deve estar em maiúsculas. Para um banco de dados multi-tenant (CDB), o nome de usuário deve começar com C## para que um usuário comum seja criado. Para um banco de dados não CDB, não use o prefixo C##.

O exemplo a seguir cria um usuário denominado C##CDCREPL com tablespace default USERS e tablespace temporário TEMP:

SQL

BEGIN
  DBX_ORACLE_SETUP_UTIL.CREATE_USER('C##CDCREPL', '<password>', 'USERS', 'TEMP');
END;
/

nota

Não use o usuário SYS ou SYSTEM para replicação.

Conceder privilégios em nível de banco de dados

Conceda ao usuário de replicação os privilégios necessários para o CDC do LogMiner. A ferramenta escolhe automaticamente o método de concessão correto para o seu ambiente (concessões padrão ou concessões do Amazon RDS rdsadmin) e define CONTAINER_DATA=ALL para bancos de dados multi-tenant.

SQL

BEGIN
  DBX_ORACLE_SETUP_UTIL.GRANT_PERMISSIONS('C##CDCREPL');
END;
/

Para a lista completa de privilégios que a ferramenta concede, consulte Requisitos de usuário do Oracle database.

Conceder privilégios SELECT em tabelas

Conceda ao usuário de replicação SELECT em todas as tabelas que você replicar. A ferramenta de configuração fornece dois procedimentos para isso:

SQL

BEGIN
  -- to grant SELECT on all tables in a schema
  DBX_ORACLE_SETUP_UTIL.GRANT_SELECT_PERMISSIONS('C##CDCREPL', '<schema_to_replicate>', '<container_name>');
  -- to grant SELECT on specific tables in the schema
  DBX_ORACLE_SETUP_UTIL.GRANT_SELECT_ON_TABLE('C##CDCREPL', '<schema_to_replicate>', '<table_name>', '<container_name>');
END;
/

Para um banco de dados não CDB, omita o argumento <container_name>.

Você também pode conceder SELECT manualmente em tabelas individuais:

SQL

GRANT SELECT ON <schema>.<table> TO C##CDCREPL;

A interface do usuário só pode mostrar tabelas nas quais o usuário de replicação tem a permissão SELECT.

nota

O privilégio SELECT ANY TABLE do Oracle concede acesso de leitura a todas as tabelas no banco de dados em uma única instrução. Evite isso fora de um banco de dados de desenvolvimento, pois ele expõe tabelas que você talvez não queira que o usuário de replicação leia.

Validar a configuração

Valide o ambiente de banco de dados, a configuração de banco de dados necessária, o usuário de replicação e os privilégios necessários:

SQL

BEGIN
  DBX_ORACLE_SETUP_UTIL.VALIDATE_SETUP('C##CDCREPL');
END;
/

o passo 4: anotar os detalhes da conexão

Ao criar a conexão do Unity Catalog, você precisará dos seguintes detalhes sobre seu banco de dados Oracle. Consulte Criar uma conexão Oracle.

Nome do serviço

O conector conecta-se ao Oracle usando um nome de serviço .

• Para uma base de dados single-tenant (não CDB) , use o nome do serviço da base de dados.
• Para um banco de dados multi-tenant (CDB) , use o nome de serviço CDB$ROOT. O conector conecta-se ao CDB$ROOT para ler alterações de todos os bancos de dados plugáveis (PDBs) e, em seguida, resolve os nomes de serviço PDB automaticamente. Consulte Bancos de dados multi-tenant (CDB).

Domínio do banco de dados

Se o seu banco de dados estiver com o parâmetro de inicialização DB_DOMAIN definido, o Oracle registrará cada serviço no listener usando um nome qualificado por domínio (por exemplo, FREEPDB1.example.com em vez de FREEPDB1). Isso é comum em ambientes gerenciados pelo Oracle Connection Manager (CMAN).

Quando DB_DOMAIN estiver definido, o nome do serviço CDB$ROOT que você fornecer na conexão do Unity Catalog deverá incluir o sufixo de domínio (por exemplo, newcorp.example.com). Para verificar o valor atual:

SQL

SELECT value FROM v$parameter WHERE name = 'db_domain';

O conector anexa automaticamente o DB_DOMAIN descoberto aos nomes de serviço PDB. Você só precisa fornecer o nome de serviço CDB$ROOT qualificado por domínio na conexão. Para obter detalhes, consulte Criar uma conexão Oracle.

Bancos de dados multi-tenant (CDB)

Para um banco de dados multi-tenant:

• Faça a execução do script no contêiner CDB$ROOT.
• O usuário de replicação deve ser um usuário comum (o prefixo C##).
• A ferramenta de configuração define CONTAINER_DATA=ALL no usuário para que ele possa ler dados de alteração em todos os contêineres.
• Na conexão do Unity Catalog, use o nome do serviço CDB$ROOT (qualificado por domínio se DB_DOMAIN estiver definido).

Instâncias multi-tenant do Amazon RDS para Oracle não são suportadas.

Diferenciação entre maiúsculas e minúsculas

Por default, a Oracle trata identificadores sem aspas como não diferenciam maiúsculas de minúsculas e os converte para maiúsculas. Se um identificador for delimitado entre aspas duplas durante a criação, o Oracle preserva o uso de maiúsculas e minúsculas.

Ao criar a conexão do Unity Catalog, use um nome de usuário em letras maiúsculas, a menos que o banco de dados o armazene em letras minúsculas. Ao especificar nomes de esquema, tabela e coluna em seu pipeline, o uso de maiúsculas e minúsculas deve corresponder à forma como o Oracle armazena o identificador.

Limitações do LogMiner

O LogMiner não oferece suporte aos seguintes tipos de dados e atributos de armazenamento. Se uma tabela contiver qualquer um destes, o LogMiner ignora a tabela inteira:

• BFILE
• Tabelas aninhadas e coleções VARRAY
• Objetos com tabelas aninhadas
• Tabelas com colunas de identidade
• Colunas de validade temporal
• PKREF Colunas
• PKOID colunas (colunas do tipo object)
• Atributos de tabelas aninhadas e colunas de tabelas aninhadas autônomas

Além disso:

• Os nomes de tabela e coluna não podem exceder 30 caracteres.
• Tipos de dados e recursos adicionados após o Oracle Database 12c Release 2 (12.2) não são compatíveis. Isso inclui BOOLEAN, VECTOR e JSON.

Mapeamentos de tipos de dados

Para o mapeamento de tipos de dados Oracle para tipos Databricks, consulte referência do conector CDC integrado do Oracle.

Passos seguintes

• Revise os requisitos de privilégio.
• Criar uma conexão Oracle.