OCI データベース・ツールでオラクルDBへの接続方法

本ブログは、[オラクル・クラウドの個人ブログ](https://qiita.com/letian/items/10152a4fec813c1b7d98)の1つです。

# 初めに
冒頭ですが、この記事の位置付けは、次のシリーズ記事の1つです。
[プライベート・サブネット内の Oracle DB/ADB に接続](https://qiita.com/liu-wei/items/10152a4fec813c1b7d98#4-%E3%83%97%E3%83%A9%E3%82%A4%E3%83%99%E3%83%BC%E3%83%88%E3%82%B5%E3%83%96%E3%83%8D%E3%83%83%E3%83%88%E5%86%85%E3%81%AE-oracle-dbadb-%E3%81%AB%E6%8E%A5%E7%B6%9A)

データベース・ツールは、2021年11月3日にリリースされた新しいOCIマネージド・サービスです。これにより、OCI内の任意の<strong>Oracle</strong>または<strong>MySQL DBサービス</strong>への接続を作成できます。データベース接続と<strong>SQLワークシート</strong>を併用することで、データベースへの直接SQLアクセスができます。パスワードや「Autonomous DB」のウォレット・ファイルなどの機密情報は暗号化されて、<strong>OCIボールト</strong>に安全に保存されます。

この新サービスを使用し、OCIの「DB System Database」および「Autonomous DB」に接続する方法を紹介したいと思います。少しお役に立てれば幸いです。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1121622/76c7c890-5e24-401d-ab9b-41a67117a43d.png)

__サポート対象のDBタイプ__
Autonomous Database
DB system database (BM,VM,Exadata)
Exadata VM cluster database

__動作検証環境__

|項目|DB System|Autonomous DB|
|:--|:--|:--|
|DBタイプ|VM|Autonomous Data Warehouse (Shared)|
|DBバージョン|21c Standard Edtion|19c|
|サブネット|プライベート・サブネット|N/A|
|接続タイプ|プライベート・エンドポイント|パブリック|

__ステップ__
- [1. 準備](#1-準備)
  - [1-1) IAMポリシーの作成](#1-1-iamポリシーの作成)
  - [1-2) ボールトの作成](#1-2-ボールトの作成)
  - [1-3) プライベート・エンドポイントの作成](#1-3-プライベートエンドポイントの作成)
  - [1-4) 要塞の作成 (オプション)](#1-4-要塞の作成-オプション)
- [2. DBシステム・データベースへの接続方法](#2-dbシステムデータベースへの接続方法)
- [3. Autonomous DBへの接続方法](#3-autonomous-dbへの接続方法)

# 1. 準備
## 1-1) IAMポリシーの作成
下記のリソースに対する「<strong>管理</strong>」権限は必要です。
Database Tools Service, Vaults, VCNs, Oracle DB or Autonomous DB Services, Secrets, Keys.

<strong>ポリシーの例:</strong>
事前に「toolsConnectionAdmin」という名前のグループを用意してください。

```
allow group toolsConnectionAdmin to manage virtual-network-family in compartment PoC
allow group toolsConnectionAdmin to manage database-family in compartment PoC
allow group toolsConnectionAdmin to manage autonomous-database-family in compartment PoC
allow group toolsConnectionAdmin to manage vaults in compartment PoC
allow group toolsConnectionAdmin to manage secret-family in compartment PoC
allow group toolsConnectionAdmin to manage database-tools-family in compartment PoC
```

ルート・コンパートメントの下に「PoC」というコンパートメントを使用しています。
必要に応じて、ポリシーを<font color=blue>テナンシー・レベル</font>(in tenancy)で設定できます。

## 1-2) ボールトの作成
パスワードやウォレット・ファイルなどの機密情報はOCIボールトに保存されますので、ボールトを持っていない場合は作成する必要があります。

メニュー → アイデンティティとセキュリティ → ボールト
ボールト名を入力し、「ボールトの作成」ボタンをクリックします。
<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1121622/96d6f3bc-b75a-b269-e3ce-3608060775eb.png" width="550">

ボールトが作成された後、<strong>マスター暗号化キー</strong>の作成を続行します。
<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1121622/a48f38a5-9391-01ee-46c4-3208098bc852.png" width="550">

## 1-3) プライベート・エンドポイントの作成
セキュリティの原因で、通常ならデータベースは、プライベート・サブネットに配置されます。この場合、プライベート・エンドポイントを介しDBにアクセスする必要があります。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1121622/c88245e1-c725-f549-862b-3b60931fb59d.png)

メニュー → 開発者サービス → データベース・ツール → プライベート・エンドポイント
<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1121622/da3cd355-f429-05d1-a9f2-70d0908467ce.png">

以下のように必要な情報を入力し、「作成」ボタンをクリックしてください。
<strong>データベースの選択</strong>は、デフォルトのオプションで、この例で使用します。
「データベース・タイプ」と「DBシステム」のリストは、「データベースの選択」を指定した場合のみ、使用できます。
<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1121622/5fa7cde4-4b6e-c658-4c9e-3a7171c59e7f.png" width="400">
まもなくプライベート・エンドポイントは、アクティブの状態になります。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1121622/f7cd9fa7-52c6-6a32-2a73-e6578dd6eb65.png)

## 1-4) 要塞の作成 (オプション)
<strong>プライベート・エンドポイントを介してSQLclを起動する場合</strong>lは、このステップを実施する必要があります。以下のいずれを該当する場合、スキップできます。

- SQLclを起動したくない場合
- パブリックのアクセスを使用して、パブリック・サブネットに存在するデータベースに接続する場合

メニュー → アイデンティティとセキュリティ → 要塞 -> 要塞の作成
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1121622/6f4d62e2-267d-c0a8-cb0d-ce3a06c15189.png)

必要な情報を入力し、「要塞の作成」ボタンをクリックします。

|項目|コメント|
|:--|:--|
|要塞名|<strong>英数字</strong>のみ|
|ターゲット・サブネット|ターゲットDBが配置されている場所。|
|CIDRブロック許可リスト|ターゲットDBへの接続を許可するIPアドレス範囲。<br>範囲を絞ることはお勧め（以下の"All Zero"はテスト用のみ）。<br>作成後に編集できる。|
<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1121622/6497f836-8b92-deb2-4547-04d32fe3fcc7.png" width="550">
まもなく要塞は、アクティブの状態になります。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1121622/45bd1f5f-9741-9a5f-bc81-622236404733.png)

# 2. DBシステム・データベースへの接続方法
メニュー → 開発者サービス → データベース・ツール → 接続 → 接続の作成

|項目|コメント|
|:--|:--|
|<strong>データベースの選択</strong>|デフォルト|
|データベース情報の入力|これを指定したら、既存のDBをリストから選択できなくなる。|
|データベース・タイプ|"DB System Database"を選択する。<br>（「データベースの選択」を指定した場合、利用可能。）|
|データベース・システム|既存のDBシステムを選択する。<br>（「データベースの選択」を指定した場合、利用可能。）|
|データベース・ホーム|データベース・ホームを選択する。<br>（「データベースの選択」を指定した場合、利用可能。）|
|データベース|ターゲットDBを選択する。<br>（「データベースの選択」を指定した場合、利用可能。）|
|プラガブル・データベース <em>オプション</em>|CDBに接続する場合は、選択不要。<br>（「データベースの選択」を指定した場合、利用可能。）|
|ユーザー名|DBユーザー|
|ロール|選択しない場合、"<strong>Default</strong>"のロールとなる。|
|ユーザー・パスワード・シークレット|持っていない場合は、「パスワードシークレットの作成」をクリックして新規作成する。|
|接続文字列| <strong>「データベースの選択」</strong>を指定した場合、接続文字列が自動に作成されるので、編集しなくてもよい。<br><strong>「データベース情報の入力」</strong>を指定した場合は、接続文字列を入力する必要がある。|

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1121622/059c422c-009d-e8a5-7f6e-902b7ef3c625.png)
「パスワード・シークレットの作成」のダイアログ画面にユーザー・パスワードを入力し、「作成」ボタンをクリックします。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1121622/1f79dc2c-e062-2daa-fc85-c52a384b44a7.png)

「<strong>プライベート・エンドポイントを介したネットワーク接続</strong>」にチェックを入れ、ステップ1-3で作成したプライベート・エンドポイントを選択し、「次へ」ボタンをクリックして進みます。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1121622/43c87c9c-a318-400f-97f4-49f5a1fa1d0e.png)

ウォレット・フォーマットは「なし」を選択し、「作成」ボタンをクリックします。
<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1121622/987a24e5-3115-48e3-f69e-85353f5ee61b.png" width="450">

作成には数分かかります。ステータスがアクティブになったら、「<strong>検証</strong>」ボタンをクリックしてDB接続を検証します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1121622/6e8b3744-de1a-a1dd-76d9-5cca6073a301.png)
検証成功の場合、以下のようなメッセージが表示されます。
<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1121622/0f9068a3-f5e5-d14b-0d59-873ce3d223f5.png" width="500">

__接続の問題__
DBへの接続が失敗した場合、以下のような原因は一般的です。ご参考ください。

- 無効なユーザーまたはパスワード。
- ユーザー・ロールの指定は間違った。
- DBインスタンスは、まだ起動していない。
- DBリスナー・ポート（TCP 1521）は、Ingressルールに追加されていない。(セキュリティ・リストまたはNSGを確認してください。)

__SQLワークシート__
「接続の詳細」画面のボタンをクリックして「SQLワークシート」を起動すると、SQLコマンドを実行できます。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1121622/92b8da62-5598-b173-c703-8f5969cef105.png)

SQLコマンドだけでなく、<strong>OCIオブジェクト・ストレージまたはローカル</strong>にある<strong>SQLスクリプト</strong>も実行できます。複数のデータベース接続を作成した場合は、メニュー（右上）から<strong>使用中の接続を変更できます</strong>。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1121622/96d571fe-195f-1e08-3a93-0b170ff1c922.png)

__SQLclの起動__
「接続の詳細」画面のボタンをクリックして、SQLclを起動します。この時、STEP1-4で作成した要塞を指定します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1121622/51977454-7c75-0e92-e5ed-e016835c7f54.png)

Cloud ShellからSQLclを起動した後、通常どおりSQLコマンドを実行できます。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1121622/42ff683f-f8df-e246-05bf-cf20a628b1a8.png)
DBシステム・データベースへの接続はここまで完了です。

# 3. Autonomous DBへの接続方法
インターネット、或いはプライベート・エンドポイントのアクセスで、既存の「Autonomous DB」に接続できます。この例ではパブリックの「Autonomous DB」を使用していますので、プライベート・エンドポイントの設定をスキップします。

__Autonomous DBへの接続を作成__
メニュー → 開発者サービス → データベース・ツール → 接続 → 接続の作成

|項目|コメント|
|:--|:--|
| データベースの選択|デフォルト|
| データベース・タイプ|"Autonomous Database"を選択する。<br>（「データベースの選択」を指定した場合、利用可能。）|
|ユーザー名|この例では「admin」を使用する。（他の既存のユーザーも使用できる）。|
|ユーザー・パスワード・シークレット|「パスワード・シークレットの作成」ボタンをクリックし、新規作成する。|

<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1121622/c61fc839-142d-6a7f-62e5-5bff6a51d21a.png" width="550">

必要な情報を入力し、「作成」ボタンをクリックしてください。
この例では「admin」ユーザーを使用しているため、「ユーザー・パスワード」はDB管理者のパスワードです。
<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1121622/b21ec827-4134-11b2-801c-1df7dfcda27e.png" width="450">

パスワード・シークレットを作成した後、前の画面に戻ります。「接続文字列」は自動的に作成されますので、通常なら編集する必要はなく、「次へ」をクリックし続行します。（この例では、プライベート・エンドポイントの設定をスキップします。必要に応じて設定してください。）

※接続文字列は、ファイル <strong>tnsnames.ora</strong>（圧縮されたウォレット・ファイルにある）から同じ内容を取得できます。
<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1121622/c4e3200a-ee4a-0fdd-981a-f8ab34d887da.png" width="550">

ウォレット・フォーマットは「SSO Wallet」を選択し、「Create Wallet Content Secret」ボタンをクリックします。
<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1121622/fb007904-c1cd-ef61-e896-8ca4dd999042.png" width="450">

必要な情報を入力し、次の3つのオプションからウォレット・ファイルの取得方法を選択します。

|オプション|コメント|
|:--|:--|
|Autonomous Databaseからの<strong>リージョナル</strong>自動ログイン・ウォレットの取得|<strong>Shared</strong> Autonomous DB、かつCross-Region Data Guardを<strong>使用しない</strong>場合、利用可能。(この例)|
|Autonomous Databaseからの<strong>インスタンス</strong>自動ログイン・ウォレットの取得|以下のいずれの場合、利用可能。<br><strong>Dedicated</strong> Autonomous DBの場合<br><strong>Shared</strong> Autonomous DB、かつCross-Region Data Guardを<strong>使用している</strong>場合|
|自動ログイン・ウォレットの<strong>アップロード</strong>|いつでも利用可能|

この例では一番目のオプション（デフォルト）を選択します。以下のように「作成」ボタンをクリックして続行します。
<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1121622/9d78809e-5835-69f3-70a0-80edc272e9b5.png" width="450">

"SSO Wallet Content Secret"の準備ができましたら、「作成」ボタンをクリックし接続を作成します。
<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1121622/fcfc6aa6-d480-98f8-521e-86ae251217df.png" width="550">

まもなく接続は、アクティブの状態になります。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1121622/5f14c616-3585-1cd1-b1b4-efe5d0aba04f.png)
SQLワークシートを起動し、SQLコマンドを実行します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1121622/720eecea-4764-dd46-a6e4-8691d557a961.png)
SQLclを起動し、SQLコマンドを実行します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1121622/68d0913c-d03e-ccfc-b867-591d6df4e52a.png)

 「<font color=blue>自動ログイン・ウォレットのアップロード</font>」オプションを使用したい場合は、最初にウォレット・ファイルをダウンロードする必要があります。
__ウォレット・ファイルのダウンロード__
メニュー → Oracle Database → Autonomous Database → Autonomous Databaseの詳細 → DB接続 → ウォレットのダウンロード
<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1121622/590ce94f-09d7-2c15-2408-ec41b486ad8b.png">
ウォレットのパスワードを作成し、「ダウンロード」ボタンをクリックします。 （これは、Autonomous DBの管理者ユーザのパスワードではありません。）
<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1121622/e84f5990-85e8-d7b4-1747-4e1cb7304f90.png" width="400">
圧縮ファイルを保存してから<strong>解凍</strong>します。
<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1121622/07916051-dc57-3311-7ccc-29e41fbecb2c.png" width="400">
解凍後、ウォレット・ファイル <strong>cwallet.sso</strong> は、以下のようです。
<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1121622/d86d8447-203e-eef7-38de-06e0a7848733.png" width="550">
ファイル <strong>cwallet.sso</strong> をアップロードし、「作成」ボタンをクリックします。
<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1121622/1029fe5e-9089-5651-483b-6cd28bdd39fa.png" width="400">
「作成」ボタンをクリックして接続を作成します。上記の方法と同じです。
<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1121622/6d6caf7c-c59e-9415-d7b1-faf02b7f36bb.png" width="450">

ここまで、Autonomous DBへの接続は完了です。SQLコマンドの実行は、SQLワークシートまたはSQLclプロンプトの両方からできます。プライベート・エンドポイントを使用する場合、SQLclを起動する時に要塞は必要です。これは、DBシステム・データベースに接続する場合と同様です。

データベース・ツールをうまく利用するため、いくつかのベスト・プラクティスがあります。詳細については、[ドキュメント](https://docs.oracle.com/ja-jp/iaas/Content/Database-Tools/dbtools_topic-best_practices.htm)をご確認ください。

以上

----
__関連記事__
[オラクル・クラウドの個人ブログ一覧](https://qiita.com/liu-wei/items/10152a4fec813c1b7d98)
[SQL Developerで各種なDBへの接続方法](https://qiita.com/liu-wei/items/08f2e2f6d90c08549cbf)
[OCI Cloud Shell上のSQL PlusからADBに接続する](https://qiita.com/liu-wei/items/38b968cee3a9619c63e5)
[OCI Bastion経由でプライベート・サブネット内のOracle DBに接続](https://qiita.com/liu-wei/items/36f2108992ce71d7bafc)
[OCI Bastion経由でプライベート・サブネット内のAutonomous DBに接続](https://qiita.com/liu-wei/items/36dc12c95d3bc72e16db)