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
- Une copie locale d'un helper dot-sourcée par une application masque silencieusement la version du module. Quand une fonction passe dans le module, supprimez la copie locale.
- Gardez le module sans connaissance d'environnement : pas de noms de serveurs, pas de fichiers de config. Tout passe en paramètre.
- Une seule convention de retour pour toutes les fonctions publiques (par exemple une hashtable avec un indicateur de succès, des données et une raison) permet de traiter les échecs uniformément.
- Gardez
Tests/hors des dossiers chargés, sinon vos tests s'exécutent à l'import. - Un outil qui gagne un planning et un fichier de config doit être promu en application ; un outil dont le travail est fini doit être supprimé.