# 帳票設計書 19-Export-DbaBinaryFile

## 概要

本ドキュメントは、dbatools PowerShellモジュールの `Export-DbaBinaryFile` コマンドに関する帳票設計書です。このコマンドは、SQLテーブルからバイナリデータを抽出しファイルとして書き出す機能を提供します。

### 本帳票の処理概要

Export-DbaBinaryFileは、SQL Serverテーブル内に格納されたバイナリデータ（画像、ドキュメント、その他のファイル）を取得し、ファイルシステム上の物理ファイルとして出力するコマンドです。binary、varbinary、imageデータ型のカラムからデータをストリーミングで効率的に抽出します。

**業務上の目的・背景**：レガシーアプリケーションでは、ドキュメントや画像をデータベース内のBLOBカラムに格納することが一般的でした。システム移行、ファイルストレージへの移行、データアーカイブ、外部システムとの連携において、これらのバイナリデータをファイルとして抽出する必要があります。本コマンドにより、大量のバイナリデータを効率的にファイル化できます。

**帳票の利用シーン**：
- データベース内の画像/ドキュメントのファイルシステムへの移行
- BLOBデータのバックアップ/アーカイブ
- レポートやWebサイト用のアセット抽出
- データベースサイズ削減のためのファイル外部化準備
- レガシーシステムからの移行データ抽出

**主要な出力内容**：
1. バイナリファイル（元のファイル形式で出力）
2. FileInfo オブジェクト（出力ファイル情報）

**帳票の出力タイミング**：PowerShellコンソールまたはスクリプトからコマンド実行時に即座に出力されます。

**帳票の利用者**：データベース管理者（DBA）、アプリケーション開発者、データ移行エンジニア

## 帳票種別

バイナリファイル（データベースに格納された元のファイル形式）

## 利用画面

| 画面No | 画面名 | URL/ルーティング | 出力操作 |
|--------|--------|-----------------|---------|
| N/A | PowerShellコンソール | コマンドライン | Export-DbaBinaryFile コマンド実行 |

## 出力形式

### 基本仕様

| 項目 | 内容 |
|-----|------|
| ファイル形式 | データベースに格納されたバイナリデータの元形式 |
| 用紙サイズ | N/A（バイナリファイル） |
| 向き | N/A |
| ファイル名 | FileNameColumn値 または FilePath指定値 |
| 出力方法 | ファイル保存 |
| 文字コード | バイナリ |

### ファイル固有設定

| 項目 | 内容 |
|-----|------|
| バッファサイズ | 8192バイト |
| ストリーミング | GetBytes()メソッドで逐次読み込み |
| 上書き | 既存ファイルを上書き |

## 帳票レイアウト

### レイアウト概要

バイナリファイルとして直接出力されるため、構造化されたレイアウトはありません。

```
┌─────────────────────────────────────┐
│      データベーステーブル            │
│   ┌───────────────────────────────┐ │
│   │   FileNameColumn  │ BinaryCol │ │
│   │   document.pdf    │ (BLOB)    │ │
│   │   image.jpg       │ (BLOB)    │ │
│   └───────────────────────────────┘ │
│                 ↓                   │
│      ファイルシステム               │
│   ┌───────────────────────────────┐ │
│   │   Path/document.pdf           │ │
│   │   Path/image.jpg              │ │
│   └───────────────────────────────┘ │
└─────────────────────────────────────┘
```

### コマンド出力オブジェクト

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | FullName | 出力ファイルのフルパス | Get-ChildItem | 文字列 |
| 2 | Name | ファイル名 | Get-ChildItem | 文字列 |
| 3 | DirectoryName | 出力ディレクトリ | Get-ChildItem | 文字列 |
| 4 | Length | ファイルサイズ（バイト） | Get-ChildItem | 数値 |
| 5 | CreationTime | 作成日時 | Get-ChildItem | DateTime |

## 出力条件

### 抽出条件

| 条件名 | 説明 | 必須 |
|-------|------|-----|
| SqlInstance | 対象SQL Serverインスタンス | Yes（InputObjectがない場合） |
| Database | 対象データベース | No |
| Table | 対象テーブル | No |
| Schema | 対象スキーマ | No |
| Query | カスタムクエリ | No |
| Path または FilePath | 出力先 | Yes（いずれか必須） |
| FileNameColumn | ファイル名カラム | No（自動検出） |
| BinaryColumn | バイナリカラム | No（自動検出） |

### ソート順

| 優先度 | 項目 | 昇順/降順 |
|-------|------|---------|
| 1 | クエリ結果順 | 取得順 |

### 改ページ条件

N/A（バイナリファイル出力のため）

## データベース参照仕様

### 参照テーブル一覧

| テーブル名 | 用途 | 結合条件 |
|-----------|------|---------|
| ユーザー指定テーブル | バイナリデータ格納元 | Table パラメータ |
| sys.columns | カラム自動検出 | SMO経由 |

### テーブル別参照項目詳細

#### ユーザー指定テーブル

| 参照項目（カラム名） | 帳票項目との対応 | 取得条件 | 備考 |
|-------------------|----------------|---------|------|
| FileNameColumn | 出力ファイル名 | name含むカラム | 自動検出可能 |
| BinaryColumn | バイナリデータ | binary/varbinary/image型 | 自動検出可能 |

## 計算仕様

### 計算項目一覧

| 項目名 | 計算式 | 端数処理 | 備考 |
|-------|-------|---------|------|
| N/A | 計算処理なし | - | バイナリストリーム転送のみ |

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[Export-DbaBinaryFile実行] --> B{Path/FilePath検証}
    B -->|両方指定| C[エラー終了]
    B -->|どちらもなし| D[エラー終了]
    B -->|有効| E{Path存在確認}
    E -->|No| F[ディレクトリ作成]
    E -->|Yes| G[Get-DbaDbTable]
    F --> G
    G --> H{テーブル取得成功?}
    H -->|No| I[エラー終了]
    H -->|Yes| J[ループ: 各テーブル]
    J --> K{FileNameColumn自動検出}
    K -->|失敗| L[エラー（複数/なし）]
    K -->|成功| M{BinaryColumn自動検出}
    M -->|失敗| N[エラー（複数/なし）]
    M -->|成功| O[SELECTクエリ構築]
    O --> P[ExecuteReader]
    P --> Q[ループ: 各行]
    Q --> R[FileStream作成]
    R --> S[BinaryWriter初期化]
    S --> T[GetBytesでストリーム読み込み]
    T --> U[ファイル書き込み]
    U --> V[ストリームClose]
    V --> W[Get-ChildItem]
    W --> X{次行?}
    X -->|Yes| Q
    X -->|No| Y{次テーブル?}
    Y -->|Yes| J
    Y -->|No| Z[終了]
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| パラメータエラー | Path/FilePath両方指定 | "You cannot specify both -Path and -FilePath" | いずれか1つのみ指定 |
| パラメータエラー | Path/FilePath両方なし | "You must specify either -Path or -FilePath" | いずれか1つを指定 |
| カラム検出エラー | 複数nameカラム | "Multiple column names match the phrase 'name'..." | -FileNameColumn指定 |
| カラム検出エラー | nameカラムなし | "No column names match the phrase 'name'..." | -FileNameColumn指定 |
| カラム検出エラー | 複数バイナリカラム | "Multiple columns have a binary datatype..." | -BinaryColumn指定 |
| カラム検出エラー | バイナリカラムなし | "No columns have a binary datatype..." | -BinaryColumn指定 |
| エクスポートエラー | 書き込み失敗 | "Failed to export binary file from..." | 権限・パス確認 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定データ件数 | 1〜10000ファイル |
| 目標出力時間 | ファイルサイズに依存 |
| 同時出力数上限 | 制限なし（シーケンシャル処理） |
| バッファサイズ | 8192バイト |

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

- データベースへのSELECT権限が必要
- 出力先ディレクトリへの書き込み権限が必要
- バイナリデータには機密情報が含まれる可能性
- ShouldProcess対応（-WhatIf、-Confirm）

## 備考

- カラム自動検出機能（FileNameColumn: "name"を含む、BinaryColumn: binary/image型）
- Queryパラメータでカスタムクエリ使用可能
- 大容量ファイルもストリーミングで効率的に処理
- Get-DbaBinaryFileTableと組み合わせて対象テーブル選択可能

---

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

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

### 推奨読解順序

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

バイナリストリーミングとカラム自動検出の仕組みを理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Export-DbaBinaryFile.ps1 | `public/Export-DbaBinaryFile.ps1` | パラメータ定義（行127-143）でPath, FilePath, FileNameColumn等を確認 |

**読解のコツ**: ExecuteReader + GetBytesによるストリーミング読み込みを理解する

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Export-DbaBinaryFile.ps1 | `public/Export-DbaBinaryFile.ps1` | beginブロック（行144-158） |
| 2-2 | Export-DbaBinaryFile.ps1 | `public/Export-DbaBinaryFile.ps1` | processブロック（行159-263） |

**主要処理フロー**:
1. **行144-157**: パラメータ検証、ディレクトリ作成
2. **行161-168**: Get-DbaDbTableでテーブル取得
3. **行180-198**: FileNameColumn/BinaryColumn自動検出
4. **行202-205**: SELECTクエリ構築

#### Step 3: バイナリ書き込み処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Export-DbaBinaryFile.ps1 | `public/Export-DbaBinaryFile.ps1` | 書き込み処理（行210-247） |

**主要処理フロー**:
- **行201-202**: バッファサイズ定義（8192バイト）
- **行212**: ExecuteReaderでクエリ実行
- **行215**: バイトアレイ初期化
- **行218-221**: ファイルパス決定
- **行225-226**: FileStream/BinaryWriter初期化
- **行230-236**: GetBytesでストリーム読み込みループ
- **行239-242**: ストリームClose

#### Step 4: エラー処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Export-DbaBinaryFile.ps1 | `public/Export-DbaBinaryFile.ps1` | finally/catch（行248-262） |

**主要処理フロー**:
- **行248-262**: ストリームのクリーンアップ
- **行251-257**: リソース解放確認

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

```
Export-DbaBinaryFile
    │
    ├─ パラメータ検証 (begin)
    │      └─ Path/FilePath排他チェック
    │
    ├─ New-Item
    │      └─ 出力ディレクトリ作成
    │
    ├─ Get-DbaDbTable
    │      └─ テーブルオブジェクト取得
    │
    ├─ カラム自動検出
    │      ├─ FileNameColumn（name含む）
    │      └─ BinaryColumn（binary/image型）
    │
    ├─ ExecuteReader
    │      └─ SELECTクエリ実行
    │
    ├─ GetBytes
    │      └─ バイナリデータストリーム
    │
    ├─ FileStream/BinaryWriter
    │      └─ ファイル書き込み
    │
    └─ Get-ChildItem
           └─ FileInfo返却
```

### データフロー図

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

SqlInstance ───────▶ Get-DbaDbTable ─────────────▶ Table Objects
                            │
Table/Schema ──────▶ Filter Tables ──────────────▶ Target Tables
                            │
                            ▼
                     Column Detection ───────────▶ FileName + Binary Cols
                            │
                            ▼
Query ─────────────▶ ExecuteReader ──────────────▶ DataReader
                            │
                            ▼
                     GetBytes Loop ──────────────▶ Byte Array
                            │
                            ▼
Path/FilePath ─────▶ FileStream Write ───────────▶ Binary File
                            │
                            ▼
                     Get-ChildItem ──────────────▶ FileInfo Object
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Export-DbaBinaryFile.ps1 | `public/Export-DbaBinaryFile.ps1` | ソース | メイン処理 |
| Export-DbaBinaryFile.Tests.ps1 | `tests/Export-DbaBinaryFile.Tests.ps1` | テスト | 単体テスト |
| Get-DbaDbTable.ps1 | `public/Get-DbaDbTable.ps1` | ソース | テーブル取得 |
| Get-DbaBinaryFileTable.ps1 | `public/Get-DbaBinaryFileTable.ps1` | ソース | バイナリテーブル検索 |
