LLI Wiki — My Digital Knowledge Base

Structurer un module PowerShell pour le travail de DBA

Manifeste, dossiers Classes/Private/Public, chargeur, modèles SQL à placeholders, versionnement et frontière module / application / outil.

Quand une équipe DBA écrit du PowerShell, les scripts commencent comme des one-shots puis deviennent peu à peu des copies les uns des autres : le même code de jeton, la même boucle de retry, le même appel de log collé dans vingt fichiers. Le module est le remède, à condition de bien le structurer et de savoir ce qui y a sa place, ce qui relève d'une application et ce qui reste un outil. Voici ma façon de faire.

L'arborescence

Contoso.Dba/
├── Contoso.Dba.psd1      # manifeste
├── Contoso.Dba.psm1      # module racine : chargeur uniquement
├── README.md
├── Classes/              # classes PowerShell, chargées en premier
├── Private/              # helpers internes, jamais exportés
├── Public/               # un fichier par fonction exportée
├── sql/                  # modèles T-SQL avec {{placeholders}}
├── Tests/                # tests Pester, jamais chargés à l'import
└── Examples/

Règle : une fonction par fichier, nommé comme la fonction. Les diffs restent lisibles, la revue est simple et les tests correspondent un pour un (Public/Get-PoolUsage.ps1 a Tests/Get-PoolUsage.Tests.ps1).

Le manifeste

@{
    RootModule        = 'Contoso.Dba.psm1'
    ModuleVersion     = '2026.11.1'
    GUID              = '00000000-0000-0000-0000-000000000000'
    Author            = 'DBA Team'
    PowerShellVersion = '7.0'
    RequiredModules   = @('SqlServer', 'Az.Accounts')
    FunctionsToExport = '*'
    CmdletsToExport   = @()
    AliasesToExport   = @()
}

FunctionsToExport = '*' est un compromis : c'est pratique, et le module racine filtre réellement avec Export-ModuleMember. Le coût : la découverte des commandes sans importer le module est plus lente et moins précise. Pour un module publié dans une galerie, une liste explicite est préférable ; pour un module interne j'accepte le joker et je laisse le chargeur décider.

Le chargeur

Le .psm1 ne contient aucune logique métier, seulement l'ordre de chargement : classes, helpers privés, puis fonctions publiques qui sont exportées.

foreach ($folder in 'Classes', 'Private') {
    $path = Join-Path $PSScriptRoot $folder
    if (Test-Path $path) {
        Get-ChildItem $path -Filter *.ps1 | ForEach-Object { . $_.FullName }
    }
}

$publicPath = Join-Path $PSScriptRoot 'Public'
if (Test-Path $publicPath) {
    Get-ChildItem $publicPath -Filter *.ps1 | ForEach-Object {
        . $_.FullName
        Export-ModuleMember -Function $_.BaseName
    }
}

Les classes d'abord, car les fonctions peuvent les utiliser comme types. Private avant Public, car les fonctions publiques les appellent. Tests/ n'est jamais chargé en dot-sourcing : c'est pourquoi les tests vivent à côté de Public/ et Private/, pas dedans.

Modèles SQL

Le texte SQL n'a pas sa place dans des chaînes PowerShell. Je le range dans sql/*.sql avec des {{Nom}} et une petite fonction privée qui charge le fichier et remplace les placeholders :

function Expand-SqlTemplate {
    param([string]$Name, [hashtable]$Values)
    $sql = Get-Content (Join-Path $PSScriptRoot "..\sql\$Name.sql") -Raw
    foreach ($key in $Values.Keys) { $sql = $sql.Replace("{{$key}}", [string]$Values[$key]) }
    if ($sql -match '\{\{\w+\}\}') { throw "Unresolved placeholder in $Name" }
    $sql
}

Le contrôle final est important : un placeholder oublié doit échouer bruyamment, pas arriver sur le serveur sous forme de texte littéral. Les placeholders servent aux identifiants (nom de base) qui ne peuvent pas être des paramètres SQL ; les vraies valeurs passent toujours par des paramètres.

Versionnement

J'utilise AAAA.M.N : année, mois, et un compteur qui s'incrémente dans le mois. La date indique d'un coup d'oeil l'ancienneté d'un module déployé. Le tag est par module, donc une application peut figer la version exacte avec laquelle elle a été testée.

Module, application ou outil ?

Type Contenu Test
Module Fonctions réutilisables sans point d'entrée : auth, exécution SQL, logs, helpers Deux jobs différents l'appelleraient-ils ?
Application Un script d'entrée, ses propres Functions/, config/ par environnement, souvent planifiée Tourne-t-elle sans surveillance et a-t-elle besoin d'une release ?
Outil Un script autonome lancé à la main, qui réutilise le module Est-il occasionnel, sans déploiement propre ?
flowchart TD
    M["Module partagé (Public / Private / Classes / sql)"]
    A1["Application planifiée 1"]
    A2["Application planifiée 2"]
    T["Outil lancé à la main"]
    C["config-env.json"]
    A1 --> M
    A2 --> M
    T --> M
    C --> A1
    C --> A2

Les applications et les outils dépendent du module, jamais l'inverse. Un module qui lit le fichier de config d'une application est déjà mal parti.

Retour d'expérience

Mastodon LLIMastodon SocialFosstodon