# 機能設計書 104-Get-DbaDbForeignKey

## 概要

本ドキュメントは、SQL Serverデータベーステーブルの外部キー制約を取得するGet-DbaDbForeignKey機能の設計仕様を定義する。

### 本機能の処理概要

本機能は、指定されたSQL Serverデータベース内のテーブルから外部キー制約の定義情報を取得する。参照整合性の文書化、移行前のテーブル依存関係分析、カスケード操作のトラブルシューティングなどに活用される。

**業務上の目的・背景**：データベースの参照整合性を理解することは、データモデリング、移行計画、パフォーマンスチューニングにおいて不可欠である。外部キー制約は、テーブル間の依存関係を定義し、データの整合性を保証する重要な要素である。本機能により、外部キー情報を体系的に収集・分析できる。

**機能の利用シーン**：
- データベーススキーマのドキュメント化
- テーブル依存関係の可視化
- 移行・リファクタリング前の影響分析
- カスケード削除/更新の動作確認
- 外部キー制約の有効/無効状態の監査

**主要な処理内容**：
1. SQL Serverインスタンスへの接続確立
2. アクセス可能なデータベースのフィルタリング
3. 各データベース内のテーブルをイテレーション
4. テーブルごとの外部キーコレクション取得
5. SMO ForeignKeyオブジェクトにカスタムプロパティを追加して出力

**関連システム・外部連携**：SMO（SQL Server Management Objects）を使用してForeignKeyオブジェクトを取得。

**権限による制御**：対象データベースへのVIEW DEFINITION権限が必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 47 | 外部キー・制約 | 主画面 | 外部キーの取得 |

## 機能種別

データ取得処理（メタデータ取得）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象のSQL Serverインスタンス | パイプライン入力対応、Mandatory |
| SqlCredential | PSCredential | No | 代替認証情報 | Windows/SQL認証、AD統合認証 |
| Database | object[] | No | 対象データベース名 | 存在するデータベース名 |
| ExcludeDatabase | object[] | No | 除外するデータベース名 | 存在するデータベース名 |
| ExcludeSystemTable | switch | No | システムテーブルを除外 | - |
| EnableException | switch | No | 例外処理モードの切り替え | - |

### 入力データソース

- SqlInstance: コマンドラインパラメータまたはパイプライン入力
- Database/ExcludeDatabase: コマンドラインパラメータ

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverをホストするコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なSQL Serverインスタンス名 |
| Database | string | データベース名 |
| Schema | string | テーブルのスキーマ名 |
| Table | string | 外部キーを持つテーブル名（参照元テーブル） |
| ID | int | 外部キー制約の一意識別子 |
| CreateDate | DateTime | 外部キー制約の作成日時 |
| DateLastModified | DateTime | 外部キー制約の最終更新日時 |
| Name | string | 外部キー制約名 |
| IsEnabled | bool | 制約が有効かどうか |
| IsChecked | bool | INSERT/UPDATE時に制約が強制されるか |
| NotForReplication | bool | レプリケーション操作に適用されるか |
| ReferencedKey | string | 参照される主キー/一意キー名 |
| ReferencedTable | string | 参照先テーブル名 |
| ReferencedTableSchema | string | 参照先テーブルのスキーマ名 |

### 出力先

PowerShellパイプライン（Microsoft.SqlServer.Management.Smo.ForeignKey）

## 処理フロー

### 処理シーケンス

```
1. インスタンスごとの処理ループ
   └─ Connect-DbaInstanceで接続確立
2. データベースのフィルタリング
   └─ IsAccessibleなDBのみ対象
   └─ Database/ExcludeDatabaseパラメータ適用
3. データベースごとのテーブルループ
   └─ ExcludeSystemTableの判定
4. テーブルごとの外部キーループ
   └─ カスタムプロパティの追加（Add-Member）
   └─ Select-DefaultViewで出力形式指定
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{インスタンスループ}
    B -->|次のインスタンス| C[Connect-DbaInstance]
    C --> D{接続成功?}
    D -->|No| E[エラー出力]
    E --> B
    D -->|Yes| F[DBフィルタリング]
    F --> G{データベースループ}
    G -->|次のDB| H{IsAccessible?}
    H -->|No| I[警告出力]
    I --> G
    H -->|Yes| J{テーブルループ}
    J -->|次のテーブル| K{システムテーブル除外?}
    K -->|除外| J
    K -->|対象| L{FKあり?}
    L -->|なし| M[Verbose出力]
    M --> J
    L -->|あり| N{外部キーループ}
    N -->|次のFK| O[Add-Member]
    O --> P[Select-DefaultView]
    P --> N
    N -->|完了| J
    J -->|完了| G
    G -->|完了| B
    B -->|完了| Q[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-401 | アクセシビリティチェック | アクセス不可能なデータベースは警告出力してスキップ | データベースループ時 |
| BR-402 | システムテーブル除外 | ExcludeSystemTableスイッチ指定時はIsSystemObjectがtrueのテーブルをスキップ | テーブルループ時 |
| BR-403 | 外部キーなしの扱い | 外部キーが存在しない場合はVerboseメッセージを出力 | テーブル処理時 |

### 計算ロジック

特に計算ロジックはなく、SMOオブジェクトのプロパティを直接取得。

## データベース操作仕様

### 操作別データベース影響一覧

| 操作 | 対象テーブル/ビュー | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 外部キー取得 | SMO ForeignKeys | メタデータ読取 | テーブルの外部キーコレクション |

### テーブル別操作詳細

SMOを使用してメタデータを取得。内部的にはsys.foreign_keys等のカタログビューにアクセス。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ConnectionError | 接続エラー | SQL Serverへの接続失敗 | Stop-Functionで処理継続 |
| - | 警告 | データベースがアクセス不可 | スキップして次のDBを処理 |

### リトライ仕様

リトライは実装されていない。接続エラー時は次のインスタンスの処理を継続。

## トランザクション仕様

読み取り専用操作のため、トランザクション管理は不要。

## パフォーマンス要件

SMOメタデータアクセスのため、テーブル数に比例した処理時間。大規模データベースでは数秒から数十秒。

## セキュリティ考慮事項

- VIEW DEFINITION権限が必要
- SqlCredentialパラメータで代替認証情報をサポート

## 備考

関連コマンド：Get-DbaDbCheckConstraint（チェック制約の取得）、Remove-DbaDbForeignKey（外部キーの削除）

---

## コードリーディングガイド

本機能を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

出力されるForeignKeyオブジェクトの構造と追加プロパティを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaDbForeignKey.ps1 | `public/Get-DbaDbForeignKey.ps1` | 158-167行目：Add-Memberとデフォルトプロパティ定義 |

**読解のコツ**: SMOのForeignKeyオブジェクトにAdd-Memberで動的にComputerName等のプロパティを追加している。Select-DefaultViewでデフォルト表示プロパティを制御。

#### Step 2: エントリーポイントを理解する

パラメータ定義と3重ネストのループ構造を確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaDbForeignKey.ps1 | `public/Get-DbaDbForeignKey.ps1` | 113-122行目：パラメータ定義 |

**主要処理フロー**:
1. **125-130行目**: インスタンスへの接続
2. **132-139行目**: データベースフィルタリング
3. **141-145行目**: アクセシビリティチェック
4. **147-155行目**: テーブルループとシステムテーブル除外
5. **157-168行目**: 外部キーループと出力

#### Step 3: フィルタリングロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaDbForeignKey.ps1 | `public/Get-DbaDbForeignKey.ps1` | 132-139行目：Database/ExcludeDatabaseフィルタ |
| 3-2 | Get-DbaDbForeignKey.ps1 | `public/Get-DbaDbForeignKey.ps1` | 148-150行目：システムテーブル除外 |

**主要処理フロー**:
- **132行目**: IsAccessibleでアクセス可能なDBのみ
- **134-138行目**: Database/ExcludeDatabaseパラメータによるフィルタ
- **148-150行目**: Test-BoundでExcludeSystemTableの有無を確認

### プログラム呼び出し階層図

```
Get-DbaDbForeignKey
    │
    ├─ Connect-DbaInstance
    │
    ├─ Write-Message（ログ/警告出力）
    │
    ├─ Stop-Function（エラー処理）
    │
    ├─ Test-Bound（パラメータ存在確認）
    │
    ├─ Add-Member（プロパティ追加）
    │
    └─ Select-DefaultView（出力形式制御）
```

### データフロー図

```
[入力]               [処理]                         [出力]

SqlInstance ───▶ Connect-DbaInstance
                      │
                      ▼
               ┌─────────────────┐
Database ────▶ │ DBフィルタリング │
               └────────┬────────┘
                        │
                        ▼
               ┌─────────────────┐
               │ テーブルループ  │
               └────────┬────────┘
                        │
                        ▼
               ┌─────────────────┐
               │ FKループ        │
               └────────┬────────┘
                        │
                        ▼
               ┌─────────────────┐      ┌─ ComputerName
               │ ForeignKey      │──────┼─ Database
               │ オブジェクト    │      ├─ Schema
               └─────────────────┘      ├─ Table
                                        ├─ Name
                                        ├─ IsEnabled
                                        ├─ ReferencedTable
                                        └─ ReferencedTableSchema
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaDbForeignKey.ps1 | `public/Get-DbaDbForeignKey.ps1` | ソース | メイン処理 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続 |
| Select-DefaultView.ps1 | `internal/functions/Select-DefaultView.ps1` | ソース | 出力形式制御 |
