Skip to content

Commit 477a682

Browse files
nvarscarnvarscar
authored
Merge pull request #60 from sqlcollaborative/development
Minor updates to the Invoke-query and docs
2 parents 2190934 + 8a5a92b commit 477a682

File tree

4 files changed

+269
-182
lines changed

4 files changed

+269
-182
lines changed

‎README.md

Lines changed: 11 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -13,12 +13,15 @@ The deployment functionality of the module is provided by [DbUp](https://github.
1313
Currently supported RDBMS:
1414
* SQL Server
1515
* Oracle
16+
* PostgreSQL
17+
* MySQL
1618

1719
## Features
1820
The most notable features of the module:
1921

2022
* Reliably deploy your scripts in a consistent and repeatable manner
2123
* Perform ad-hoc deployments with highly customizable deployment parameters
24+
* Run ad-hoc queries to any supported RDBMS on both Windows and Linux
2225
* Create ready-to-deploy versioned packages in a single command
2326
* Brings along all features of CI/CD pipelining functionality: builds, artifact management, deployment
2427
* Roll back the script (or a whole deployment!) in case of errors
@@ -53,7 +56,7 @@ Install-Module dbops
5356
* Versioned package deployment (e.g. Octopus Deployment)
5457

5558
## Examples
56-
### Simple deployment
59+
### Simple deployments and ad-hoc queries
5760

5861
Perform plain-text script deployments using a single command:
5962

@@ -65,6 +68,9 @@ Example code:
6568
```powershell
6669
# Ad-hoc deployment of the scripts from a folder myscripts
6770
Install-DBOSqlScript -ScriptPath C:\temp\myscripts -SqlInstance server1 -Database MyDB
71+
72+
# Execute a list of files as an Ad-hoc query
73+
Get-ChildItem C:\temp\myscripts | Invoke-DBOQuery -SqlInstance server1 -Database MyDB
6874
```
6975
### Package management
7076

@@ -153,7 +159,6 @@ Publish-DBOPackageArtifact -Path myPackage.zip -Repository \\data\repo
153159
154160
# Retrieve the latest package version from the repository and install it
155161
Get-DBOPackageArtifact -Path myPackage.zip -Repository \\data\repo | Install-DBOPackage -Server MyDBServer -Database MyDB
156-
157162
```
158163

159164
## Planned for future releases
@@ -162,7 +167,10 @@ Get-DBOPackageArtifact -Path myPackage.zip -Repository \\data\repo | Install-DBO
162167
* Support for other RDBMS (eventually, everything that DbUp libraries can talk with)
163168
* Integration with unit tests (tSQLt/Pester/...?)
164169
* Module for Ansible (right now can still be used as a powershell task)
165-
* Linux support
166170
* SQLCMD support
167171
* Deployments to multiple databases at once
168172
* Optional rollback scripts
173+
174+
## Contacts
175+
Submitting issues - [GitHub issues](https://github.com/sqlcollaborative/dbops/issues)
176+
SQLCommunity Slack: https://sqlcommunity.slack.com #devops or @nvarscar

‎docs/index.md

Lines changed: 68 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -7,20 +7,19 @@ The deployment functionality of the module is provided by [DbUp](https://github.
77
Currently supported RDBMS:
88
* SQL Server
99
* Oracle
10+
* PostgreSQL
11+
* MySQL
1012

1113
## Features
1214
The most notable features of the module:
1315

14-
* No scripting experience required - the module is designed around usability and functionality
15-
* Introduces an option to aggregate source scripts from multiple sources into a single ready-to-deploy file
16-
* CI/CD pipelining functionality: builds, artifact management, deployment
17-
* Can detect new/changed files in your source code folder and generate a new deployment build based on those files
18-
* Introduces optional internal build system: older builds are kept inside the deployment package ensuring smooth and errorless deployments
19-
* Reliably deploys the scripts in a consistent manner - all the scripts are executed in alphabetical order one build at a time
20-
* Can be deployed without the module installed in the system - module itself is integrated into the deployment package
21-
* Transactionality of the deployments/migrations: every build can be deployed as a part of a single transaction, rolling back unsuccessful deployments
22-
* Dynamically change your code based on custom variables - use `#{customVarName}` tokens to define variables inside the scripts or execution parameters
23-
* Packages are fully compatible with Octopus Deploy deployments: all packages are in essence zip archives with Deploy.ps1 file that initiates deployment
16+
* Reliably deploy your scripts in a consistent and repeatable manner
17+
* Perform ad-hoc deployments with highly customizable deployment parameters
18+
* Run ad-hoc queries to any supported RDBMS on both Windows and Linux
19+
* Create ready-to-deploy versioned packages in a single command
20+
* Brings along all features of CI/CD pipelining functionality: builds, artifact management, deployment
21+
* Roll back the script (or a whole deployment!) in case of errors
22+
* Dynamically change your code based on custom variables using `#{customVarName}` tokens
2423

2524

2625
## System requirements
@@ -48,16 +47,39 @@ Install-Module dbops
4847
* Delivering new version of the database schema in a consistent manner to multiple environments
4948
* Build/Test/Deploy scenarios inside the Continuous Integration/Continuous Delivery pipeline
5049
* Dynamic deployment based on modified files in the source folder
50+
* Versioned package deployment (e.g. Octopus Deployment)
5151

5252
## Examples
53-
### Simple deployment
53+
54+
### Simple deployments and ad-hoc queries
55+
56+
Perform plain-text script deployments using a single command:
57+
58+
[![Invoke-DBODeployment](https://img.youtube.com/vi/PdMCk0Wa-FA/0.jpg)](http://www.youtube.com/watch?v=PdMCk0Wa-FA)<br/>
59+
<small>(click to open the video)</small>
60+
61+
Example code:
62+
5463
```powershell
55-
# Quick deployment without tracking deployment history
56-
Install-DBOSqlScript -ScriptPath C:\temp\myscripts -SqlInstance server1 -Database MyDB -SchemaVersionTable $null
64+
# Ad-hoc deployment of the scripts from a folder myscripts
65+
Install-DBOSqlScript -ScriptPath C:\temp\myscripts -SqlInstance server1 -Database MyDB
66+
67+
# Execute a list of files as an Ad-hoc query
68+
Get-ChildItem C:\temp\myscripts | Invoke-DBOQuery -SqlInstance server1 -Database MyDB
5769
```
5870
### Package management
71+
72+
<img src="https://sqlcollaborative.github.io/dbops/img/dbops-package.jpg" alt="dbops packages" width="800"/>
73+
74+
Each package consists of multiple builds and can be easily deployed to the database, ensuring that each build is deployed in proper order and only once.
75+
76+
[![Add-DBOBuild](https://img.youtube.com/vi/SasXV9Sz7gs/0.jpg)](http://www.youtube.com/watch?v=SasXV9Sz7gs)<br/>
77+
<small>(click to open the video)</small>
78+
79+
Example code:
80+
5981
```powershell
60-
# Deployment using packages & builds with keeping track of deployment history in the SchemaVersions table
82+
# Deployment using packaging system
6183
New-DBOPackage Deploy.zip -ScriptPath C:\temp\myscripts | Install-DBOPackage -SqlInstance server1 -Database MyDB
6284
6385
# Create new deployment package with predefined configuration and deploy it replacing #{dbName} tokens with corresponding values
@@ -66,21 +88,32 @@ Install-DBOPackage MyPackage.zip -Variables @{ dbName = 'myDB' }
6688
6789
# Adding builds to the package
6890
Add-DBOBuild Deploy.zip -ScriptPath .\myscripts -Type Unique -Build 2.0
69-
Get-ChildItem .\myscripts | Add-DBOBuild Deploy.zip -Type New,Modified -Build 3.0\
91+
Get-ChildItem .\myscripts | Add-DBOBuild Deploy.zip -Type New,Modified -Build 3.0
7092
7193
# Install package using internal script Deploy.ps1 - to use when module is not installed locally
7294
Expand-Archive Deploy.zip '.\MyTempFolder'
7395
.\MyTempFolder\Deploy.ps1 -SqlInstance server1 -Database MyDB
7496
```
7597
### Configurations and defaults
98+
99+
There are multiple configuration options available, including:
100+
* Configuring default settings
101+
* Specifying runtime parameters
102+
* Using configuration files
103+
104+
[![Get-DBOConfig](https://img.youtube.com/vi/JRwNyiMyyes/0.jpg)](http://www.youtube.com/watch?v=JRwNyiMyyes)<br/>
105+
<small>(click to open the video)</small>
106+
107+
Example code:
108+
76109
```powershell
77110
# Setting deployment options within the package to be able to deploy it without specifying options
78-
Update-DBOConfig Deploy.zip -Configuration @{ DeploymentMethod = 'SingleTransaction'; SqlInstance = 'localhost'; DatabaseName = 'MyDb2' }
111+
Update-DBOConfig Deploy.zip -Configuration @{ DeploymentMethod = 'SingleTransaction'; SqlInstance = 'localhost'; Database = 'MyDb2' }
79112
Install-DBOPackage Deploy.zip
80113
81114
# Generating config files and using it later as a deployment template
82-
(Get-DBOConfig -Configuration @{ DeploymentMethod = 'SingleTransaction'; SqlInstance = 'devInstance'; DatabaseName = 'MyDB' }).SaveToFile('.\dev.json')
83-
(Get-DBOConfig -Path '.\dev.json' -Configuration @{ SqlInstance = 'prodInstance' }).SaveToFile('.\prod.json')
115+
New-DBOConfig -Configuration @{ DeploymentMethod = 'SingleTransaction'; SqlInstance = 'devInstance'; Database = 'MyDB' } | Export-DBOConfig '.\dev.json'
116+
Get-DBOConfig -Path '.\dev.json' -Configuration @{ SqlInstance = 'prodInstance' } | Export-DBOConfig '.\prod.json'
84117
Install-DBOPackage Deploy.zip -ConfigurationFile .\dev.json
85118
86119
# Invoke package deployment using custom connection string
@@ -92,10 +125,25 @@ Install-DBOPackage -Path Deploy.zip -Server OracleDB -ConnectionType Oracle
92125
# Get a list of all the default settings
93126
Get-DBODefaultSetting
94127
95-
# Change the default SchemaVersionTable setting to null, disabling the deployment logging by default
128+
# Change the default SchemaVersionTable setting to null, disabling the deployment journalling by default
96129
Set-DBODefaultSetting -Name SchemaVersionTable -Value $null
130+
131+
# Reset SchemaVersionTable setting back to its default value
132+
Reset-DBODefaultSetting -Name SchemaVersionTable
97133
```
98134
### CI/CD features
135+
136+
dbops CI/CD flow assumes that each package version is built only once and deployed onto every single environment. The successfull builds should make their way as artifacts into the artifact storage, from which they would be pulled again to add new builds into the package during the next iteration.
137+
138+
<img src="https://sqlcollaborative.github.io/dbops/img/ci-cd-flow.jpg" alt="CI-CD flow" width="800"/>
139+
140+
CI/CD capabilities of the module enable user to integrate SQL scripts into a package file using a single command and to store packages in a versioned package repository.
141+
142+
[![Invoke-DBOPackageCI](https://img.youtube.com/vi/A6EwiHM9wE8/0.jpg)](http://www.youtube.com/watch?v=A6EwiHM9wE8)<br/>
143+
<small>(click to open the video)</small>
144+
145+
Example code:
146+
99147
```powershell
100148
# Invoke CI/CD build of the package MyPackage.zip using scripts from the source folder .\Scripts
101149
# Each execution of the command will only pick up new files from the ScriptPath folder
@@ -106,7 +154,6 @@ Publish-DBOPackageArtifact -Path myPackage.zip -Repository \\data\repo
106154
107155
# Retrieve the latest package version from the repository and install it
108156
Get-DBOPackageArtifact -Path myPackage.zip -Repository \\data\repo | Install-DBOPackage -Server MyDBServer -Database MyDB
109-
110157
```
111158

112159
## Planned for future releases
@@ -115,11 +162,10 @@ Get-DBOPackageArtifact -Path myPackage.zip -Repository \\data\repo | Install-DBO
115162
* Support for other RDBMS (eventually, everything that DbUp libraries can talk with)
116163
* Integration with unit tests (tSQLt/Pester/...?)
117164
* Module for Ansible (right now can still be used as a powershell task)
118-
* Linux support
119165
* SQLCMD support
120166
* Deployments to multiple databases at once
121167
* Optional rollback scripts
122168

123169
## Contacts
124170
Submitting issues - [GitHub issues](https://github.com/sqlcollaborative/dbops/issues)
125-
SQLCommunity Slack: https://sqlcommunity.slack.com #devops or @nvarscar
171+
SQLCommunity Slack: https://sqlcommunity.slack.com #devops or @nvarscar

0 commit comments

Comments
 (0)