SQLclでCPATを実行してみた

# はじめに
CPAT（Cloud Premigration Advisor Tool)はOracle DatabaseインスタンスをOracle Cloudに移行する際に、問題になる可能性があるコンテンツや移行を妨げる可能性があるその他の要因をチェックするJavaベースのツールです。詳細はMy Oracle Supportの以下のドキュメントでご確認いただけます。

[Cloud Premigration Advisor Tool (CPAT) Analyzes Databases for Suitability of Cloud Migration (Doc ID 2758371.1)](https://support.oracle.com/rs?type=doc&id=2758371.1)

ドキュメントにも記載はあるのですが、CPATは他の製品と統合されています。その中の1つがSQLclです。利用できるのはバージョン22.2以降からとなります。
今回SQLcl23.1でCPATを実行してみました。

# 環境
ターゲットはTLS接続が可能なAutonomous Database(ATP)、ソースはComputeにインストールしたOracle Database12.2のPDBとします。SQLclは別のComputeで各種開発ツールがインストール済みであるOracle Linux Cloud Developerイメージを使いました。

# SQLclでCPATのヘルプを確認
oracleユーザでSQLclを起動し確認します。SQLclではCPATは**migrateadvisor**というコマンドで実行ができます。
```
[opc@dev1 ~]$ sudo su - oracle
[oracle@dev1 ~]$ cd cpat --> あらかじめ作成したディレクトリ
[oracle@dev1 cpat]$ sql /nolog
SQLcl: Release 23.1 Production on Tue Feb 27 03:46:49 2024
Copyright (c) 1982, 2024, Oracle.  All rights reserved.
SQL> ma help

  Usage:
  migrateadvisor|ma COMMAND {OPTIONS}
  migrateadvisor|ma  help|he [-example|-ex]
  migrateadvisor|ma  help|he COMMAND [-syntax|-sy] [-example|-ex]

  The following commands are available within the migrateadvisor feature.

  Commands:
    advise|ad
    Analyze database and produce reports containing information to assist in a
    successful migration.

    properties|pr
    Connect to the target instance to create the properties file allowing instance
    specific analysis.
    Specify the properties file as -analysisprops argument when doing an Advise.

    version|ve
    Show version information for the Cloud Premigration Advisor Tool.
```
サブコマンド**properties**がプロパティ・ファイルの作成、**advise**が分析、レポートの作成となります。これらのコマンドを実行するOracle Dataユーザーには以下の権限が必要です。
+ SELECT ANY DICTIONAYシステム権限

# プロパティ・ファイルの生成
ソース・データベースの分析の前にターゲット・データベースであるAutonomous Databaseのプロパティ・ファイルを生成します。ソース・データべースの分析でプロパティ・ファイルを指定すると、実行されるチェックをターゲット・データベースに最適化することができます。

まずSQLclでADMINユーザーでAutonomous Databaseに接続します。パスワードはWelcome12345#としています。接続文字列はAutonomous Databaseのコンソールの「データベース接続」から「TLS」を選択し、「TNS」がMediumの文字列を使いました。
```
SQL> connect admin/Welcome12345#@(description= (retry_count=20)(retry_delay=3)(address=(protocol=tcps)(port=1521)(host=<adb.ap-osaka-1.oraclecloud.com))(connect_data=(service_name=xxxxxxxxxx_atp1_medium.adb.oraclecloud.com))(security=(ssl_server_dn_match=yes)))

Connected.
```
次にプロパティ・ファイルを生成するためのコマンド**properties**を入力します。-oはファイルを出力するディレクトリ、-pはファイル名の接頭辞を指定するオプションです。
```
SQL> ma properties -o /home/oracle　-p atp1 
Cloud Premigration Advisor Tool
Cloud Premigration Advisor Tool property file location:
    /home/oracle/atp1_premigration_advisor_analysis.properties
    /home/oracle/atp1_premigration_advisor.log
```
実行すると2つのファイルが出力されます。atp1_premigration_advisor_analysis.propertiesが生成されたプロパティ・ファイルとなります。

# 分析の実行
ソース・データベースの分析を実行します。
まずSQLclでソース・データべースに接続します。今回はEasy Connect（簡易接続ネーミング・メソッド）を使って、SYSTEMユーザーで接続しました。
```
SQL> connect system/Manager1@ComputeのIPアドレス:1521/pdb1
connected
```
分析のコマンド**advise**を実行します。-tはターゲット・タイプを指定する必須オプションです。ATPS/ATPD/ADWS/ADWD/DEAULTから選択することができます。ターゲット・データベースはATPでしたのでATPSの指定となります。先に作成したターゲット・データベースのプロパティ・ファイルは-aで指定します。
```
SQL> ma advise -t ATPS -a /home/oracle/atp1_premigration_advisor_analysis.properties

Cloud Premigration Advisor Tool Version 22.10.1-10
--------------------------------------------------------------------------------
Cloud Premigration Advisor Check Summary
--------------------------------------------------------------------------------
Cloud Premigration Advisor Tool completed with overall result: Action Required
    47 Checks run
    39 Schemas in source DB
    3 Schemas analyzed: PDBADMIN, SCOTT, TESTUSER
    1 Action Required: Checks with this result typically need to be resolved before attempting migration.
        Role Privileges (2 relevant objects)
    3 Review Required
    3 Review Suggested
    40 Passed
Cloud Premigration Advisor Tool generated report location(s):
    /home/oracle/cpat/premigration_advisor_report.json
    /home/oracle/cpat/premigration_advisor_report/premigration_advisor_report.html
    /home/oracle/cpat/premigration_advisor.log

---------

```
デフォルトの出力はJSONとHTMLで行われます。
```
[oracle@dev1 cpat]$ ls -al *
-rw-r--r--. 1 oracle oinstall  40263 Feb 29 03:29 premigration_advisor.log
-rw-r--r--. 1 oracle oinstall 105491 Feb 29 03:29 premigration_advisor_report.json

premigration_advisor_report:
total 12
drwxr-xr-x. 4 oracle oinstall   74 Feb 29 03:29 .
drwxr-xr-x. 3 oracle oinstall  113 Feb 29 03:29 ..
drwxr-xr-x. 2 oracle oinstall 4096 Feb 29 03:29 details
-rw-r--r--. 1 oracle oinstall 7577 Feb 29 03:29 premigration_advisor_report.html
drwxr-xr-x. 2 oracle oinstall   41 Feb 29 03:29 utils
```

# レポートの確認
出力された結果をzipでまとめてローカルのPCに持ってきました。
```
[oracle@dev1 cpat] cd /home/oracle
[oracle@dev1 ~]$ zip cpat_result.zip -r cpat
```
解凍してpremigration_advisor_report.htmlを開きます。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/134317/2957d560-a4a2-e338-3a8b-dfa848f42953.png)

Checksの部分を展開すると実行された各チェックが表示され、リンクをクリックするとその詳細を確認することができます。チェックのSQLも詳細で表示されます。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/134317/5179a50c-496d-be86-2510-3443cec78e25.png)

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/134317/4db3dd48-b58c-552b-a5f3-9d2298eb566d.png)

レポートの解釈や各項目については、以下を参考にご確認ください。
+ 20.7 クラウド移行前アドバイザ・ツール(CPAT)レポート・データの解釈(https://docs.oracle.com/cd/F19136_01/sutil/premigration-advisor-tool.html#GUID-4DD2B593-AB68-4492-9D95-CC47CFD28DBA)
+ 20.11 移行前アドバイザ・ツールによって実行されるチェックのリスト（https://docs.oracle.com/cd/F19136_01/sutil/check-list-report-premigration-advisor-tool.html#GUID-3DD93362-15AF-4A6A-B8F8-5916C7A4F2BB）

# おわりに
SQLclで組み込まれたCPATを実行してみました。ツールに組み込まれたCPATを使えば、CPATのダウンロードや準備を省略することができますね。なお、分析時に指定できるオプションはスキーマ指定や出力先ディレクトリ指定など他にもありますので、詳細はドキュメントをご確認ください。

# Tips
SQLclを日本語で出力させたいときはLANGの変更でできます。CPATの出力も日本語になります。
```
export LANG=ja_JP.utf8
```
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/134317/fb23ded0-411e-1a70-47ad-01e47d622c58.png)


# 参考資料
+ [Cloud Premigration Advisor Tool (CPAT) Analyzes Databases for Suitability of Cloud Migration (Doc ID 2758371.1)](https://support.oracle.com/rs?type=doc&id=2758371.1)
+ [『Oracle Databaseユーティリティ』20.クラウド移行前アドバイザツール](https://docs.oracle.com/cd/F19136_01/sutil/premigration-advisor-tool.html#GUID-8D66CC0A-A9A6-46DC-BF7D-1DAB61728651)
+ [『Oracle SQLclユーザーズ・ガイド』6.クラウド移行前アドバイザ・ツールの使用](
https://docs.oracle.com/cd/F87166_01/sqcug/cpat-support.html#GUID-40A62C98-D016-4896-8E5B-D1C022BAC5B7)