|
| 1 | +| master | development | |
| 2 | +|---|---| |
| 3 | +| [](https://ci.appveyor.com/project/nvarscar/powerup/branch/master) | [](https://ci.appveyor.com/project/nvarscar/powerup/branch/development) | |
| 4 | + |
| 5 | + |
| 6 | +# DBOps |
| 7 | +DBOps is a Powershell module that provides Continuous Integration/Continuous Deployment capabilities for SQL database deployments. In addition to easy-to-use deployment functions, it provides tracking functionality, ensuring that each script is deployed only once and in due order. It will also grant you with ability to organize scripts into builds and deploy them in a repeatable manner on top of any previously deployed version. |
| 8 | + |
| 9 | +The deployment functionality of the module is provided by [DbUp](https://github.com/DbUp/DbUp) .Net library, which has proven its flexibility and reliability during deployments. |
| 10 | + |
| 11 | +Currently supported RDBMS: |
| 12 | +* SQL Server |
| 13 | +* Oracle |
| 14 | + |
| 15 | +## Features |
| 16 | +The most notable features of the module: |
| 17 | + |
| 18 | +* No scripting experience required - the module is designed around usability and functionality |
| 19 | +* Introduces an option to aggregate source scripts from multiple sources into a single ready-to-deploy file |
| 20 | +* CI/CD pipelining functionality: builds, artifact management, deployment |
| 21 | +* Can detect new/changed files in your source code folder and generate a new deployment build based on those files |
| 22 | +* Introduces optional internal build system: older builds are kept inside the deployment package ensuring smooth and errorless deployments |
| 23 | +* Reliably deploys the scripts in a consistent manner - all the scripts are executed in alphabetical order one build at a time |
| 24 | +* Can be deployed without the module installed in the system - module itself is integrated into the deployment package |
| 25 | +* Transactionality of the deployments/migrations: every build can be deployed as a part of a single transaction, rolling back unsuccessful deployments |
| 26 | +* Dynamically change your code based on custom variables - use `#{customVarName}` tokens to define variables inside the scripts or execution parameters |
| 27 | +* Packages are fully compatible with Octopus Deploy deployments: all packages are in essence zip archives with Deploy.ps1 file that initiates deployment |
| 28 | + |
| 29 | + |
| 30 | +## System requirements |
| 31 | + |
| 32 | +* Powershell 5.0 or higher |
| 33 | + |
| 34 | +## Installation |
| 35 | +### Using git |
| 36 | +```powershell |
| 37 | +git clone https://github.com/sqlcollaborative/dbops.git dbops |
| 38 | +Import-Module .\dbops |
| 39 | +``` |
| 40 | +Make sure to have the following modules installed as well: |
| 41 | +- [PSFramework](https://github.com/PowershellFrameworkCollective/psframework) |
| 42 | +- [ZipHelper](https://www.powershellgallery.com/packages/ziphelper) - only if you intend to run module tests |
| 43 | + |
| 44 | +### Using PSGallery (Powershell 5+) |
| 45 | +```powershell |
| 46 | +Install-Module dbops |
| 47 | +``` |
| 48 | + |
| 49 | +## Usage scenarios |
| 50 | + |
| 51 | +* Ad-hoc deployments of any scale without manual code execution |
| 52 | +* Delivering new version of the database schema in a consistent manner to multiple environments |
| 53 | +* Build/Test/Deploy scenarios inside the Continuous Integration/Continuous Delivery pipeline |
| 54 | +* Dynamic deployment based on modified files in the source folder |
| 55 | + |
| 56 | +## Examples |
| 57 | +### Simple deployment |
| 58 | +```powershell |
| 59 | +# Quick deployment without tracking deployment history |
| 60 | +Invoke-DBODeployment -ScriptPath C:\temp\myscripts -SqlInstance server1 -Database MyDB -SchemaVersionTable $null |
| 61 | +``` |
| 62 | +### Package management |
| 63 | +```powershell |
| 64 | +# Deployment using packages & builds with keeping track of deployment history in the SchemaVersions table |
| 65 | +New-DBOPackage Deploy.zip -ScriptPath C:\temp\myscripts | Install-DBOPackage -SqlInstance server1 -Database MyDB |
| 66 | +
|
| 67 | +# Create new deployment package with predefined configuration and deploy it replacing #{dbName} tokens with corresponding values |
| 68 | +New-DBOPackage -Path MyPackage.zip -ScriptPath .\Scripts -Configuration @{ Database = '#{dbName}'; ConnectionTimeout = 5 } |
| 69 | +Install-DBOPackage MyPackage.zip -Variables @{ dbName = 'myDB' } |
| 70 | +
|
| 71 | +# Adding builds to the package |
| 72 | +Add-DBOBuild Deploy.zip -ScriptPath .\myscripts -Type Unique -Build 2.0 |
| 73 | +Get-ChildItem .\myscripts | Add-DBOBuild Deploy.zip -Type New,Modified -Build 3.0\ |
| 74 | +
|
| 75 | +# Install package using internal script Deploy.ps1 - to use when module is not installed locally |
| 76 | +Expand-Archive Deploy.zip '.\MyTempFolder' |
| 77 | +.\MyTempFolder\Deploy.ps1 -SqlInstance server1 -Database MyDB |
| 78 | +``` |
| 79 | +### Configurations and defaults |
| 80 | +```powershell |
| 81 | +# Setting deployment options within the package to be able to deploy it without specifying options |
| 82 | +Update-DBOConfig Deploy.zip -Configuration @{ DeploymentMethod = 'SingleTransaction'; SqlInstance = 'localhost'; DatabaseName = 'MyDb2' } |
| 83 | +Install-DBOPackage Deploy.zip |
| 84 | +
|
| 85 | +# Generating config files and using it later as a deployment template |
| 86 | +(Get-DBOConfig -Configuration @{ DeploymentMethod = 'SingleTransaction'; SqlInstance = 'devInstance'; DatabaseName = 'MyDB' }).SaveToFile('.\dev.json') |
| 87 | +(Get-DBOConfig -Path '.\dev.json' -Configuration @{ SqlInstance = 'prodInstance' }).SaveToFile('.\prod.json') |
| 88 | +Install-DBOPackage Deploy.zip -ConfigurationFile .\dev.json |
| 89 | +
|
| 90 | +# Invoke package deployment using custom connection string |
| 91 | +Install-DBOPackage -Path Deploy.zip -ConnectionString 'Server=myServerAddress;Database=myDataBase;Trusted_Connection=True;' |
| 92 | +
|
| 93 | +# Invoke package deployment to an Oracle database OracleDB |
| 94 | +Install-DBOPackage -Path Deploy.zip -Server OracleDB -ConnectionType Oracle |
| 95 | +
|
| 96 | +# Get a list of all the default settings |
| 97 | +Get-DBODefaultSetting |
| 98 | +
|
| 99 | +# Change the default SchemaVersionTable setting to null, disabling the deployment logging by default |
| 100 | +Set-DBODefaultSetting -Name SchemaVersionTable -Value $null |
| 101 | +``` |
| 102 | +### CI/CD features |
| 103 | +```powershell |
| 104 | +# Invoke CI/CD build of the package MyPackage.zip using scripts from the source folder .\Scripts |
| 105 | +# Each execution of the command will only pick up new files from the ScriptPath folder |
| 106 | +Invoke-DBOPackageCI -Path MyPackage.zip -ScriptPath .\Scripts -Version 1.0 |
| 107 | +
|
| 108 | +# Store the package in a DBOps package repository in a folder \\data\repo |
| 109 | +Publish-DBOPackageArtifact -Path myPackage.zip -Repository \\data\repo |
| 110 | +
|
| 111 | +# Retrieve the latest package version from the repository and install it |
| 112 | +Get-DBOPackageArtifact -Path myPackage.zip -Repository \\data\repo | Install-DBOPackage -Server MyDBServer -Database MyDB |
| 113 | +
|
| 114 | +``` |
| 115 | + |
| 116 | +## Planned for future releases |
| 117 | + |
| 118 | +* Code analysis: know what kind of code makes its way into the package. Will find hidden sysadmin grants, USE statements and other undesired statements |
| 119 | +* Support for other RDBMS (eventually, everything that DbUp libraries can talk with) |
| 120 | +* Integration with unit tests (tSQLt/Pester/...?) |
| 121 | +* Module for Ansible (right now can still be used as a powershell task) |
| 122 | +* Linux support |
| 123 | +* SQLCMD support |
| 124 | +* Deployments to multiple databases at once |
| 125 | +* Optional rollback scripts |
0 commit comments