# 機能設計書 631-Get-DbaBinaryFileTable

## 概要

本ドキュメントは、dbatools PowerShellモジュールのGet-DbaBinaryFileTableコマンドレットの機能設計書である。このコマンドは、SQL Serverデータベース内のバイナリデータを含むテーブルを識別し、ファイル抽出操作のための情報を提供する。

### 本機能の処理概要

Get-DbaBinaryFileTableは、データベーステーブルをスキャンし、バイナリデータ列（binary、varbinary、image）を含むテーブルを特定する。さらに、ファイル名を格納している可能性のある列を自動的に識別し、ファイル抽出ワークフローを支援する。

**業務上の目的・背景**：レガシーアプリケーションでは、ファイルをファイルシステムではなくデータベース内にBLOBとして格納することが一般的であった。このコマンドは、そのようなデータベースからファイルを抽出する必要がある場合に、どのテーブルにバイナリデータが含まれているか、ファイル名がどのように格納されているかを迅速に特定できるようにする。データベース移行、バックアップ、監査の際に、バイナリコンテンツの所在を把握するために使用される。

**機能の利用シーン**：
- レガシーシステムからのファイル抽出プロジェクト
- データベース内のバイナリコンテンツ監査
- データベース移行前のバイナリデータ所在確認
- Export-DbaBinaryFileコマンドと連携したファイルエクスポート処理

**主要な処理内容**：
1. 指定されたSQL Serverインスタンスに接続し、対象データベースのテーブル一覧を取得
2. 各テーブルの列情報を解析し、バイナリ型（binary、varbinary、image）の列を特定
3. 列名に「Name」を含む列をファイル名列として自動識別
4. BinaryColumnとFileNameColumnプロパティをテーブルオブジェクトに追加して出力

**関連システム・外部連携**：Export-DbaBinaryFile、Import-DbaBinaryFileコマンドと連携し、パイプライン経由でファイル抽出ワークフローを構築可能

**権限による制御**：対象データベースへの読み取りアクセス権限が必要。SQLCredentialパラメータによりSQL Server認証、Windows認証、Active Directory認証をサポート

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | コマンドライン/PowerShellコンソール | 主画面 | コマンド実行およびパイプライン処理 |

## 機能種別

データ取得（SELECT）/ テーブル解析

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | No | 対象SQL Serverインスタンス。複数指定可、パイプライン入力対応 | なし |
| SqlCredential | PSCredential | No | 代替認証情報（Get-Credential形式） | Windows認証、SQL認証、AD認証対応 |
| Database | string[] | No | スキャン対象データベース。ワイルドカード対応 | なし |
| Table | string[] | No | 対象テーブル。3パート名とワイルドカード対応 | 特殊文字は角括弧でエスケープ |
| Schema | string[] | No | 対象スキーマ。複数指定、ワイルドカード対応 | なし |
| InputObject | Microsoft.SqlServer.Management.Smo.Table[] | No | Get-DbaDbTableからパイプライン入力 | SMO Tableオブジェクト |
| EnableException | switch | No | 例外を有効にして詳細なエラー情報を取得 | なし |

### 入力データソース

- SqlInstance指定時：Get-DbaDbTableを内部呼び出しでテーブル一覧を取得
- InputObject指定時：パイプラインから受け取ったTableオブジェクトを直接処理

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | String | SQL Serverインスタンスのコンピュータ名 |
| InstanceName | String | SQL Serverインスタンス名 |
| SqlInstance | String | 完全なSQL Serverインスタンス名（computer\instance） |
| Database | String | テーブルを含むデータベース名 |
| Schema | String | テーブルを含むスキーマ名 |
| Name | String | テーブル名 |
| BinaryColumn | String/String[] | バイナリデータを含む列名（複数可） |
| FileNameColumn | String | ファイル名を格納している列名（複数マッチ時は空） |

### 出力先

PowerShellパイプライン（Microsoft.SqlServer.Management.Smo.Tableオブジェクト拡張版）

## 処理フロー

### 処理シーケンス

```
1. パラメータ検証とインスタンス接続
   └─ Test-FunctionInterruptで中断チェック

2. テーブルオブジェクト取得
   └─ InputObjectがない場合、Get-DbaDbTableを呼び出し
   └─ SqlInstance、Database、Table、Schema、SqlCredentialを渡す

3. テーブルごとの処理ループ
   └─ 各テーブルの列情報を解析

4. バイナリ列の特定
   └─ DataType.Nameが"binary"にマッチまたは"image"と等しい列を抽出

5. ファイル名列の特定
   └─ 列名に"Name"を含む列を抽出
   └─ 複数マッチ時は警告メッセージを出力

6. プロパティ追加と出力
   └─ BinaryColumnとFileNameColumnをNotePropertyとして追加
   └─ Select-DefaultViewで既定プロパティを設定して出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{InputObject指定?}
    B -->|No| C[Get-DbaDbTable呼び出し]
    B -->|Yes| D[InputObjectを使用]
    C --> D
    D --> E{テーブルあり?}
    E -->|No| F[終了]
    E -->|Yes| G[テーブルループ開始]
    G --> H[バイナリ列を抽出]
    H --> I[ファイル名列を抽出]
    I --> J{複数ファイル名列?}
    J -->|Yes| K[警告メッセージ出力]
    J -->|No| L{バイナリ列あり?}
    K --> L
    L -->|No| M[次のテーブルへ]
    L -->|Yes| N[プロパティ追加]
    N --> O[結果出力]
    O --> M
    M --> P{次のテーブル?}
    P -->|Yes| G
    P -->|No| F
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | バイナリ型判定 | binary、varbinary、imageデータ型をバイナリ列として認識 | 全テーブルのスキャン時 |
| BR-002 | ファイル名列自動検出 | 列名に"Name"を含む列をファイル名列として認識 | 全テーブルのスキャン時 |
| BR-003 | 複数マッチ時の警告 | ファイル名列が複数マッチした場合は警告を出力し、FileNameColumnは空 | 複数マッチ時 |
| BR-004 | バイナリ列なしスキップ | バイナリ列を含まないテーブルは出力しない | 全テーブルの処理時 |

### 計算ロジック

バイナリ列判定ロジック：
```powershell
$tbl.Columns | Where-Object { $_.DataType.Name -match "binary" -or $_.DataType.Name -eq "image" }
```

ファイル名列判定ロジック：
```powershell
$tbl.Columns | Where-Object Name -Match "Name"
```

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| テーブル一覧取得 | sys.tables（内部） | SELECT | Get-DbaDbTableがメタデータ取得 |
| 列情報取得 | sys.columns（内部） | SELECT | SMOを通じて列情報を取得 |

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

#### sys.tables / sys.columns（SMO経由）

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | name, type_desc | データベース内の全テーブル | SMO Tableオブジェクトを通じて取得 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ConnectionError | SQL Serverへの接続失敗 | Stop-Functionで処理中断、エラーメッセージ出力 |
| - | TableRetrievalError | テーブル取得失敗 | Stop-Functionで処理中断 |

### リトライ仕様

リトライ機能なし。接続エラー時は処理を中断する。

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

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

## パフォーマンス要件

- 大規模データベースでは多数のテーブルをスキャンするため、処理時間が増加する可能性あり
- TableやSchemaパラメータで対象を絞り込むことで性能改善可能

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

- SqlCredentialパラメータでSQL認証、Windows認証、AD認証をサポート
- MFA対応の場合はConnect-DbaInstanceを事前に使用することを推奨
- データベースへの読み取りアクセス権限のみで動作

## 備考

- Export-DbaBinaryFile、Import-DbaBinaryFileとのパイプライン連携が主要ユースケース
- Out-GridView -Passthruとの組み合わせで対話的なテーブル選択が可能
- ファイル名列の自動検出は「Name」というパターンに依存するため、カスタム列名の場合は手動指定が必要

---

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

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

### 推奨読解順序

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

SMO Tableオブジェクトの構造とプロパティを理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaBinaryFileTable.ps1 | `public/Get-DbaBinaryFileTable.ps1` | 出力オブジェクトの構造（BinaryColumn、FileNameColumnプロパティの追加） |

**読解のコツ**: Add-Memberを使用してSMO TableオブジェクトにNotePropertyを追加している。Select-DefaultViewで出力プロパティを制限している。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaBinaryFileTable.ps1 | `public/Get-DbaBinaryFileTable.ps1` | processブロックがエントリーポイント |

**主要処理フロー**:
1. **106行目**: Test-FunctionInterruptで中断チェック
2. **108-115行目**: InputObjectがない場合にGet-DbaDbTableを呼び出し
3. **118-132行目**: 各テーブルのバイナリ列とファイル名列を特定

#### Step 3: バイナリ列検出ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaBinaryFileTable.ps1 | `public/Get-DbaBinaryFileTable.ps1` | 120行目のWhere-Object条件 |

**主要処理フロー**:
- **120行目**: DataType.Nameが"binary"にマッチまたは"image"と等しい列をフィルタリング
- **121行目**: 列名に"Name"を含む列をファイル名列として抽出

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

```
Get-DbaBinaryFileTable
    │
    ├─ Test-FunctionInterrupt
    │      └─ 中断状態チェック
    │
    ├─ Get-DbaDbTable（InputObjectがない場合）
    │      ├─ Connect-DbaInstance
    │      └─ SMO経由でテーブル取得
    │
    ├─ Write-Message
    │      └─ 詳細ログ出力
    │
    └─ Select-DefaultView
           └─ 出力プロパティフィルタリング
```

### データフロー図

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

SqlInstance/Database  ───▶ Get-DbaDbTable
                                 │
                                 ▼
Table[]               ───▶ 列解析（バイナリ/ファイル名）
                                 │
                                 ▼
                           プロパティ追加              ───▶ Table + BinaryColumn
                           (Add-Member)                     + FileNameColumn
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaBinaryFileTable.ps1 | `public/Get-DbaBinaryFileTable.ps1` | ソース | メイン処理ロジック |
| Get-DbaDbTable.ps1 | `public/Get-DbaDbTable.ps1` | ソース | テーブル一覧取得の内部依存 |
| Export-DbaBinaryFile.ps1 | `public/Export-DbaBinaryFile.ps1` | ソース | 連携先コマンド（ファイルエクスポート） |
| Import-DbaBinaryFile.ps1 | `public/Import-DbaBinaryFile.ps1` | ソース | 連携先コマンド（ファイルインポート） |
