# 画面設計書 41-テーブル管理

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおけるテーブル管理機能群の設計仕様を記述する。SQL Serverデータベース内のテーブルオブジェクトに対する取得・作成・削除・データ操作を行うコマンドレット群を対象とする。

### 本画面の処理概要

テーブル管理機能は、SQL Serverデータベース内のテーブルに対するライフサイクル全体の管理操作を提供する。テーブルのメタデータ取得から、新規作成、削除、そしてテーブル内データの高速コピー・エクスポート・インポート・削除まで、包括的なテーブル操作を実現する。

**業務上の目的・背景**：データベース管理者（DBA）は日常的にテーブルの状態確認、容量計画、データ移行、データクレンジングなどの業務を行う。従来これらの作業はSSMS（SQL Server Management Studio）やT-SQLスクリプトで個別に実施していたが、本機能群によりPowerShellから一貫した方法で自動化・スクリプト化が可能となる。特に複数インスタンス・複数データベースにまたがる操作を効率化し、運用作業の標準化とヒューマンエラーの削減に寄与する。

**画面へのアクセス方法**：PowerShellコンソールまたはスクリプトから各コマンドレットを直接呼び出す。CLIベースのツールであるため、GUI画面は存在しない。`Connect-DbaInstance`で接続を確立後、各コマンドを実行する。

**主要な操作・処理内容**：
1. `Get-DbaDbTable` - データベース内のテーブル一覧とメタデータ（行数、空間使用量、パーティション状態等）を取得
2. `New-DbaDbTable` - PowerShellハッシュテーブルまたはSMOオブジェクトによる新規テーブル作成
3. `Remove-DbaDbTable` - テーブルの削除（確認プロンプト付き）
4. `Copy-DbaDbTableData` - SqlBulkCopyによる高速データコピー（インスタンス間・データベース間対応）
5. `Export-DbaDbTableData` - テーブルデータをINSERT文としてエクスポート
6. `Write-DbaDbTableData` - 各種データソース（CSV、DataTable等）からのバルクインサート
7. `Remove-DbaDbTableData` - トランザクションログ肥大化を防ぐバッチ削除

**画面遷移**：CLIコマンドのため画面遷移はないが、パイプライン接続により`Get-DbaDatabase`→`Get-DbaDbTable`→`Copy-DbaDbTableData`等の連携が可能。

**権限による表示制御**：SQL Server側の権限に依存。テーブル取得にはdb_datareaderまたはVIEW DEFINITION権限、作成にはCREATE TABLE権限、削除にはALTER権限またはdb_ddladmin、データ操作には各テーブルへのINSERT/DELETE権限が必要。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 670 | Get-DbaDbTable | 主機能 | テーブルの取得 |
| 671 | New-DbaDbTable | 主機能 | テーブルの作成 |
| 672 | Remove-DbaDbTable | 主機能 | テーブルの削除 |
| 667 | Copy-DbaDbTableData | 補助機能 | テーブルデータのコピー |
| 668 | Export-DbaDbTableData | 補助機能 | テーブルデータのエクスポート |
| 673 | Remove-DbaDbTableData | 補助機能 | テーブルデータの削除 |
| 674 | Write-DbaDbTableData | 補助機能 | テーブルへのデータ書き込み |

## 画面種別

CLI（コマンドラインインターフェース）- 一覧取得・登録・編集・削除の複合機能

## URL/ルーティング

PowerShellコマンドレット呼び出し（CLIのためURL/ルーティングなし）
- `Get-DbaDbTable`
- `New-DbaDbTable`
- `Remove-DbaDbTable`
- `Copy-DbaDbTableData`
- `Export-DbaDbTableData`
- `Write-DbaDbTableData`
- `Remove-DbaDbTableData`

## 入出力項目

### Get-DbaDbTable 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstanceParameter[] | No | 対象SQL Serverインスタンス |
| SqlCredential | PSCredential | No | 認証情報 |
| Database | string[] | No | 対象データベース名 |
| ExcludeDatabase | string[] | No | 除外データベース名 |
| IncludeSystemDBs | switch | No | システムDBを含める |
| Table | string[] | No | 対象テーブル名（1-3部構成名対応） |
| Schema | string[] | No | 対象スキーマ名 |
| InputObject | Database[] | No | パイプライン入力 |
| EnableException | switch | No | 例外を有効化 |

### New-DbaDbTable 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstanceParameter[] | No | 対象SQL Serverインスタンス |
| SqlCredential | PSCredential | No | 認証情報 |
| Database | String[] | No | 対象データベース名 |
| Name | String | Yes* | テーブル名 |
| Schema | String | No | スキーマ名（デフォルト: dbo） |
| ColumnMap | hashtable[] | No | カラム定義ハッシュテーブル |
| ColumnObject | Column[] | No | SMOカラムオブジェクト |
| IsMemoryOptimized | switch | No | メモリ最適化テーブル |
| IsSystemVersioned | switch | No | テンポラルテーブル |
| Passthru | switch | No | スクリプト出力 |

### Copy-DbaDbTableData 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstanceParameter | No | ソースインスタンス |
| Destination | DbaInstanceParameter[] | No | 宛先インスタンス |
| Database | string | No | ソースデータベース |
| DestinationDatabase | string | No | 宛先データベース |
| Table | string[] | No | ソーステーブル |
| DestinationTable | string | No | 宛先テーブル |
| BatchSize | int | No | バッチサイズ（デフォルト: 50000） |
| AutoCreateTable | switch | No | テーブル自動作成 |
| KeepIdentity | switch | No | ID値保持 |
| Truncate | switch | No | 事前TRUNCATE |

### Write-DbaDbTableData 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstanceParameter | Yes | 対象インスタンス |
| Database | object | No | 対象データベース |
| InputObject | object | Yes | 入力データ（DataTable/CSV等） |
| Table | string | Yes | 宛先テーブル名 |
| Schema | string | No | スキーマ名（デフォルト: dbo） |
| BatchSize | int | No | バッチサイズ（デフォルト: 50000） |
| AutoCreateTable | switch | No | テーブル自動作成 |

## 表示項目

### Get-DbaDbTable 出力プロパティ

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| ComputerName | string | コンピュータ名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | 完全修飾インスタンス名 |
| Database | string | データベース名 |
| Schema | string | スキーマ名 |
| Name | string | テーブル名 |
| IndexSpaceUsed | long | インデックス使用領域(KB) |
| DataSpaceUsed | long | データ使用領域(KB) |
| RowCount | long | 行数 |
| HasClusteredIndex | bool | クラスター化インデックス有無 |
| IsPartitioned | bool | パーティション有無（SQL2005+） |
| IsMemoryOptimized | bool | メモリ最適化有無（SQL2014+） |
| IsFileTable | bool | FileTable有無（SQL2012+） |

### Copy-DbaDbTableData 出力プロパティ

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| SourceInstance | string | ソースインスタンス名 |
| SourceDatabase | string | ソースデータベース名 |
| SourceSchema | string | ソーススキーマ名 |
| SourceTable | string | ソーステーブル名 |
| DestinationInstance | string | 宛先インスタンス名 |
| DestinationDatabase | string | 宛先データベース名 |
| DestinationSchema | string | 宛先スキーマ名 |
| DestinationTable | string | 宛先テーブル名 |
| RowsCopied | long | コピー行数 |
| Elapsed | TimeSpan | 経過時間 |

## イベント仕様

### 1-Get-DbaDbTable実行

1. SqlInstanceまたはInputObjectからデータベースオブジェクトを取得
2. 各データベースのTables.ClearAndInitialize()を呼び出してSMOプロパティを一括読み込み
3. Table/Schemaパラメータによるフィルタリング
4. SQLバージョンに応じたプロパティセットでSelect-DefaultViewを適用
5. 結果オブジェクトをパイプラインに出力

### 2-New-DbaDbTable実行

1. SqlInstanceまたはInputObjectからデータベースオブジェクトを取得
2. テーブル既存チェック（存在する場合はエラー）
3. SMO Tableオブジェクト生成
4. ColumnMap/ColumnObjectからカラム定義を追加
5. スキーマが存在しない場合は自動作成
6. Passthru指定時はスクリプト出力、それ以外はテーブル作成
7. 作成されたテーブルオブジェクトを返却

### 3-Remove-DbaDbTable実行

1. SqlInstance指定時はGet-DbaDbTableでテーブルオブジェクト取得
2. InputObject指定時は直接パイプライン入力を使用
3. ShouldProcess確認（ConfirmImpact = High）
4. SMO Table.Drop()メソッド実行
5. 成功/失敗ステータスを含む結果オブジェクト出力

### 4-Copy-DbaDbTableData実行

1. ソース/宛先接続確立
2. 宛先テーブル存在チェック、AutoCreateTable時は自動作成
3. Truncate指定時は宛先テーブルをTRUNCATE
4. SqlBulkCopyオブジェクト生成（オプション設定）
5. ソースクエリ実行（ORDER BY付与で一貫性確保）
6. カラムマッピング適用
7. バッチ単位でWriteToServer実行
8. 進捗通知とメトリクス収集
9. 結果オブジェクト出力

### 5-Write-DbaDbTableData実行

1. 接続確立とテーブル名解析
2. テーブル存在チェック（AutoCreateTable時は自動作成、スキーマも含む）
3. Truncate指定時は事前TRUNCATE
4. 入力データをDataTable形式に変換（ConvertTo-DbaDataTable使用）
5. SqlBulkCopyでバルクインサート実行
6. 進捗表示と完了処理

## データベース更新仕様

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| Get-DbaDbTable | sys.tables | SELECT | テーブルメタデータ取得 |
| New-DbaDbTable | ユーザー指定テーブル | CREATE TABLE | 新規テーブル作成 |
| Remove-DbaDbTable | ユーザー指定テーブル | DROP TABLE | テーブル削除 |
| Copy-DbaDbTableData | 宛先テーブル | INSERT/TRUNCATE | データコピー |
| Write-DbaDbTableData | 宛先テーブル | INSERT/TRUNCATE | バルクインサート |
| Remove-DbaDbTableData | ユーザー指定テーブル | DELETE | バッチ削除 |

### テーブル別更新項目詳細

#### ユーザー指定テーブル（New-DbaDbTable）

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| CREATE TABLE | 全カラム | ColumnMap/ColumnObjectで指定 | スキーマ自動作成対応 |

#### ユーザー指定テーブル（Copy-DbaDbTableData/Write-DbaDbTableData）

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | 全カラム | ソースデータ/入力データ | SqlBulkCopy使用 |
| TRUNCATE | 全行 | 条件なし全削除 | -Truncate指定時 |

## メッセージ仕様

| メッセージ種別 | 条件 | メッセージ内容 |
|--------------|------|--------------|
| 成功 | テーブル削除完了 | Status = "Dropped" |
| 警告 | 3部構成名パース失敗 | "Please check you are using proper three-part names..." |
| 警告 | テーブル未発見 | "Could not find table {name} in {db} on {server}" |
| エラー | テーブル既存 | "Table [{Schema}].[{Name}] already exists in {db}" |
| エラー | テーブル未存在（コピー時） | "Table {name} cannot be found... Use -AutoCreateTable..." |
| エラー | 同一テーブルへのコピー | "Cannot copy {table} into itself..." |
| 進捗 | バルクコピー中 | "{rows} rows ({rows/sec} rows/sec)" |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| 接続失敗 | Stop-Function -Category ConnectionError |
| テーブル作成失敗 | 作成途中のテーブル/スキーマをDrop、エラー出力 |
| バルクコピータイムアウト | BulkCopyTimeoutパラメータで制御（デフォルト5000秒） |
| 権限不足 | SQL Server側エラーをキャッチしStop-Function |
| Azure SQLログ制限超過 | エラー40552発生の可能性を警告 |

## 備考

- SQL Server 2000以降をサポート（一部機能はバージョン依存）
- Azure SQL Databaseにも対応（ログバックアップ等の処理は自動スキップ）
- SMO（SQL Server Management Objects）を使用したオブジェクト操作
- SqlBulkCopyによる高速データ転送（ストリーミング処理でメモリ効率化）

---

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

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

### 推奨読解順序

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

テーブル管理機能はSMO（SQL Server Management Objects）のTableオブジェクトを中心に構築されている。まずSMOのテーブル関連クラスの構造を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaDbTable.ps1 | `public/Get-DbaDbTable.ps1` | .OUTPUTSセクションでMicrosoft.SqlServer.Management.Smo.Tableの出力プロパティ定義を確認（行61-95） |

**読解のコツ**: PowerShellのコメントベースヘルプ（`<# ... #>`）内の.OUTPUTSセクションに出力オブジェクトの詳細が記載されている。SMOのTableクラスはComputerName等のカスタムプロパティで拡張される。

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

Get-DbaDbTableがテーブル情報取得の起点となり、他のコマンドからも内部的に呼び出される。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaDbTable.ps1 | `public/Get-DbaDbTable.ps1` | param()ブロックでパラメータ定義、processブロックで主処理を確認 |

**主要処理フロー**:
1. **行145-168**: beginブロックでTableパラメータの3部構成名パース（Get-ObjectNameParts呼び出し）
2. **行172-174**: SqlInstanceからGet-DbaDatabase経由でデータベースオブジェクト取得
3. **行184-210**: SQLバージョンに応じたプロパティリスト構築
4. **行281**: Tables.ClearAndInitialize()でSMO一括読み込み最適化
5. **行309-340**: 結果オブジェクトにカスタムプロパティ追加とSelect-DefaultView適用

#### Step 3: テーブル作成処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | New-DbaDbTable.ps1 | `public/New-DbaDbTable.ps1` | ColumnMapハッシュテーブルからSMO Columnオブジェクトへの変換ロジック |

**主要処理フロー**:
- **行479-482**: テーブル既存チェック
- **行484**: SMO Tableオブジェクト生成（`New-Object -TypeName Microsoft.SqlServer.Management.Smo.Table`）
- **行510-564**: ColumnMapからカラムオブジェクト生成（データ型変換、デフォルト値、Identity設定）
- **行566-571**: スキーマ自動作成処理
- **行584-588**: Invoke-Create呼び出しによるテーブル作成

#### Step 4: バルクコピー処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Copy-DbaDbTableData.ps1 | `public/Copy-DbaDbTableData.ps1` | SqlBulkCopyオプション設定とストリーミング転送ロジック |

**主要処理フロー**:
- **行283-294**: bulkCopyOptionsビルド（TableLock、KeepIdentity等）
- **行389-441**: AutoCreateTable時のテーブルスクリプト生成とリネーム処理
- **行466-518**: ORDER BY句自動付与（クラスタ化インデックス/PK/Identity列順）
- **行536-541**: SqlBulkCopyオブジェクト設定（BatchSize、NotifyAfter等）
- **行557-569**: RowsCopiedイベントハンドラ（進捗表示）
- **行578-588**: カラムマッピング（名前ベースまたは序数ベース）

#### Step 5: バルクインサート処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | Write-DbaDbTableData.ps1 | `public/Write-DbaDbTableData.ps1` | ConvertTo-DbaDataTable連携とスキーマ自動作成 |

**主要処理フロー**:
- **行244-296**: Invoke-BulkCopy内部関数定義
- **行298-438**: New-Table内部関数（スキーマ/テーブル自動作成、PStoSQLTypes型変換マップ）
- **行687-702**: ConvertTo-DbaDataTableラッパー（steppablePipeline）
- **行717-734**: 入力データ型判定とバルクコピー実行

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

```
Get-DbaDbTable
    │
    ├─ Get-DbaDatabase (データベースオブジェクト取得)
    │
    ├─ Get-ObjectNameParts (テーブル名パース)
    │
    └─ Select-DefaultView (出力プロパティ制御)

New-DbaDbTable
    │
    ├─ Get-DbaDatabase
    │
    ├─ Get-DbaDbSchema (スキーマ存在確認)
    │
    ├─ Invoke-Create (SMO作成実行)
    │
    └─ Get-DbaDbTable (作成結果取得)

Copy-DbaDbTableData
    │
    ├─ Connect-DbaInstance (ソース/宛先接続)
    │
    ├─ Get-DbaDbTable / Get-DbaDbView (ソースオブジェクト取得)
    │
    ├─ Export-DbaScript (AutoCreateTable用スクリプト生成)
    │
    ├─ Invoke-DbaQuery (TRUNCATE/テーブル作成)
    │
    └─ Microsoft.Data.SqlClient.SqlBulkCopy (データ転送)

Write-DbaDbTableData
    │
    ├─ Connect-DbaInstance
    │
    ├─ ConvertTo-DbaDataTable (入力データ変換)
    │
    ├─ New-Table (内部関数: テーブル自動作成)
    │
    └─ Invoke-BulkCopy (内部関数: SqlBulkCopy実行)
```

### データフロー図

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

SqlInstance ───────────▶ Connect-DbaInstance ────────────▶ SMO Server
                                │
                                ▼
Database ──────────────▶ Get-DbaDatabase ────────────────▶ SMO Database
                                │
                                ▼
Table/Schema ──────────▶ Get-DbaDbTable ─────────────────▶ SMO Table
                                │                            (enhanced)
                                │
[Copy-DbaDbTableData]           │
SourceTable ───────────▶ SqlBulkCopy.WriteToServer ──────▶ DestinationTable
                                │
                                │
[Write-DbaDbTableData]          │
InputObject ───────────▶ ConvertTo-DbaDataTable ─────────▶ DataTable
(CSV/Object)                    │
                                ▼
                        SqlBulkCopy.WriteToServer ───────▶ TargetTable
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaDbTable.ps1 | `public/Get-DbaDbTable.ps1` | ソース | テーブルメタデータ取得 |
| New-DbaDbTable.ps1 | `public/New-DbaDbTable.ps1` | ソース | テーブル作成 |
| Remove-DbaDbTable.ps1 | `public/Remove-DbaDbTable.ps1` | ソース | テーブル削除 |
| Copy-DbaDbTableData.ps1 | `public/Copy-DbaDbTableData.ps1` | ソース | テーブルデータコピー |
| Export-DbaDbTableData.ps1 | `public/Export-DbaDbTableData.ps1` | ソース | INSERT文エクスポート |
| Write-DbaDbTableData.ps1 | `public/Write-DbaDbTableData.ps1` | ソース | バルクインサート |
| Remove-DbaDbTableData.ps1 | `public/Remove-DbaDbTableData.ps1` | ソース | バッチ削除 |
| ConvertTo-DbaDataTable.ps1 | `public/ConvertTo-DbaDataTable.ps1` | ソース | DataTable変換 |
| Export-DbaScript.ps1 | `public/Export-DbaScript.ps1` | ソース | スクリプト生成 |
| Get-DbaDatabase.ps1 | `public/Get-DbaDatabase.ps1` | ソース | データベースオブジェクト取得 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | インスタンス接続 |
