Skip to content

Getting started

This page takes you from nothing to a package deployed to two environments, with its history recorded.

1. Install

Get your free download key at sql2devops.com/download, then:

$env:SQL2DEVOPS_DOWNLOAD_KEY="s2dk_..."; irm https://sql2devops.com/install.ps1 | iex

It installs for your user (no administrator rights) in %LOCALAPPDATA%\Programs\Sql2DevOps and adds it to your PATH.

curl -fsSL https://sql2devops.com/install.sh | SQL2DEVOPS_DOWNLOAD_KEY=s2dk_... sh

It installs in ~/.local/share/sql2devops/<version> and links ~/.local/bin/sql2devops.

Both installers check the archive against the published SHA-256 checksums. Check the result:

sql2devops version

2. Run a script

The connection string always comes from an environment variable, never from a command-line flag, so it does not end up in logs or shell history.

export SQL2DEVOPS_DSN='postgres://user:password@localhost:5432/app?sslmode=disable'
sql2devops exec -d postgres --dry-run script.sql   # shows how the script is split
sql2devops exec -d postgres script.sql

3. Create a control repository

The control repository keeps the submitted packages and the history. It is any Git repository your pipelines can push to; an empty private repository is a good start.

git clone git@github.com:your-org/sql-control.git
export SQL2DEVOPS_CONTROL_DIR=$PWD/sql-control
sql2devops key generate --name ci --out ~/ci.key
export SQL2DEVOPS_SIGNING_KEY="$(cat ~/ci.key)"

Keep ci.key as a secret of your pipeline. Its public part is registered in the control repository, so anyone can verify the history.

5. Describe the project

sql2devops project init finance -d postgres --envs DEV,PROD

Edit projects/finance/project.yaml in the control repository (approvers, the environment variables that hold each connection string), then commit it. See Projects and environments.

6. Write a package

CHG-1001/
  sql2devops.yaml
  01-rates.sql
  rollback/01-rates.sql
# sql2devops.yaml
package: CHG-1001
project: finance
target: finance-db
steps:
  - file: 01-rates.sql
    type: ddl
    rollback: rollback/01-rates.sql

7. Submit and promote

sql2devops package check -d postgres ./CHG-1001
sql2devops package submit ./CHG-1001
sql2devops promote CHG-1001 --project finance     # runs in DEV
sql2devops approve CHG-1001 --project finance --env PROD
sql2devops promote CHG-1001 --project finance     # runs in PROD
sql2devops status --project finance
PACKAGE    VERSION   DEV   PROD   NEXT
CHG-1001   v1        ok    ok     done

From here, put the same commands in your pipeline.