# 機能設計書 664-New-DbaDbSynonym

## 概要

本ドキュメントは、テーブル、ビュー、プロシージャ、その他のデータベースオブジェクトに代替名を提供するデータベースシノニムを作成するNew-DbaDbSynonym機能の設計仕様を記述したものである。

### 本機能の処理概要

New-DbaDbSynonymは、テーブル、ビュー、ストアドプロシージャ、関数などのデータベースオブジェクトの代替名またはエイリアスとして機能するデータベースシノニムを作成する機能である。

**業務上の目的・背景**：シノニムは、より短い名前の提供、複雑なスキーマ構造の隠蔽、またはアプリケーション用の抽象化レイヤーの作成によってオブジェクト参照を簡素化する。同一データベース内、異なるデータベース、またはリンクサーバー上のオブジェクトを参照するシノニムを作成でき、アプリケーションやユーザーにとってクロスデータベースおよびクロスサーバーのオブジェクトアクセスをより管理しやすくする。

**機能の利用シーン**：
- 複雑なオブジェクト名の簡素化
- クロスデータベース参照の抽象化
- アプリケーションからの物理オブジェクト名の隠蔽
- リンクサーバー経由のリモートオブジェクトアクセス簡素化
- データベースリファクタリング時の互換性レイヤー作成

**主要な処理内容**：
1. 入力パラメータの検証
2. 対象データベースの取得
3. 既存シノニムの重複チェック
4. 新しいSynonymオブジェクトの作成と設定
5. Create()メソッドによるシノニム作成
6. 結果オブジェクトへのメタデータ付加とパイプライン出力

**関連システム・外部連携**：SQL Server Management Objects (SMO)を使用してSQL Serverと連携し、シノニムを作成する。リンクサーバー経由でリモートサーバーのオブジェクトも参照可能。

**権限による制御**：対象データベースでのCREATE SYNONYM権限が必要。対象スキーマに対するALTER権限も必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | PowerShellコンソール | 主画面 | コマンド実行とテキスト出力表示 |

## 機能種別

データ作成（INSERT/CREATE） / DDL操作

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | No | 対象SQL Serverインスタンス | - |
| SqlCredential | PSCredential | No | 代替認証情報 | Windows/SQL/AD認証対応 |
| Database | string[] | No | シノニムを作成するデータベース | ワイルドカード対応 |
| ExcludeDatabase | string[] | No | 除外するデータベース | - |
| Synonym | String | No | 作成するシノニム名 | 必須（Stop-Functionで検証） |
| Schema | String | No | シノニムのスキーマ | デフォルト: dbo |
| BaseServer | String | No | リンクサーバー名 | BaseDatabase必須 |
| BaseDatabase | String | No | ターゲットデータベース名 | BaseSchema必須 |
| BaseSchema | String | No | ターゲットスキーマ名 | BaseDatabase使用時必須 |
| BaseObject | String | Yes | ターゲットオブジェクト名 | 必須 |
| InputObject | Database[] | No | データベースオブジェクト | パイプライン入力可能 |
| EnableException | switch | No | 例外を有効化 | - |

### 入力データソース

- SqlInstance: パイプラインまたはパラメータから取得
- InputObject: Get-DbaDatabase等からパイプライン入力
- BaseObject: 参照先オブジェクト名（必須）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverのコンピュータ名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | 完全修飾インスタンス名 |
| Database | string | データベース名 (ParentName) |
| Name | string | シノニム名 |
| Schema | string | スキーマ名 |
| BaseServer | string | ターゲットのリンクサーバー名 |
| BaseDatabase | string | ターゲットデータベース名 |
| BaseSchema | string | ターゲットスキーマ名 |
| BaseObject | string | ターゲットオブジェクト名 |

### 出力先

パイプライン出力（Microsoft.SqlServer.Management.Smo.Synonym型オブジェクト）

## 処理フロー

### 処理シーケンス

```
1. 入力検証
   └─ SqlInstanceまたはInputObjectの存在確認
2. パラメータ依存関係の検証
   └─ BaseServer→BaseDatabase、BaseDatabase→BaseSchema
3. データベースオブジェクトの取得
   └─ SqlInstance指定時はGet-DbaDatabase呼び出し
4. アクセス可能なDBのフィルタリング
   └─ IsAccessible = trueのみ対象
5. 各データベースに対するシノニム作成
   └─ 重複チェック後、Create()実行
6. 結果オブジェクトの構築と出力
   └─ NoteProperty追加とデフォルトビュー設定
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{SqlInstanceまたはInputObject?}
    B -->|No| C[Stop-Function]
    B -->|Yes| D{BaseObject指定?}
    D -->|No| E[Stop-Function]
    D -->|Yes| F{BaseServer指定?}
    F -->|Yes| G{BaseDatabase指定?}
    G -->|No| H[Stop-Function]
    G -->|Yes| I{BaseSchema指定?}
    F -->|No| I
    I -->|No/BaseDB有| J[Stop-Function]
    I -->|Yes/BaseDB無| K{Synonym名指定?}
    K -->|No| L[Stop-Function]
    K -->|Yes| M[データベース取得]
    M --> N[IsAccessibleフィルタ]
    N --> O[各DBループ]
    O --> P{シノニム重複?}
    P -->|Yes| Q[Stop-Function -Continue]
    P -->|No| R{ShouldProcess?}
    R -->|No| S{次のDB?}
    R -->|Yes| T[Synonymオブジェクト作成]
    T --> U[プロパティ設定]
    U --> V[Create実行]
    V --> W[NoteProperty追加]
    W --> X[Select-DefaultView出力]
    X --> S
    Q --> S
    S -->|Yes| O
    S -->|No| Y[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-664-1 | BaseObject必須 | ターゲットオブジェクト名は必ず指定 | 常時 |
| BR-664-2 | BaseServer依存 | BaseServer指定時はBaseDatabase必須 | BaseServer指定時 |
| BR-664-3 | BaseDatabase依存 | BaseDatabase指定時はBaseSchema必須 | BaseDatabase指定時 |
| BR-664-4 | シノニム重複禁止 | 同名シノニムが存在する場合はエラー | 常時 |
| BR-664-5 | デフォルトスキーマ | Schema未指定時はdboを使用 | Schema未指定時 |
| BR-664-6 | アクセス可能DB限定 | IsAccessible=trueのDBのみ対象 | 常時 |

### 計算ロジック

特になし

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 作成 | sys.synonyms | INSERT | シノニム作成 |

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

#### sys.synonyms (SMO経由)

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | name, schema_id, base_object_name | パラメータから設定 | Create()メソッド経由 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | Stop | SqlInstanceもInputObjectも未指定 | Stop-Functionで停止 |
| - | Stop | BaseObject未指定 | Stop-Functionで停止 |
| - | Stop | BaseServer指定時のBaseDatabase未指定 | Stop-Functionで停止 |
| - | Stop | BaseDatabase指定時のBaseSchema未指定 | Stop-Functionで停止 |
| - | Stop | Synonym名未指定 | Stop-Functionで停止 |
| - | Stop-Continue | 同名シノニム既存 | 警告出力後、次DBへ継続 |
| - | Stop-Continue | Create失敗 | エラー出力後、次DBへ継続 |

### リトライ仕様

リトライ処理は実装されていない。

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

SMOのCreate()メソッドによる暗黙的なトランザクション管理。

## パフォーマンス要件

- シノニム作成は軽量なDDL操作
- 複数データベースへの一括作成時はデータベース数に比例した処理時間

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

- SqlCredentialパラメータで認証情報を安全に受け渡し
- CREATE SYNONYM権限が必要
- 対象スキーマに対するALTER権限が必要
- SupportsShouldProcess/ConfirmImpactでWhatIf/Confirm対応

## 備考

- Get-DbaDatabase -ExcludeSystemとパイプラインで連携することで、全ユーザーDBに一括でシノニムを作成可能
- SMOのSynonymオブジェクトをそのまま返すため、追加のプロパティもSelect-Object *で参照可能

---

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

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

### 推奨読解順序

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

SMOのSynonymオブジェクトの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | SMO Synonym | (SMO Documentation) | プロパティ: Name, Schema, BaseServer, BaseDatabase, BaseSchema, BaseObject |

**読解のコツ**: Synonymオブジェクトは作成時にParent（Database）を設定し、各Baseプロパティで参照先を指定する。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | New-DbaDbSynonym.ps1 | `public/New-DbaDbSynonym.ps1` | メイン処理の流れを把握 |

**主要処理フロー**:
1. **157-180行目**: 入力検証とパラメータ依存関係チェック
2. **182-186行目**: SqlInstance指定時のデータベース取得
3. **188行目**: IsAccessibleフィルタリング
4. **190-199行目**: 重複チェック
5. **203-215行目**: Synonymオブジェクト作成とプロパティ設定
6. **217-222行目**: NoteProperty追加とデフォルトビュー出力

#### Step 3: 依存関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaDatabase | `public/Get-DbaDatabase.ps1` | データベース取得処理 |
| 3-2 | Select-DefaultView | `internal/functions/` | デフォルト表示プロパティ設定 |

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

```
New-DbaDbSynonym
    │
    ├─ Stop-Function (入力検証)
    │
    ├─ Get-DbaDatabase (DB取得)
    │      └─ Connect-DbaInstance
    │
    ├─ $db.Synonyms (重複チェック)
    │
    ├─ New-Object Synonym (オブジェクト作成)
    │      └─ プロパティ設定
    │             ├─ Name
    │             ├─ Schema
    │             ├─ Parent
    │             ├─ BaseDatabase
    │             ├─ BaseSchema
    │             ├─ BaseObject
    │             └─ BaseServer
    │
    ├─ $newSynonym.Create() (シノニム作成)
    │
    ├─ Add-Member (プロパティ追加)
    │
    └─ Select-DefaultView (出力フォーマット)
```

### データフロー図

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

SqlInstance ───────────┐
                       │
SqlCredential ─────────┼──▶ Get-DbaDatabase ───────▶ Database[]
                       │
Database ──────────────┤
                       │
ExcludeDatabase ───────┤
                       │
InputObject ───────────┘
                              │
                              ▼
Synonym ───────────────┐     重複チェック
Schema ────────────────┤
BaseServer ────────────┤
BaseDatabase ──────────┼──▶ New-Object Synonym ────▶ Synonym
BaseSchema ────────────┤
BaseObject ────────────┘
                              │
                              ▼
                        Create() ──────────────────▶ DB登録
                              │
                              ▼
                        Add-Member ─────────────────▶ 拡張Synonym
                              │
                              ▼
                        Select-DefaultView ────────▶ パイプライン出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| New-DbaDbSynonym.ps1 | `public/New-DbaDbSynonym.ps1` | ソース | メイン機能実装 |
| Get-DbaDatabase.ps1 | `public/Get-DbaDatabase.ps1` | ソース | データベース取得 |
| Get-DbaDbSynonym.ps1 | `public/Get-DbaDbSynonym.ps1` | ソース | シノニム取得（関連機能） |
| Remove-DbaDbSynonym.ps1 | `public/Remove-DbaDbSynonym.ps1` | ソース | シノニム削除（関連機能） |
| Select-DefaultView.ps1 | `internal/functions/` | ソース | 出力フォーマット |
