Automacao PowerShell para SQL Server & Azure

Posicionamento

O PowerShell nao e para mim apenas uma linguagem de scripting -- e o tecido conectivo entre a administracao do SQL Server, as operacoes de nuvem Azure e as praticas de DevOps. Venho desenvolvendo e aplicando esta tecnologia desde seus primeiros dias como Windows PowerShell em projetos de clientes. O que torna o PowerShell tao atraente e a combinacao de integracao profunda com o sistema operacional Windows, modulos excelentes para SQL Server (dbatools) e Azure (Az), um pipeline orientado a objetos e a capacidade de incorporar scripts diretamente em sistemas CI/CD. Essas propriedades tornam o PowerShell a linguagem ideal para eliminar tarefas repetitivas e implementar infraestrutura como codigo.

Em projetos em uma organizacao publica de pesquisa, em um banco de poupanca, em uma empresa textil e prestadora de servicos e em um fabricante de maquinas industriais, usei o PowerShell como nucleo da camada de automacao: para deployment SSDT, para relatorios Excel com dados do Data Warehouse, para configuracao do Azure e para pipelines CI/CD baseadas em YAML. A amplitude desses casos de uso demonstra que o PowerShell nao e uma ferramenta de nicho, mas um instrumento universal relevante em qualquer ambiente empresarial orientado a dados.

Por que a automacao com PowerShell e tao demandada hoje? Tres fatores atuam em conjunto: primeiro, parques de servidores e infraestruturas de nuvem crescem mais rapido do que a administracao manual consegue escalar. Segundo, requisitos regulatorios e auditorias exigem mudancas rastreaveis e registradas que sequencias de cliques manuais nao conseguem fornecer. Terceiro, pipelines de deployment automatizadas reduzem significativamente o tempo de entrada no mercado para mudancas de schema de banco de dados, reduzindo simultaneamente o risco de erros humanos ao aplicar atualizacoes. Abordar os tres cria uma vantagem competitiva mensuravel.

Fundamentos do PowerShell no Contexto DBA/DevOps

O PowerShell difere fundamentalmente das linguagens de shell classicas: em vez de fluxos de texto simples, o pipeline processa objetos .NET. Isso tem consequencias de longo alcance para o desenvolvimento de scripts. Quando o Invoke-Sqlcmd retorna um conjunto de resultados de uma consulta SQL Server, voce trabalha com objetos tipados cujas propriedades sao diretamente enderecsaveis -- sem regex em saida de texto. Quando voce usa cmdlets do dbatools, recebe objetos totalmente documentados que podem ser canalizados, filtrados, agregados e alimentados em outros sistemas sem esforco. Essa base orientada a objetos torna o codigo PowerShell substancialmente mais robusto e sustentavel do que scripts batch ou shell equivalentes.

Modulos, Versionamento e Plataforma Cruzada

O PowerShell 7 (PowerShell Core) roda em multiplataformas no Windows, Linux e macOS. Para automacao pura de SQL Server e Azure em servidores Windows, o Windows PowerShell 5.1 ainda e relevante porque certos modulos e cenarios de COM-interop ainda dependem dele. Uso a versao adequada para cada ambiente e garanto que os modulos estejam fixados em versoes definidas (#Requires -Modules) para evitar problemas de compatibilidade em execucoes automatizadas.

Estrutura de Modulos e Reutilizacao

Scripts PowerShell bons nao sao arquivos de texto monoliticos, mas modulos estruturados com funcoes claras, blocos de parametros e ajuda baseada em comentarios. Desenvolvo scripts de automacao com CmdletBinding, blocos Param e tipos de retorno padronizados para que possam ser incorporados em pipelines, sistemas CI/CD e tarefas agendadas sem modificacoes de codigo. Validacao de parametros via [ValidateSet], [ValidateNotNullOrEmpty] e [ValidateRange] torna os scripts mais seguros e autodocumentados.

Tratamento de Erros com try/catch e ErrorAction

Uma das fraquezas mais comuns em scripts de automacao amadores e a ausencia de tratamento de erros. Um script que aborta silenciosamente em um erro de conexao e relata um sucesso parcial como sucesso total e mais perigoso do que nenhum script. Uso consistentemente blocos try/catch, ErrorAction Stop para cmdlets e handlers trap para excecoes inesperadas, combinados com uma estrutura de logging que registra erros com timestamp, contexto e nivel de severidade. Isso cria uma trilha de auditoria confiavel que explica imediatamente o que aconteceu, onde e por que quando algo da errado.

• Expertise em PowerShell 5.1 (Windows) e PowerShell 7+ (plataforma cruzada)
• Pipeline orientado a objetos: objetos tipados, sem analise de texto
• Estrutura de modulos: CmdletBinding, Param, ajuda em comentarios, ValidateSet
• Design tolerante a falhas: try/catch, ErrorAction Stop, logging estruturado
• Gerenciamento de codigo versionado em Git: branches, tags, pull requests
• Scripts assinados e execution policy para ambientes de producao seguros

Visao geral do pipeline de automacao PowerShell: entrada (script, dbatools/Az), processamento no motor com tratamento de erros e logging, saida para SQL Server, Azure e Excel/CSV.

Inventario de Servidores com dbatools

O modulo dbatools e uma das maiores historias de sucesso da comunidade PowerShell. Mais de 600 cmdlets cobrem praticamente todas as tarefas concebiveis de DBA: gerenciamento de conexoes, inventario de instancias, provisionamento de bancos de dados, backup e restauracao, gerenciamento de permissoes, monitoramento de HADR, manutencao de indice, comparacao de configuracao e muito mais. Os cmdlets seguem a convencao PowerShell Verbo-Substantivo, sao documentados uniformemente e retornam objetos tipados que se integram perfeitamente a scripts personalizados. Com o dbatools, uma unica linha de codigo pode recuperar informacoes em centenas de servidores -- algo que nenhuma pessoa poderia conseguir manualmente em um tempo razoavel.

Em um provedor de servicos financeiros, inventariar aproximadamente 80 instancias virtualizadas do SQL Server foi uma das primeiras tarefas que resolvi com o dbatools. O inventario completo -- numeros de build, tamanhos de banco de dados, modelos de recuperacao, timestamps de backup e desvios de configuracao -- foi produzido em minutos e forneceu a base para cada medida subsequente: priorizacao de patches, remediacao de seguranca e planejamento de capacidade. O que teria levado semanas manualmente foi concluido em uma unica execucao com scripts.

Fluxo de trabalho do inventario dbatools: lista de servidores como entrada, coleta de dados via multiplos cmdlets, consolidacao em tabela central, consumo por patching, monitoramento e relatorios.

Inventario Completo em Minutos

O codigo abaixo mostra como coleto um inventario completo do SQL Server em qualquer numero de instancias, marco desvios de configuracao e exporto os resultados como CSV e diretamente em uma tabela de controle do SQL Server. Falhas de conexao sao registradas sem abortar a execucao geral. O padrao e facilmente estendido com status de backup, indices ausentes, correcoes de configuracao pendentes ou nivel de patch.

# Coleta um inventario completo do SQL Server a partir de uma lista de servidores.
# Armazena dados de instancias, tamanhos de bancos e nivel de build como CSV
# e em uma tabela de controle central (SQL Server).
#Requires -Modules dbatools

param(
    [string]$ServerListPath = 'C:\admin\sql_server_list.txt',
    [string]$OutputCsv      = 'C:\admin\sql_inventory.csv',
    [string]$CentralServer  = 'MGMT-SQL01',
    [string]$CentralDb      = 'DBA_Central',
    [string]$CentralTable   = 'dbo.Inventory'
)

Set-DbatoolsConfig -Name logging.errorloglevel -Value 5   # Log detalhado

$servers = Get-Content -Path $ServerListPath -ErrorAction Stop

$report = [System.Collections.Generic.List[PSCustomObject]]::new()

foreach ($srv in $servers) {
    try {
        # Estabelece conexao -- bloco catch trata falha sem abortar
        $inst = Connect-DbaInstance -SqlInstance $srv `
                    -ConnectTimeout 10 -ErrorAction Stop

        # Dados basicos da instancia
        $props = Get-DbaInstanceProperty -SqlInstance $inst |
            Where-Object { $_.Name -in @('BuildNumber','Edition','Collation',
                                          'MaxServerMemory','MinServerMemory') } |
            Group-Object -AsHashTable -Property Name

        # Bancos de dados: tamanho, status, modelo de recuperacao, idade do backup
        $dbs = Get-DbaDatabase -SqlInstance $inst -ExcludeSystem |
            Select-Object Name, Status, RecoveryModel, SizeMB,
                @{ N='BackupAgeDays'; E={
                    if ($_.LastBackupDate) {
                        [math]::Round(((Get-Date) - $_.LastBackupDate).TotalDays, 1)
                    } else { 9999 }   # sem backup registrado
                }}

        $obj = [PSCustomObject]@{
            Timestamp     = (Get-Date -Format 'yyyy-MM-dd HH:mm')
            Server        = $srv
            Build         = $props['BuildNumber'].Value
            Edition       = $props['Edition'].Value
            DatabaseCount = $dbs.Count
            TotalSizeMB   = ($dbs | Measure-Object SizeMB -Sum).Sum
            # Bancos sem backup nos ultimos 7 dias -- acao necessaria
            NeedBackup    = ($dbs | Where-Object BackupAgeDays -gt 7).Name -join '; '
            MaxMemoryMB   = $props['MaxServerMemory'].Value
        }
        $report.Add($obj)
    }
    catch {
        # Registra falha de conexao e continua com proximo servidor
        $report.Add([PSCustomObject]@{
            Timestamp = (Get-Date -Format 'yyyy-MM-dd HH:mm')
            Server    = $srv
            Build     = 'ERRO_CONEXAO'
            Edition   = $_.Exception.Message
        })
        Write-Warning "Erro em $srv : $($_.Exception.Message)"
    }
}

# Exportar CSV para trilha de auditoria
$report | Export-Csv -Path $OutputCsv -NoTypeInformation -Encoding UTF8
Write-Host "Inventario: $($report.Count) servidores processados. CSV: $OutputCsv"

# Carregar na tabela de controle central (opcional)
$report | Write-DbaDataTable -SqlInstance $CentralServer `
    -Database $CentralDb -Table $CentralTable -AutoCreateTable
Write-Host "Dados carregados em $CentralServer.$CentralDb.$CentralTable"

Este script coleta um inventario completo de qualquer numero de instancias SQL Server. Falhas de conexao sao registradas sem abortar a execucao. Os resultados sao exportados como CSV e carregados em uma tabela de controle central.

Comparacao de Configuracao e Deteccao de Desvios

Alem do inventario puro, o dbatools e excelente para detectar e corrigir desvios de configuracao. Cmdlets como Test-DbaMaxMemory, Test-DbaConnectionAuthScheme e Get-DbaSpConfigure recuperam o estado atual, que comparo com uma linha de base de configuracao alvo. Instancias que desviam recebem correcoes especificas via Set-DbaMaxMemory ou Set-DbaSpConfigure sem tocar em todo o parque. Essa abordagem de 'estado desejado' e o primeiro passo em direcao a uma estrategia consistente de infraestrutura como codigo.

• Get-DbaDatabase: tamanhos de bancos, modelos de recuperacao, timestamps de backup
• Get-DbaInstanceProperty: numeros de build, edicoes, valores de configuracao
• Test-DbaMaxMemory / Set-DbaMaxMemory: verificar e corrigir configuracao de memoria
• Get-DbaDiskSpace: detectar criticidade de espaco em disco antes de alertas dispararem
• Copy-DbaDatabase: migrar bancos entre instancias sem backup/restauracao
• Invoke-DbaQuery: executar T-SQL ad hoc ou de arquivo contra N instancias de uma vez

Automacao de Deployment SSDT/DACPAC

O SQL Server Data Tools (SSDT) permite que schemas de banco de dados sejam versionados como projetos Visual Studio e entregues como artefatos de deployment. O artefato e um DACPAC -- um pacote contendo um snapshot completo do schema. O SqlPackage.exe ou o cmdlet PowerShell Publish-DbaDacPackage pode comparar este DACPAC com um banco de dados alvo e aplicar apenas as mudancas delta, sem scripts de mudanca criados manualmente. O resultado e um deployment idempotente e reproduzivel que pode ser incorporado em qualquer pipeline CI/CD.

Em um banco de poupanca, automatizei todo o fluxo de deployment SSDT: build do DACPAC no sistema CI, comparacao automatica com o banco de dados alvo, geracao de relatorio de mudancas para revisao, seguida de aplicacao automatizada do DACPAC apos aprovacao. O roulette de scripts manuais -- onde desenvolvedores mantinham scripts de mudanca feitos a mao e conflitos de versao surgiam regularmente -- foi eliminado. Em uma empresa textil e prestadora de servicos combinei o deployment SSDT com integracao de pipeline Azure DevOps e contas de servico baseadas em Entra ID, simplificando a configuracao de acesso e elevando o padrao de seguranca.

# Deployment SSDT/DACPAC automatizado com idempotencia e seguranca de rollback.
# Constroi o DACPAC a partir do projeto SSDT, compara com o banco alvo
# e aplica as mudancas de forma idempotente.
#Requires -Modules dbatools

param(
    [Parameter(Mandatory)][string]$SsdtProjectPath,  # Caminho para o arquivo .sqlproj
    [Parameter(Mandatory)][string]$TargetServer,      # SQL Server alvo
    [Parameter(Mandatory)][string]$TargetDatabase,    # Banco de dados alvo
    [string]$DacpacOutputDir = 'C:\builds\dacpacs',
    [string]$BackupDir       = 'C:\builds\backups',
    [switch]$WhatIf                                   # Apenas comparar, sem deployment
)

$ErrorActionPreference = 'Stop'
$timestamp = Get-Date -Format 'yyyyMMdd_HHmmss'
$logFile   = "$DacpacOutputDir\deploy_${TargetDatabase}_${timestamp}.log"

function Write-Log {
    param([string]$Msg, [string]$Level = 'INFO')
    $entry = "[$((Get-Date -Format 'HH:mm:ss'))] [$Level] $Msg"
    Add-Content -Path $logFile -Value $entry
    if ($Level -eq 'ERROR') { Write-Error $entry } else { Write-Host $entry }
}

try {
    Write-Log "Iniciando deployment DACPAC: $TargetDatabase em $TargetServer"

    # Passo 1: MSBuild -- compilar DACPAC a partir do projeto SSDT
    Write-Log "Construindo projeto SSDT: $SsdtProjectPath"
    $msbuild = "${env:ProgramFiles(x86)}\MSBuild\Current\Bin\MSBuild.exe"
    & $msbuild $SsdtProjectPath /p:Configuration=Release /p:OutputPath=$DacpacOutputDir `
        /verbosity:minimal /nologo
    if ($LASTEXITCODE -ne 0) { throw "MSBuild falhou. Codigo de saida: $LASTEXITCODE" }

    $dacpacName = [System.IO.Path]::GetFileNameWithoutExtension($SsdtProjectPath)
    $dacpacPath = Join-Path $DacpacOutputDir "$dacpacName.dacpac"
    Write-Log "DACPAC criado: $dacpacPath"

    # Passo 2: Checkpoint de seguranca -- backup antes do deployment
    if (-not $WhatIf) {
        Write-Log "Criando backup pre-deployment..."
        $bkName = "${TargetDatabase}_PreDeploy_${timestamp}.bak"
        Backup-DbaDatabase -SqlInstance $TargetServer -Database $TargetDatabase `
            -Path $BackupDir -FilePath $bkName -CompressBackup -Checksum | Out-Null
        Write-Log "Backup criado: $BackupDir\$bkName"
    }

    # Passo 3: Gerar relatorio de mudancas (sempre, mesmo no modo WhatIf)
    Write-Log "Gerando relatorio de mudancas..."
    $reportPath = "$DacpacOutputDir\${TargetDatabase}_${timestamp}_changes.xml"
    $sqlpkg = "${env:ProgramFiles(x86)}\Microsoft SQL Server\160\DAC\bin\SqlPackage.exe"
    & $sqlpkg /Action:DeployReport /SourceFile:$dacpacPath `
        /TargetServerName:$TargetServer /TargetDatabaseName:$TargetDatabase `
        /OutputPath:$reportPath /p:DropObjectsNotInSource=false
    Write-Log "Relatorio de mudancas salvo: $reportPath"

    if ($WhatIf) {
        Write-Log "Modo WhatIf: sem deployment, apenas relatorio gerado." 'WARN'
        return
    }

    # Passo 4: Aplicar DACPAC de forma idempotente
    Write-Log "Aplicando DACPAC..."
    Publish-DbaDacPackage -SqlInstance $TargetServer -Database $TargetDatabase `
        -Path $dacpacPath -PublishXml "$DacpacOutputDir\publish.xml" |
        Tee-Object -FilePath $logFile -Append
    Write-Log "Deployment concluido com sucesso."
}
catch {
    Write-Log "Deployment falhou: $($_.Exception.Message)" 'ERROR'
    Write-Log "Rollback: restaurar ultimo backup se necessario." 'WARN'
    throw
}

Este script constroi um DACPAC a partir de um projeto SSDT, cria um backup pre-deployment, gera um relatorio de mudancas e aplica as mudancas de forma idempotente. No modo WhatIf apenas o relatorio e gerado; nenhum deployment real e realizado.

Publish.xml e Opcoes de Deployment

O SqlPackage.exe e o Publish-DbaDacPackage aceitam um arquivo XML de publicacao onde as opcoes de deployment sao controladas em detalhes: o banco de dados deve ser criado se nao existir? Objetos ausentes no DACPAC devem ser excluidos do alvo? Certas tabelas ou schemas devem ser excluidos do deployment? Essas opcoes sao versionaveis e podem variar por ambiente (Dev, Teste, Prod) sem alteracoes de codigo, dando controle total sobre o comportamento do deployment.

Populacao de Excel com Dados do DWH (ImportExcel)

Um dos requisitos mais frequentes em projetos de DWH e a entrega automatizada de dados em planilhas Excel: relatorios de gestao, avaliacoes mensais, resumos de departamentos distribuidos por email. A solucao ingnua e um pacote SSIS com um conector de destino Excel -- fragil, dependente de 32/64 bits e de alta manutencao. A solucao elegante e o modulo ImportExcel, que cria arquivos Excel sem nenhum Excel instalado, completamente formatado com formulas, tabelas dinamicas e graficos. Uso o ImportExcel em scripts PowerShell prontos para CI/CD que rodam confiavelmente em servidores sem Microsoft Office instalado.

Em uma organizacao publica de pesquisa, desenvolvi um script PowerShell que extrai dados do Data Warehouse mensalmente, formata-os e os escreve em apostilas Excel de multiplas planilhas. O script estava integrado ao pipeline CI/CD do Jenkins e executava de forma agendada. Os departamentos de negocios recebiam automaticamente relatorios precisos e atualizados sem que nenhum DBA ou desenvolvedor de BI precisasse intervir manualmente. Ao mesmo tempo, o script estava sob controle de versao, de modo que mudancas no layout e na logica de calculo permaneceram completamente rastreaveis.

# Exporta dados do DWH para apostilas Excel formatadas.
# Usa ImportExcel -- nao requer Microsoft Office no servidor.
# Cria multiplas planilhas, formatacao condicional e AutoFiltro.
#Requires -Modules ImportExcel, dbatools

param(
    [string]$DwhServer   = 'DWH-SQL01',
    [string]$DwhDatabase = 'DataWarehouse',
    [string]$OutputPath  = 'C:\reports\DWH_RelatorioMensal.xlsx',
    [int]   $MonthOffset = 0   # 0 = mes atual, -1 = mes anterior, etc.
)

$ErrorActionPreference = 'Stop'
$reportMonth = (Get-Date).AddMonths($MonthOffset).ToString('yyyy-MM')
Write-Host "Criando relatorio para o mes: $reportMonth"

# Consultas T-SQL para as planilhas individuais
$sqlReceita = @"
SELECT
    Departamento,
    CentrodeCusto,
    SUM(Receita_BRL)    AS Receita_BRL,
    SUM(Custo_BRL)      AS Custo_BRL,
    SUM(Receita_BRL) - SUM(Custo_BRL) AS MargemContribuicao
FROM dwh.FatoReceita
WHERE FORMAT(DataLancamento, 'yyyy-MM') = '$reportMonth'
GROUP BY Departamento, CentrodeCusto
ORDER BY Departamento, CentrodeCusto;
"@

$sqlTopClientes = @"
SELECT TOP 20
    ClienteNo,
    NomeCliente,
    SUM(Receita_BRL) AS Receita_BRL
FROM dwh.FatoReceita f
JOIN dwh.DimCliente c ON f.ClienteKey = c.ClienteKey
WHERE FORMAT(DataLancamento, 'yyyy-MM') = '$reportMonth'
GROUP BY ClienteNo, NomeCliente
ORDER BY Receita_BRL DESC;
"@

# Buscar dados do DWH
Write-Host "Carregando dados de receita do DWH..."
$dadosReceita    = Invoke-DbaQuery -SqlInstance $DwhServer -Database $DwhDatabase -Query $sqlReceita
$dadosTopCliente = Invoke-DbaQuery -SqlInstance $DwhServer -Database $DwhDatabase -Query $sqlTopClientes

# Remover arquivo existente (comportamento idempotente)
if (Test-Path $OutputPath) { Remove-Item $OutputPath -Force }

# Planilha 1: Receita por departamento
$xlParam = @{
    Path          = $OutputPath
    WorksheetName = "Receita_$reportMonth"
    TableName     = "TblReceita"
    TableStyle    = 'Medium9'
    AutoSize      = $true
    FreezeTopRow  = $true
    AutoFilter    = $true
    BoldTopRow    = $true
    PassThru      = $true   # Retornar pacote Excel para edicoes adicionais
}
$excelPkg = $dadosReceita | Export-Excel @xlParam

# Formatacao condicional: destacar margem de contribuicao negativa em vermelho
$ws      = $excelPkg.Workbook.Worksheets["Receita_$reportMonth"]
$lastRow = $ws.Dimension.End.Row
Add-ConditionalFormatting -WorkSheet $ws `
    -Range "E2:E$lastRow" `
    -RuleType LessThan -ConditionValue 0 `
    -BackgroundColor ([System.Drawing.Color]::FromArgb(255, 200, 200))

# Planilha 2: Top 20 clientes
$dadosTopCliente | Export-Excel -ExcelPackage $excelPkg `
    -WorksheetName "Top20_Clientes" `
    -TableName "TblTopClientes" `
    -TableStyle 'Medium6' `
    -AutoSize -FreezeTopRow -AutoFilter

# Salvar e fechar
Close-ExcelPackage $excelPkg
Write-Host "Relatorio Excel criado: $OutputPath"

Este script consulta dados do Data Warehouse via Invoke-DbaQuery, gera uma apostila Excel de multiplas planilhas com tabelas formatadas e formatacao condicional para valores negativos, sem Microsoft Office no servidor. O ImportExcel cria arquivos .xlsx genuinos.

Tabelas Dinamicas e Graficos com ImportExcel

O ImportExcel tambem suporta tabelas dinamicas e graficos incorporados, aumentando significativamente a usabilidade dos relatorios exportados. Com Add-PivotTable e Add-ExcelChart, areas de analise dinamica e visualizacoes podem ser integradas diretamente no script, permitindo que os destinatarios explorem dados sem precisar de habilidades avancadas em Excel. Para departamentos de controladoria e financas, essa e frequentemente a abordagem mais pragmatica para relatorios recorrentes e automatizados.

Azure PowerShell: Entra ID, KeyVault, Storage

O modulo Az e a interface PowerShell oficial para o Azure. Cobre todos os servicos Azure relevantes para um freelancer de SQL Server e DWH: Entra ID (antigo Azure Active Directory) para gerenciamento de usuarios e grupos, Key Vault para gerenciamento seguro de segredos e strings de conexao, Azure Storage para destinos de backup e transferencias de arquivos, e Azure SQL e Synapse para operacoes de banco de dados na nuvem. Uso o modulo Az consistentemente em scripts de automacao que genuinamente cumprem os requisitos de seguranca: sem senhas em scripts, referencias ao Key Vault e Managed Identities em vez disso.

Em uma empresa textil e prestadora de servicos, desenvolvi scripts Azure PowerShell que sincronizam grupos do Entra ID com permissoes de acesso ao banco de dados, recuperam strings de conexao de banco de dados com seguranca do Key Vault e armazenam arquivos de backup no Azure Blob Storage. Essa abordagem eliminou completamente credenciais hard-coded de scripts e arquivos de configuracao e as substituiu por segredos rotataveis do Key Vault. No mesmo cliente, o Azure PowerShell tambem serviu como alavanca para analisar custos do Azure e identificar potencial de otimizacao para recursos nao utilizados.

# Le uma string de conexao com seguranca do Azure Key Vault
# e consulta membros de um grupo de seguranca do Entra ID.
# Sem senhas hard-coded no script.
#Requires -Modules Az.KeyVault, Az.Accounts, Az.Resources

param(
    [Parameter(Mandatory)][string]$TenantId,        # Tenant do Entra ID
    [Parameter(Mandatory)][string]$SubscriptionId,  # Assinatura Azure
    [string]$KeyVaultName = 'kv-dwh-prod',
    [string]$SecretName   = 'sql-dwh-connstr',
    [string]$GroupName    = 'GRP-DWH-ReadOnly'      # Grupo Entra ID
)

$ErrorActionPreference = 'Stop'

# Autenticacao -- preferir Managed Identity, fallback para interativa
try {
    Connect-AzAccount -Identity -TenantId $TenantId `
        -SubscriptionId $SubscriptionId -ErrorAction Stop
    Write-Host "Autenticado via Managed Identity."
}
catch {
    Write-Warning "Managed Identity nao disponivel, alternando para login interativo."
    Connect-AzAccount -TenantId $TenantId -SubscriptionId $SubscriptionId
}

# Ler string de conexao com seguranca do Key Vault
Write-Host "Lendo segredo '$SecretName' do Key Vault '$KeyVaultName'..."
$secret = Get-AzKeyVaultSecret -VaultName $KeyVaultName -Name $SecretName `
    -AsPlainText -ErrorAction Stop
Write-Host "Segredo recuperado com sucesso. (Valor nao exibido no console)"

# Recuperar grupo do Entra ID e seus membros
Write-Host "Carregando membros do grupo: $GroupName"
$group   = Get-AzADGroup -DisplayName $GroupName -ErrorAction Stop
$members = Get-AzADGroupMember -GroupObjectId $group.Id |
    Select-Object DisplayName, UserPrincipalName, UserType

Write-Host "Grupo: $($group.DisplayName)"
Write-Host "Membros ($($members.Count)):"
$members | Format-Table -AutoSize

# Filtrar apenas contas de usuario ativas (excluir contas de convidados)
$activeMembers = $members | Where-Object UserType -eq 'Member'
Write-Host "Membros ativos (sem convidados): $($activeMembers.Count)"

# Disponibilizar segredo como SecureString para uso posterior
$secureConn = ConvertTo-SecureString -String $secret -AsPlainText -Force
# $secureConn pode ser passado para Invoke-DbaQuery ou similar
Write-Host "String de conexao disponivel como SecureString."

# Encerrar sessao Azure
Disconnect-AzAccount | Out-Null
Write-Host "Sessao Azure encerrada."

Este script autentica via Managed Identity (ou faz fallback para login interativo), le uma string de conexao com seguranca do Azure Key Vault e consulta membros de grupos do Entra ID. Nenhuma senha e armazenada no script.

Armazenamento de Backup no Azure Blob

Um cenario tipico e o armazenamento automatizado de backups off-site no Azure Blob Storage. Com New-AzStorageContext, Set-AzStorageBlobContent e Remove-AzStorageBlob, um processo completo de gerenciamento de ciclo de vida de backup pode ser implementado em PowerShell: criar backup, enviar para o Azure, manter arquivos mais recentes que N dias, excluir os mais antigos. A autenticacao usa Managed Identity ou token SAS armazenado no Key Vault -- sem chave de conta de armazenamento em texto simples.

Monitoramento de Custos do Azure com PowerShell

Get-AzConsumptionUsageDetail e Get-AzCostManagementQuery retornam dados de consumo que podem ser agregados e relatados via PowerShell. Desenvolvi scripts que analisam custos diarios do Azure por tipo de recurso e assinatura e alertam automaticamente por email e mensagens Teams quando limites sao excedidos. Combinado com acoes de parar/desalocar VMs nao utilizadas acionadas pelo PowerShell, isso resultou em reducao mensuravel de custos para um cliente.

CI/CD com Jenkins e Azure DevOps

Integracao Continua e Deployment Continuo sao o contexto no qual os scripts PowerShell entregam seu valor total. Um script que um DBA executa manualmente e util. O mesmo script automaticamente acionado em cada commit Git -- construindo, testando, empacotando e implantando no ambiente alvo -- e infraestrutura como codigo. Sistemas CI/CD como Jenkins e Azure DevOps fornecem o framework; os scripts PowerShell formam a logica real de automacao.

Em uma organizacao publica de pesquisa, incorporei todo o processo de ETL e geracao de relatorios em um pipeline Jenkins: pacotes SSIS eram construidos, executados automaticamente em um banco de dados de teste, os testes tSQLt eram executados e, em caso de sucesso, o DACPAC era aplicado a producao. Scripts PowerShell tratavam todos os passos de deployment. Em um fabricante de maquinas industriais, o equivalente era um pipeline Azure DevOps com definicao YAML, mapeando o mesmo processo para a infraestrutura Azure.

Arquitetura de pipeline CI/CD para deployment SSDT: Git push aciona o build, MSBuild produz o DACPAC, testes tSQLt validam, PowerShell implanta de forma idempotente no ambiente alvo.

Pipeline Jenkins com Stages PowerShell

No Jenkins, um pipeline e tipicamente definido como um Jenkinsfile (Groovy). Cada stage pode invocar scripts PowerShell, arquivar resultados como artefatos e enviar notificacoes em falha ou sucesso. Estruturo pipelines Jenkins em stages claramente separados: Build (MSBuild/SSDT), Teste (tSQLt, Pester), Deploy (DACPAC), Notificar (email/Teams em falha ou sucesso). Essa estrutura torna o status do pipeline imediatamente visivel na interface Jenkins e permite solucao de problemas especificos.

Azure DevOps com Pipelines YAML

Os pipelines YAML do Azure DevOps sao declarativos, versionados e armazenados diretamente no repositorio Git. Prefiro pipelines multi-stage com ambientes explicitos e portais de deployment que exigem aprovacao manual antes do deployment em producao. Passos PowerShell em YAML sao definidos como script: ou task: powershell@2 e podem rodar em agentes hospedados no Azure ou self-hosted. Grupos de variaveis no Azure DevOps podem ser vinculados a segredos do Key Vault para que nenhum segredo aparea no codigo YAML.

• Jenkins: Jenkinsfile (Groovy) com stages PowerShell, arquivamento de artefatos
• Azure DevOps: pipelines YAML multi-stage, ambientes, portais de deployment
• Passos PowerShell: build, teste (tSQLt/Pester), deploy (DACPAC), notificacao
• Grupos de variaveis com integracao Key Vault: sem segredos no codigo
• Agentes self-hosted vs. hospedados Azure: trade-offs para deployments SQL Server
• Estrategias de branch: feature branches, branch main como gatilho de deployment

Tratamento de Erros, Logging e Idempotencia

O tratamento robusto de erros distingue um script de producao de um codigo descartavel. Desenvolvo scripts PowerShell segundo tres principios centrais: Fail-Fast para erros criticos (ErrorAction Stop, throw para estados invalidos), Graceful Degradation para erros nao criticos (try/catch por unidade, registrar e continuar), e Idempotencia -- o script pode rodar multiplas vezes e deixar o mesmo estado alvo a cada vez, sem criar duplicatas ou operacoes parciais.

O logging e a memoria do script. Registro cada passo com timestamp, nivel de severidade (INFO/WARN/ERROR), objeto afetado e detalhes de excecao onde aplicavel. Os logs sao gravados tanto em arquivos quanto via Write-Host para consoles CI/CD. Erros criticos acionam notificacoes adicionais por email ou Teams. Esse design significa que um incidente de producao pode ser analisado imediatamente com contexto completo, sem depender de logs de eventos do servidor ou recordacoes.

Padroes de Idempotencia em PowerShell

Idempotencia significa: verificar se o estado alvo ja foi alcancado antes de agir, e agir apenas se nao foi. Para operacoes de banco de dados: o objeto ja existe? A tabela ja tem a coluna correta? O job ja executou hoje? Esses padroes evitam entradas duplicadas, conflitos e estados inconsistentes quando scripts sao reiniciados apos falha ou executados em paralelo em ambientes CI/CD.

Padrao de Logging Estruturado

Em vez de chamadas ad hoc de Write-Host e Write-Error, uso uma funcao de log central que padroniza todas as saidas: timestamp, nivel (INFO/WARN/ERROR), nome do script, numero da linha e mensagem. Em ambientes CI/CD o mesmo log e gravado simultaneamente no console e em um arquivo de log arquivado como artefato de build. Cada execucao de pipeline e completamente rastrecavel, mesmo semanas apos a execucao.

• ErrorAction Stop: tratar erros de cmdlets como excecoes terminativas
• try/catch/finally: tratamento granular de erros por unidade de trabalho
• Idempotencia: padrao 'testar-depois-agir' antes de cada operacao que muda estado
• Logging estruturado: timestamp, nivel, contexto, detalhes de excecao
• Rollback de transacao: envolver mudancas de banco de dados em transacoes
• Logica de retry para erros transitorios (timeouts de rede, conflitos de lock)

Scripts de Self-Healing e Monitoramento

Scripts de monitoramento relatam problemas. Scripts de self-healing os resolvem. Esse nivel de automacao faz sentido onde os problemas sao conhecidos, recorrentes e seguramente resoluveis de forma automatica. Exemplos tipicos: um job do SQL Agent falhou e deve ser automaticamente reiniciado para padroes de erro especificos. Um log de transacao cresceu inesperadamente devido a um processo ETL fora de controle e deve ser reduzido apos remediacao. Uma VM Azure parou inesperadamente e deve ser iniciada automaticamente durante o horario comercial.

Desenvolvo scripts de self-healing com logica clara: verificar estado, tomar decisao, executar acao, registrar. A acao nunca deve ser cega -- cada correcao automatica e registrada, e apos mais de N repeticoes dentro de uma janela de tempo definida o script para de agir automaticamente e solicita intervencao humana. Essa camada de escalacao e critica para evitar loops de feedback infinitos.

Monitoramento Proativo de Espaco em Disco

Um cenario classico de self-healing e o gerenciamento de espaco em disco: bancos de dados crescem, arquivos de log enchem, caminhos de backup ficam cheios. Com cmdlets dbatools como Get-DbaDiskSpace e analise de espaco de log, alertas proativos podem ser construidos com base em limites, nao no ultimo kilobyte disponivel. Combinado com limpeza automatizada de arquivos de backup mais antigos e analise de espaco de log, resulta em um script que previne crises de espaco em disco em vez de apenas relata-las.

Monitoramento de Jobs do SQL Agent

Jobs falhos do SQL Agent podem ser consultados e analisados automaticamente com dbatools. Get-DbaAgentJobHistory retorna o historico de execucao de todos os jobs; Start-DbaAgentJob aciona uma reinicializacao manual. Em um loop de monitoramento simples -- executado como Tarefa Agendada do Windows ou job do SQL Agent a cada 15 minutos -- falhas transitorias conhecidas (interrupcao de rede, timeout de lock) podem ser resolvidas automaticamente por reinicializacao, enquanto falhas estruturais (bug de script, tabela ausente) sao escaladas imediatamente.

Assinatura de Scripts e Execution Policy

Em ambientes empresariais regulados, a execucao de scripts PowerShell nao assinados e frequentemente bloqueada por execution policy e regras de AppLocker. As execution policies AllSigned ou RemoteSigned exigem que os scripts sejam assinados por um certificado confiavel antes de poderem ser executados. Esse requisito nao e um obstaculo, mas uma medida de seguranca sensata: scripts assinados nao podem ser modificados sem deteccao, e sua procedencia e criptograficamente verificavel.

Assino scripts de producao com certificados de assinatura de codigo da infraestrutura PKI corporativa. O processo de assinatura pode ser integrado ao pipeline CI/CD: cada script que passou com sucesso pelo processo de build e automaticamente assinado com o certificado do agente de build e carregado como artefato assinado no repositorio de artefatos. Todos os scripts de producao sao, portanto, assinados automaticamente sem esforco manual.

Set-AuthenticodeSignature no Pipeline CI/CD

Set-AuthenticodeSignature e o cmdlet PowerShell para assinatura. Requer um certificado com Key Usage 'Code Signing'. No Azure DevOps, o certificado pode ser armazenado com seguranca no Key Vault e recuperado via cmdlets Az.KeyVault. Get-AuthenticodeSignature verifica a assinatura de um arquivo e pode servir como verificacao pre-deployment no pipeline.

Recomendacoes de Execution Policy

Para servidores de producao recomendo a execution policy AllSigned ou RemoteSigned, aplicada via Group Policy. Para ambientes de desenvolvimento, Bypass ou Unrestricted pode ser definido por escopo CurrentUser sem alterar a policy em nivel de servidor. Importante: execution policy nao e um mecanismo de seguranca contra atores maliciosos deliberados com direitos de admin local -- e uma guarda contra execucao acidental de scripts nao assinados por usuarios legitimos.

Abordagem de Colaboracao

O ponto de partida tipico para um projeto de automacao PowerShell e uma avaliacao: o que roda manualmente hoje? Onde ha friccao, erros ou perda de tempo? Que scripts ja existem e sao mantenidos, testados e controlados por versao? Essa analise leva tipicamente meio dia a um dia e produz uma lista priorizada de oportunidades de automacao ordenadas por esforco e beneficio.

Entao vem a implementacao: iterativa, com feedback antecipado. Desenvolvo scripts em unidades pequenas e testadas em vez de monolitos. Cada funcao e coberta por testes Pester antes de ser integrada ao pipeline. Essa abordagem reduz surpresas durante a primeira execucao em producao e facilita a manutencao pelas equipes internas apos meu projeto.

• Avaliacao: identificar processos manuais, inventariar scripts existentes
• Design: planejar estrutura de modulos, parametros, tratamento de erros, logging
• Implementacao: iterativa, com testes unitarios Pester para funcoes criticas
• Integracao: incorporacao CI/CD, scripts assinados, tarefas agendadas
• Documentacao: ajuda em comentarios, README, runbook de operacoes
• Transferencia: transferencia de conhecimento para a equipe interna, nao criacao de dependencia

Minha experiencia em ambientes regulados -- setor financeiro, administracao publica -- se traduz em cuidado especial com documentacao e rastreabilidade. Cada script recebe ajuda completa baseada em comentarios com autor, versao, historico de mudancas e exemplos de uso. Documento as operacoes em um breve runbook explicando como iniciar o script, como diagnosticar erros e o que fazer em caso de falha.

Servicos Tipicos em Automacao PowerShell

Meu espectro de servicos PowerShell vai de scripts individuais isolados a solucoes completas de automacao incorporadas em infraestrutura CI/CD existente. Dependendo da fase do projeto e dos requisitos, trato de areas especificas ou de toda a pilha de automacao.

• Inventario de parque de servidores e comparacao de configuracao com dbatools
• Automacao de deployment SSDT/DACPAC para ambientes Dev/Teste/Prod
• Exportacao de Excel com dados do DWH com ImportExcel (sem Microsoft Office no servidor)
• Azure PowerShell: gerenciamento Entra ID, integracao Key Vault, backup em Blob Storage
• Integracao CI/CD: Jenkinsfile Jenkins e pipelines YAML Azure DevOps
• Tratamento de erros, logging estruturado e idempotencia para scripts de producao
• Scripts de self-healing para problemas operacionais conhecidos e recorrentes
• Assinatura de scripts com certificados de assinatura de codigo e configuracao de execution policy
• Testes unitarios Pester para funcoes PowerShell criticas
• Transferencia de conhecimento e criacao de runbook para equipes internas
• Revisao de scripts existentes: seguranca, idempotencia, robustez, manutencao
• Suporte a migracao: portando scripts batch legados para modulos PowerShell modernos

Esses servicos nao sao isolados -- sua forca esta na combinacao. Um script de deployment SSDT rodando no sistema CI/CD, recuperando dados de conexao do Key Vault, registrando erros de forma estruturada e executando assinado e mais do que a soma de suas partes. E um modelo operacional completo, seguro e auditavel.

Oferecom automacao PowerShell tanto como topico independente quanto como complemento a projetos SQL Server e Azure. O maior valor frequentemente emerge quando processos manuais existentes -- deployment, relatorios, monitoramento -- sao sistematicamente automatizados dentro de um projeto mais longo, enquanto o projeto principal (construcao de DWH, migracao, performance) progride em paralelo.

Projetos de referencia anonimizados selecionados

Perguntas frequentes sobre automacao PowerShell