Ao avaliar uma migração de banco de dados Oracle para o serviço de Autonomous Database na OCI, precisamos levar em consideração alguns requisitos adicionais, que normalmente não tem as mesmas restrições quando comparamos com uma migração para IaaS, DB System ou ExaCS.
O Autonomous possui algumas restrições técnicas, muitas delas são usadas para garantir o isolamento necessário em um serviço “compartilhado” e de gestão “terceirizada”. O documento “Oracle Database Features in Dedicated Autonomous Database Deployments” lista todas as restrições que devem ser consideradas ao migrar para o Autonomous.
O objetivo deste post é demonstrar como utilizar a ferramenta Cloud Premigration Advisor Tool (CPAT), que automatiza o processo de conectar no banco de dados a ser migrado e faz uma série de validações, gerando um relatório com os itens que podem ameaçar o sucesso da migração, caso não sejam ajustados antes de migrar para o Autonomous Database.
Download do CPAT
O download do CPAT pode ser feito através da nota “Cloud Premigration Advisor Tool (CPAT) Analyzes Databases for Suitability of Cloud Migration (Doc ID 2758371.1)“, não requer instalação e não executa nenhuma alteração no banco de dados sendo analisado (atua como READ-ONLY).
Após clicar no link de download, será aberto a página com uma lista de opções, selecione o patch com a descrição “Cloud Premigration Advisor Tool (CPAT) for version 11.2.0.4 and Higher (Patch)”.
Após o download, copie o arquivo .zip para o servidor de banco de dados, ou qualquer outra máquina que tenha acesso remoto ao banco de dados e disponha do Java 7 ou superior. Neste post, demonstrarei exemplos com execução “Local” no servidor de banco de dados, assim como execução remota.
Descompactando o CPAT no servidor:
mkdir -p /tmp/cpat
unzip p32613591_112048_Generic.zip -d /tmp/cpat
cd /tmp/cpat
Síntaxe de Conexão com o Banco
O CPAT pode ser executado diretamente no servidor de banco de dados, ou a partir de outra máquina, usando uma conexão remota. Mesmo quando o utilitário é executado diretamente no servidor de banco, podemos usar a síntaxe de conexão remota para conectar em um PDB (apesar de eu preferir usar conexão local e o parâmetro –pdbname).
O parâmetro –connectstring é obrigatório, mesmo para execução local com SYSDBA.
Exemplo de conexão local com SYSDBA:
./premigration.sh --connectstring jdbc:oracle:oci:@ --sysdba
Exemplo de conexão remota com SYSDBA informando o ORACLE_SID (ORCL)
./premigration.sh --connectstring jdbc:oracle:oci:@lab01.dibiei.com:1521:ORCL --sysdba --username SYS
Exemplo de conexão remota com SYSDBA informando o SERVICE_NAME (note a mudança do driver “oci” para o driver “thin” na string do JDBC):
./premigration.sh --connectstring jdbc:oracle:thin:@//lab02:1521:SALES --sysdba --username SYS
Exemplo de conexão local, indicando o nome do PDB que deve ser avaliado:
./premigration.sh --connectstring jdbc:oracle:oci:@ --sysdba --pdbname PDB1
O parâmetro –sysdba deve ser usado junto com o parâmetro –connectstring sempre que a conexão com o banco de dados for realizada com o usuário SYS, independente de ser conexão local ou remota. Para conexão remota, deve-se incluir o parâmetro –username junto com –connectstring e –sysdba (assumindo que a conexão é com usuário SYS).
Parâmetros
Podemos obter a lista de parâmetros através da opção –help:
./premigration.sh --help
usage: premigration.sh [-h | -v]
Cloud Premigration Advisor Tool (CPAT) command line syntax for help and version information:
-h,--help Show this help text for the Cloud Premigration Advisor Tool
-v,--version Show the version of the Cloud Premigration Advisor Tool then exit
usage: premigration.sh [-C <simpleVersionString> | -U | -V]
Cloud Premigration Advisor Tool (CPAT) command line syntax for version update checking:
-C,--compareversion <simpleVersionString> Compares the version string argument to the version of the Cloud Premigration Advisor Tool (CPAT) currently running and returns 0, 1, or 2 to the invoking
shell depending on whether the version of CPAT currently executing is "the same", "older", or "more recent" respectively.
-U,--updatecheck Checks to see if an updated version of Cloud Premigration Advisor Tool (CPAT) is available. Network access is required for a successful check.
-V,--simpleversion Outputs the version of the Cloud Premigration Advisor Tool (CPAT) in its simplest form and exits.
usage: premigration.sh [-a <propertyFile>] -c <connectString> [-d] [-f] [-l <loggingLevel>] [-m <migrationMethod>] [-M <maxRelevantObjects>] [-n <maxNumDataRows>] [-o <outputDirectory>] [-p <pdbName>]
[-P <outFilePrefix>] [-r <reportFormat>] [-s <schemaNames> | -x <excludeSchemas>] [-S] -t <cloudType> [-u <username>]
Cloud Premigration Advisor Tool (CPAT) command line syntax for analyzing source database instances:
-a,--analysisprops <propertyFile> The path and name of a properties file, generated previously by using --gettargetprops; to be used when analysing the source database.
-c,--connectstring <connectString> The JDBC connect string for the source database. Should this connect string be for a CDB then '--pdbname' must also be used.
-d,--sysdba Used to force 'AS SYSDBA' when connecting to the database
-f,--full Force the full set of checks to be executed even when --schemas is used
-l,--logginglevel <loggingLevel> Logging levels.
allowed options: severe, warning, info, config, fine, finer, finest
-m,--migrationmethod <migrationMethod> Method(s)/Tooling to do the migration separated by spaces.
allowed options: datapump, datapump_dblink, goldengate
default: datapump
-M,--maxrelevantobjects <maxRelevantObjects> The maximum number of 'relevant objects' to be included in all reports (overrides '--maxtextdatarows' switch for TEXT reports).
default: All relevant objects are included (no maximum)
-n,--maxtextdatarows <maxNumDataRows> The maximum number of 'relevant objects' rows to be included in text reports (does not apply to JSON reports).
defaults: the value given for --maxtextdatarows should that switch be used or all rows otherwise (no maximum)
-o,--outdir <outputDirectory> Points to where the log files and report files should be created
default: current working directory
-p,--pdbname <pdbName> The name of a PDB to connect to. Applicable only when the source database connect string is for a CDB
-P,--outfileprefix <outFilePrefix> A prefix to be used in addition to the standard base file name of "premigration_advisor"
-r,--reportformat <reportFormat> One or more report formats separated by spaces.
allowed options: json, text
default: json
-s,--schemas <schemaNames> The name(s) of the schema(s) in the source database to analyze separated by spaces
-S,--sqltext Include SQL query used for checks in TEXT reports (does not apply to JSON reports).
-t,--targetcloud <cloudType> The type of cloud database being migrated to. DEFAULT indicates a target with no known lockdown profile.
allowed options: atps, atpd, adws, adwd, default
-u,--username <username> The username to use when connecting to the database. Must be a user with SYSDBA/ADMIN privs
-x,--excludeschemas <excludeSchemas> The name(s) of the schema(s) in the source database to exclude from analysis separated by spaces
usage: premigration.sh -c <connectString> [-d] -g [-l <loggingLevel>] [-o <outputDirectory>] [-p <pdbName>] [-P <outFilePrefix>] [-u <username>]
Cloud Premigration Advisor Tool (CPAT) command line syntax for fetching properties from target instances:
-c,--connectstring <connectString> The JDBC connect string for the source database. Should this connect string be for a CDB then '--pdbname' must also be used.
-d,--sysdba Used to force 'AS SYSDBA' when connecting to the database
-g,--gettargetprops Indicates the connection parameters are for the migration target instance and will be used to fetch properties of that instance for later use analyzing the source
database instance.
-l,--logginglevel <loggingLevel> Logging levels.
allowed options: severe, warning, info, config, fine, finer, finest
-o,--outdir <outputDirectory> Points to where the log files and report files should be created
default: current working directory
-p,--pdbname <pdbName> The name of a PDB to connect to. Applicable only when the source database connect string is for a CDB
-P,--outfileprefix <outFilePrefix> A prefix to be used in addition to the standard base file name of "premigration_advisor"
-u,--username <username> The username to use when connecting to the database. Must be a user with SYSDBA/ADMIN privs
Please note that the definitions of JAVA_HOME and ORACLE_HOME can affect CPAT execution.
If JAVA_HOME isn't defined then ORACLE_HOME must contain a Java 7 or higher JVM.
If using a "thin" JDBC URL then ORACLE_HOME need not be defined as long as JAVA_HOME refers to a Java 7 or higher JVM.
If using a "thick" JDBC URL then ORACLE_HOME must be property defined even if JAVA_HOME is refers to a Java 7 or higher JVM.
Principais Parâmetros (os que mais uso):
O parâmetro –targetcloud, onde podemos indicar o tipo do Autonomous Database, se é OLTP ou DW, se é Shared ou Dedicated.
O parâmetro –migrationmethod permite indicar qual será o método de migração, onde basicamente temos Data Pump e Golden Gate. Note que ele diferencia o Data Pump convencional com export + import e o Data Pump com import direto via DBLINK.
A depender do valor informado, o Advisor vai levar em consideração os pré requisitos para usar cada tecnologia. Por exemplo, usando a opção “goldengate”, pode gerar um status de BLOCKER se o parâmetro “enable_goldengate_replication” não estiver configurado com valor TRUE no banco de dados.
O parâmetro –reportformat permite especificar o formato do relatório gerado, sendo text ou json. Eu sempre uso o formato text, por achar ele mais legível e amigável.
O parâmetro –maxrelevantobjects limita a quantidade de objetos que são usados na amostragem do relatório, eu sempre uso ele com um valor baixo para tornar o relatório mais legível. Em uma primeira análise, o status geral de cada item é o mais importante a ser verificado, a relação completa de objetos só seria importante quando avaliando o esforço de aplicar uma ação corretiva.
O parâmetro –schemas pode ser usado para informar uma lista de quais schemas serão migrados, caso não seja uma migração “full”.
Exemplos
1) Migração para Autonomous Dedicated usando Golden Gate:
./premigration.sh --connectstring jdbc:oracle:oci:@ --targetcloud ATPD --sysdba --maxrelevantobjects 50 --reportformat text --migrationmethod goldengate
2) Migração para Autonomous Shared usando Data Pump com import direto via DBLINK:
./premigration.sh --connectstring jdbc:oracle:oci:@ --targetcloud ATPS --sysdba --maxrelevantobjects 50 --reportformat text --migrationmethod datapump_dblink
3) Customizando o prefixo do nome do arquivo gerado (colocando o hostname da máquina atual)
./premigration.sh --connectstring jdbc:oracle:oci:@ --targetcloud ATPS --sysdba --maxrelevantobjects 50 --reportformat text --migrationmethod goldengate --outfileprefix $(hostname)
Analisando o Relatório
Note que assim que a execução é concluída, o CPAT já mostra o resultado geral do relatório (BLOCKER, neste caso):
[oracle@lab02 cpat]$ ./premigration.sh --connectstring jdbc:oracle:oci:@ --targetcloud ATPD --sysdba --maxrelevantobjects 50 --reportformat text --migrationmethod goldengate --outfileprefix cdbsoe --pdbname SALES
Cloud Premigration Advisor Tool Version 22.5.0
Cloud Premigration Advisor Tool completed with overall result: BLOCKER
Cloud Premigration Advisor Tool generated report location: /tmp/cpat/cdbsoe_premigration_advisor_report.txt
Na parte inicial do relatório há a indicação do tipo de destino e método de migração usados na execução do CPAT. Em “Databae Details” temos as informações do banco de dados que foi analisado, como o nome do PDB (quando aplicável), nome da instância, sistema operacional e usuário utilizado na conexão. Por fim, temos a versão do banco de dados, assim como o histórico de patches aplicados.
Na segunda parte do relatório, na seção “Premigration Advisor Report Check Summary”, temos um resumo com a contagem de itens de validação por cada status possível. Aqui devemos focar inicialmente nos itens com status “Blocking Cheks”, que representam os impeditivos técnicos para realizar a migração, podendo ser algo relacionado ao método de migração assim como algo relacionado a diferença de configuração a origem e destino).
Neste exemplo, temos 3 itens com status BLOCKER:
There were 3 checks with BLOCKER results: gg_enabled_replication (1 relevant objects),gg_supplemental_log_data_min (1 relevant objects), nls_character_set_conversion (0 relevant
objects)
Na terceira parte do relatório, na seção “Premigration Advisor Check Details List”, temos o detalhamento de cada item checado, indicando os possíveis impactos e qual seria a ação recomendada.
Neste exemplo, dos três itens com status BLOCKER, dois deles são referentes a configuração para usar Golden Gate (Extract), então são impeditivos técnicos relacionados ao método de migração escolhido, e não tem relação direta com as características do banco de origem em relação as restrições do Autonomous Database.
Assumindo que vamos alterar o parâmetro “enable_goldengate_replication” para TRUE e habilitar o SUPPLEMENTAL LOG DATA, restaria apenas um item com status BLOCKER: nls_character_set_conversion. Este item é mais crítico, pois trata-se de uma característica do banco de dados de origem que não é suportada no Autonomous Database.
Note que a descrição desse item alerta para a possibilidade de receber erros ORA-1401 durante a migração, assim como perder alguns caracteres especiais quando migrar para o Autonomous, devido ao banco de origem usar o CHARACTERSET “WE8MSWIN1252” e destino usar “AL32UTF8” (padrão do Autonomous).
Após avaliar os itens com status BLOCKER, podemos avaliar os itens com status de WARNING. Esses não são impeditivos para a migração, mas teoricamente, poderia gerar algum comportamento “inesperado” durante ou após a migração.
No exemplo abaixo, o item “has_low_streams_pool_size” validou que o parâmetro “streams_pool_size” não tem um valor configurado, o que poderia impactar na performance do Data Pump ou Golden Gate (método de migração), mas isso não chega a ser um real problema para a migração.
Por fim, temos os itens com status INFORMATIONAL, que são configurações ou objetos que serão alteradas na migração, mas não devem representar nenhum problema (em teoria). Na prática, recomendo avaliar com atenção o item “modified_db_parameters_dedicated” e checar se tem algum parâmetro que é recomendado ou até mesmo exigido pelo fornecedor da aplicação.
Neste exemplo não há nenhum parâmetro que possa influenciar no comportamento da aplicação, mas poderia ter alguns parâmetros de otimizador, tratamento de case sensitive na autenticação, entre outros. Particularmente eu sempre olho para esse item como um potencial WARNING ou até mesmo BLOCKER, dependendo dos requisitos da aplicação e se a mesma poderá ser adaptada ou não para as restrições do Autonomous.
Gerando um Arquivo de Properiedades do Destino
Se o ambiente de destino já existir, uma abordagem interessante é gerar um arquivo de propriedades do banco de destino e usá-lo para fazer uma avaliação mais precisa no banco de origem. O CPAT vai levar em consideração os valores reais de alguns atributos, por exemplo, a versão do TimeZone.
Neste exemplo vou gerar um arquivo de properidades conectado em um Autonomous Database Transaction Processing (Shared).
1) Na console OCI, faça o download da Wallet de Conexão do Autonomous para o qual será realizada a migração:
Será baixado na sua máquina o arquivo Wallet_<nome do ADB>.zip. Copie o arquivo .zip para o mesmo servidor no qual está executando o CPAT.
2) Extraia o conteudo do arquivo .zip da Wallet em um diretório:
mkdir -p /tmp/adb_wallet
unzip Wallet_adb1.zip -d /tmp/adb_wallet
Archive: Wallet_adb1.zip
inflating: /tmp/adb_wallet/README
inflating: /tmp/adb_wallet/cwallet.sso
inflating: /tmp/adb_wallet/tnsnames.ora
inflating: /tmp/adb_wallet/truststore.jks
inflating: /tmp/adb_wallet/ojdbc.properties
inflating: /tmp/adb_wallet/sqlnet.ora
inflating: /tmp/adb_wallet/ewallet.p12
inflating: /tmp/adb_wallet/keystore.jks
Dando um cat no arquivo tnsnames.ora, note que ele contém uma entrada para cada SERVICE_NAME do Autonomous:
3) Execute o CPAT conectando no Autonomous, usando o serviço “high” e informando o parâmetro –gettargetprops para gerar o arquivo de propriedades:
./premigration.sh --connectstring jdbc:oracle:thin:@adb1_high?TNS_ADMIN=/tmp/adb_wallet --gettargetprops --username admin
Note que na string de conexão JDBC, informamos a entrada existente no arquivo tnsnames.ora e usamos a opção “?TNS_ADMIN=” para indicar o diretório onde extraimos a wallet do Autonomous.
Outro detalhe que muda neste cenário é sobre o usuário usado na autenticação com o banco, onde não temos acesso SYS no Autonomous, então não podemos usar o parâmetro “–sysdba”. Neste caso, devemos informar algum usuário com permissão de PDB_DBA, usuário “admin” neste exemplo.
Resultado:
$ ./premigration.sh --connectstring jdbc:oracle:thin:@adb1_high?TNS_ADMIN=/tmp/adb_wallet --gettargetprops --username admin
Enter password for admin user:
Cloud Premigration Advisor Tool Version 22.5.0
Cloud Premigration Advisor Tool generated properties file location: /tmp/cpat/premigration_advisor_analysis.properties
4) Execute o CPAT para analisar a origem, usando o arquivo de propriedades gerado anteriormente. Exemplo:
$ ./premigration.sh --connectstring jdbc:oracle:oci:@ --targetcloud ATPS --sysdba --maxrelevantobjects 50 --reportformat text --migrationmethod goldengate --outfileprefix PROD --pdbname SALES --analysisprops /tmp/cpat/premigration_advisor_analysis.properties
O parâmetro –analysisprops é usado para indicar o caminho do arquivo de propriedades gerado no destino no passo anterior.
Simulando Migração Para Oracle Database “Não-Autonomous”
Apesar de o foco principal do CPAT ser migração para Autonomous Database, podemos usá-lo para avaliar uma possível migração para outro tipo de destino, como DBCS ou ExaCS, caso o método de migração seja via DataPump ou Golden Gate.
Isso é possível usando a abordagem de gerar um arquivo de propriedades do destino e usar o valor “default” no parâmetro –targetcloud. Quando usamos o valor “default” neste parâmetro, o CPAT desconsidera uma boa parte das restrições impostas pelo PDB Lockdown Profile do Autonomous Database (O Autonomous é basicamente um PDB dentro de um grande CDB, tendo muitas das suas restrições controladas pela feature de PDB Lockdown).
1) Gerando um arquivo de propriedades em um possível banco de dados de destino:
./premigration.sh --connectstring jdbc:oracle:thin:@//app-scan.dibiei.com:1521/orcl --gettargetprops --username sys --sysdba --outfileprefix ORCL
Enter password for sys user:
Cloud Premigration Advisor Tool Version 22.5.0
Cloud Premigration Advisor Tool generated properties file location: /tmp/cpat/ORCL_premigration_advisor_analysis.properties
2) Executando o CPAT informando um destino “Não-Autonomous”, usando o arquivo de propriedades gerados na etapa anterior:
./premigration.sh --connectstring jdbc:oracle:oci:@ --targetcloud default --sysdba --maxrelevantobjects 50 --reportformat text --migrationmethod goldengate --outfileprefix SALES --pdbname SALES --analysisprops /tmp/cpat/ORCL_premigration_advisor_analysis.properties --outfileprefix ORCL
Cloud Premigration Advisor Tool Version 22.5.0
Cloud Premigration Advisor Tool completed with overall result: WARNING
Cloud Premigration Advisor Tool generated report location: /tmp/cpat/SALES_premigration_advisor_report.txt
Possíveis Erros Ao Usar o Método de Conexão Incorreto
Conexão local usando o driver “thin” ao invés de “oci”
CPAT-1004: SQL error while initializing premigration application.
Unable to start the Universal Connection Pool: oracle.ucp.UniversalConnectionPoolException: Cannot get Connection from Datasource: java.sql.SQLRecoverableException: IO Error: Connect identifier was empty.
Make sure the JDBC connection information is correct. See the log file for more details.
Conexão remota informando o SERVICE_NAME e usando o driver “oci” ao invés de “thin”:
CPAT-1004: SQL error while initializing premigration application.
Unable to start the Universal Connection Pool: oracle.ucp.UniversalConnectionPoolException: Cannot get Connection from Datasource: java.sql.SQLException: ORA-12505: TNS:listener does not currently know of SID given in connect descriptor
Conclusão
Este post apresentou a ferramenta Cloud Premigration Advisor Tool (CPAT) e como podemos usá-la para automatizar algumas etapas da análose de pré requisitos de uma migração para o Autonomous Database, demonstrando o passo a passo para obter o utilitário através do My Oracle Support, exemplos básicos de utilização da ferramenta e uma introução sobre como analisar o resultado do relatório.