Skip to content

Commands

Every command and option, as printed by sql2devops <command> --help. This page is generated from the tool itself, version dev.

sql2devops approve

Record an approval for one package version in one environment.

  --automatic   for pipelines: approves on the strength of its own checks,
                with --evidence (in GitHub Actions the run URL is used when
                --evidence is not given). Counts for approval: automatic.
  (default)     a person's approval. Counts for approval: human when the
                person is listed in approvers and did not submit the version
                (unless allow_self_approval).

Approvals are signed events in the history, like everything else.

Usage:
  sql2devops approve <package> [flags]

Flags:
      --automatic                 a pipeline's approval based on its own checks
      --control-dir string        control repository folder (default $SQL2DEVOPS_CONTROL_DIR)
      --env string                environment to approve for
      --evidence string           why it is approved: test run URL, ticket, review
  -h, --help                      help for approve
      --project string            project of the package
      --signing-key-file string   private key file to sign events (default $SQL2DEVOPS_SIGNING_KEY)
      --version int               package version (default: latest submitted)

sql2devops deploy

Run a submitted package (its immutable copy) on one environment's database,
and record the execution in the database's sql2devops_history table and in
the control repository.

With a project.yaml, the environment's policy applies first: the previous
environment must have succeeded with the same version, and the required
approvals must exist. The database and its driver come from project.yaml.

Then both records are compared:
  - already applied: nothing runs (use --force to run again)
  - they disagree (database restored from a backup, package applied by hand
    or from another control repository): the deployment stops (use --force)
  - the last attempt failed: it runs again as a new attempt, when the
    environment allows it (rerun_after_failure, default true)

Only one deployment runs at a time on a database; others wait for the lock.
Every attempt, failed or forced, is recorded.

Usage:
  sql2devops deploy <package> [flags]

Flags:
      --control-dir string        control repository folder (default $SQL2DEVOPS_CONTROL_DIR)
  -d, --driver string             database engine (default: from project.yaml)
      --dsn-env string            variable with the connection string (default: from project.yaml, else SQL2DEVOPS_DSN)
      --env string                environment name, e.g. DEV, HML, PROD
      --force                     run even if already applied or if the records disagree (recorded; never bypasses the policy)
  -h, --help                      help for deploy
      --lock-timeout duration     how long to wait for another deployment on the same database (default 30m0s)
      --no-rerun                  refuse to run a version whose last attempt here failed
      --project string            project of the package
      --signing-key-file string   private key file to sign events (default $SQL2DEVOPS_SIGNING_KEY)
      --timeout duration          timeout for steps without their own (0 = no limit)
      --var-env stringToString    script variable to environment variable, e.g. senha_api=API_PASSWORD (overrides project.yaml) (default [])
      --version int               package version (default: latest submitted)

sql2devops emergency

Deploy a package to an environment without its prerequisite or approvals,
for incidents that cannot wait. Everything else still applies: the immutable
copy, the lock, the history table, the comparison with the database.

The execution is recorded as an emergency with its reason and ticket, and it
leaves follow-ups that 'status' shows until they are done:
  - a review by someone else ('sql2devops review')
  - the same version in the environments it skipped, through the normal flow

Who may run emergencies, whether a ticket is required and who may review
them is set in project.yaml (emergency:); by default anyone may.

A folder is accepted: it is submitted first, so the copy is kept.

Usage:
  sql2devops emergency <package | package-folder> [flags]

Flags:
      --control-dir string        control repository folder (default $SQL2DEVOPS_CONTROL_DIR)
  -d, --driver string             database engine (default: from project.yaml)
      --dsn-env string            variable with the connection string (default: from project.yaml, else SQL2DEVOPS_DSN)
      --env string                environment, e.g. PROD
      --force                     run even if already applied or if the records disagree (recorded; never bypasses the policy)
  -h, --help                      help for emergency
      --lock-timeout duration     how long to wait for another deployment on the same database (default 30m0s)
      --no-rerun                  refuse to run a version whose last attempt here failed
      --project string            project of the package
      --reason string             why this cannot wait (required; reviewers read it)
      --signing-key-file string   private key file to sign events (default $SQL2DEVOPS_SIGNING_KEY)
      --target string             target for a single-script folder without a manifest
      --ticket string             incident or change ticket
      --timeout duration          timeout for steps without their own (0 = no limit)
      --var-env stringToString    script variable to environment variable, e.g. senha_api=API_PASSWORD (overrides project.yaml) (default [])
      --version int               package version (default: latest submitted)

sql2devops exec

Run a single SQL script, batch by batch, on one connection.

The connection string is read from an environment variable (default
SQL2DEVOPS_DSN), never from a flag, so it does not end up in shell
history, process lists or pipeline logs.

Examples of connection strings:
  sqlserver://user:pass@host:1433?database=app
  postgres://user:pass@host:5432/app?sslmode=require

Usage:
  sql2devops exec <script.sql> [flags]

Flags:
  -d, --driver string                    database engine: postgres, sqlite, sqlserver
      --dry-run                          only show how the script would be split, do not connect
      --dsn-env string                   environment variable that holds the connection string (default "SQL2DEVOPS_DSN")
  -h, --help                             help for exec
      --sqlite-function stringToString   SQLite only: SQL function the application registers in code, with a fixed value, e.g. app_usuario=sql2devops (default [])
      --timeout duration                 maximum time for the whole script, e.g. 30s or 10m (0 = no limit)
      --var-env stringToString           script variable to environment variable, e.g. senha_api=API_PASSWORD (default SQL2DEVOPS_VAR_<NAME>) (default [])

sql2devops history

Show what happened to a project's packages

Usage:
  sql2devops history [flags]

Flags:
      --control-dir string        control repository folder (default $SQL2DEVOPS_CONTROL_DIR)
      --emergencies               only emergencies, manual runs and their reviews
      --errors                    also print the full failure reports
  -h, --help                      help for history
      --package string            only this package
      --project string            project to show
      --signing-key-file string   private key file to sign events (default $SQL2DEVOPS_SIGNING_KEY)

sql2devops key

Manage signing keys

Usage:
  sql2devops key [command]

Available Commands:
  generate    Create a signing key and register its public part

Flags:
  -h, --help   help for key

Use "sql2devops key [command] --help" for more information about a command.

sql2devops key generate

Create an ed25519 key pair. The private key is written to --out (keep it
secret: store it as a pipeline secret, e.g. SQL2DEVOPS_SIGNING_KEY). The public key is
registered in the control repository, so verify can check signatures.

Usage:
  sql2devops key generate [flags]

Flags:
      --control-dir string        control repository folder (default $SQL2DEVOPS_CONTROL_DIR)
  -h, --help                      help for generate
      --name string               who or what uses the key, e.g. github-actions or a person
      --out string                file to write the private key to
      --signing-key-file string   private key file to sign events (default $SQL2DEVOPS_SIGNING_KEY)

sql2devops license

Without a license, the free edition applies: packages with up to 2 scripts,
projects with up to 2 environments, no web interface. A license removes
these limits.

The license is looked up in the environment variable SQL2DEVOPS_LICENSE (the license
text, for pipelines), then in the file named by SQL2DEVOPS_LICENSE_FILE, then in the
file written by 'sql2devops license install'. It is checked offline.

Usage:
  sql2devops license [command]

Available Commands:
  install     Check a license and store it for this user
  show        Show the edition in effect

Flags:
  -h, --help   help for license

Use "sql2devops license [command] --help" for more information about a command.

sql2devops license install

Check a license and store it for this user

Usage:
  sql2devops license install <license-file | -> [flags]

Flags:
  -h, --help   help for install

sql2devops license show

Show the edition in effect

Usage:
  sql2devops license show [flags]

Flags:
  -h, --help   help for show

sql2devops package

Check, submit and run SQL packages

Usage:
  sql2devops package [command]

Aliases:
  package, pkg

Available Commands:
  check       Check a package's structure without connecting to a database
  run         Run a package's steps in order, rolling back on failure
  submit      Store an immutable copy of a package in the control directory

Flags:
  -h, --help   help for package

Use "sql2devops package [command] --help" for more information about a command.

sql2devops package check

Check a package: manifest fields, step files and rollbacks present,
paths inside the package, file encodings. With --driver, scripts are also
split with that engine's rules, which catches unterminated strings, comments
or $$ bodies. The SQL itself is not validated.

Usage:
  sql2devops package check <package-folder> [flags]

Flags:
  -d, --driver string    also split scripts with this engine's rules
  -h, --help             help for check
      --project string   project for a package without a manifest
      --target string    target for a package without a manifest

sql2devops package run

Run a package step by step on one database.

When a step fails and on_error is "rollback" (the default), the rollback of
the failed step runs first, then the rollbacks of the completed steps, newest
first. With on_error "stop", nothing is rolled back.

The folder can be a package source or a stored copy from the control
directory. The connection string is read from an environment variable.

Usage:
  sql2devops package run <package-folder> [flags]

Flags:
  -d, --driver string                    database engine: postgres, sqlite, sqlserver
      --dsn-env string                   environment variable that holds the connection string (default "SQL2DEVOPS_DSN")
  -h, --help                             help for run
      --project string                   project for a package without a manifest
      --sqlite-function stringToString   SQLite only: SQL function the application registers in code, with a fixed value, e.g. app_usuario=sql2devops (default [])
      --target string                    target for a package without a manifest
      --timeout duration                 timeout for steps without their own (0 = no limit)
      --var-env stringToString           script variable to environment variable, e.g. senha_api=API_PASSWORD (default SQL2DEVOPS_VAR_<NAME>) (default [])

sql2devops package submit

Store an immutable copy of a package. Every environment later runs that
copy, so production runs exactly what was tested.

Submitting the same content again does nothing. A version is never
overwritten: to change a package, raise its version.

Usage:
  sql2devops package submit <package-folder> [flags]

Flags:
      --auto-version              ignore the manifest version: reuse the latest one when the content is the same, else the next (for packages a pipeline generates)
      --control-dir string        control repository folder (default $SQL2DEVOPS_CONTROL_DIR)
  -h, --help                      help for submit
      --project string            project for a package without a manifest
      --signing-key-file string   private key file to sign events (default $SQL2DEVOPS_SIGNING_KEY)
      --source string             where the package came from (default: GitHub Actions repository and commit, when available)
      --target string             target for a package without a manifest

sql2devops project

Configure projects: environments, databases and policies

Usage:
  sql2devops project [command]

Available Commands:
  check       Validate a project's project.yaml
  init        Create a project.yaml to edit

Flags:
  -h, --help   help for project

Use "sql2devops project [command] --help" for more information about a command.

sql2devops project check

Validate a project's project.yaml

Usage:
  sql2devops project check <project> [flags]

Flags:
      --control-dir string        control repository folder (default $SQL2DEVOPS_CONTROL_DIR)
  -h, --help                      help for check
      --signing-key-file string   private key file to sign events (default $SQL2DEVOPS_SIGNING_KEY)

sql2devops project init

Create projects/<project>/project.yaml in the control repository with the
given environments in promotion order. The first needs no approval, the last
(with three or more) needs a human approval, the ones in between an
automatic one. Edit the approvers and the connection-string variables, then
commit the change.

Usage:
  sql2devops project init <project> [flags]

Flags:
      --control-dir string        control repository folder (default $SQL2DEVOPS_CONTROL_DIR)
  -d, --driver string             database engine: postgres, sqlite, sqlserver
      --envs string               environments in promotion order (free edition: DEV,PROD) (default "DEV,HML,PROD")
  -h, --help                      help for init
      --signing-key-file string   private key file to sign events (default $SQL2DEVOPS_SIGNING_KEY)

sql2devops promote

Deploy the package to the first environment, in project.yaml order, where
this version has not succeeded yet. Same rules as deploy.

Usage:
  sql2devops promote <package> [flags]

Flags:
      --control-dir string        control repository folder (default $SQL2DEVOPS_CONTROL_DIR)
  -d, --driver string             database engine (default: from project.yaml)
      --dsn-env string            variable with the connection string (default: from project.yaml, else SQL2DEVOPS_DSN)
      --force                     run even if already applied or if the records disagree (recorded; never bypasses the policy)
  -h, --help                      help for promote
      --lock-timeout duration     how long to wait for another deployment on the same database (default 30m0s)
      --no-rerun                  refuse to run a version whose last attempt here failed
      --project string            project of the package
      --signing-key-file string   private key file to sign events (default $SQL2DEVOPS_SIGNING_KEY)
      --timeout duration          timeout for steps without their own (0 = no limit)
      --var-env stringToString    script variable to environment variable, e.g. senha_api=API_PASSWORD (overrides project.yaml) (default [])
      --version int               package version (default: latest submitted)

sql2devops record-manual

Record that a package was run by hand (a DBA in a hurry, a script run in a
query window), so the history stays complete. Nothing is executed.

The record goes to the database's sql2devops_history table (unless
--skip-database) and to the control repository, as a manual execution with
the same follow-ups as an emergency: a review and the reconciliation of the
environments it skipped.

Usage:
  sql2devops record-manual <package | package-folder> [flags]

Flags:
      --control-dir string        control repository folder (default $SQL2DEVOPS_CONTROL_DIR)
  -d, --driver string             database engine (default: from project.yaml)
      --dsn-env string            variable with the connection string (default: from project.yaml)
      --env string                environment where it ran
      --executed-at string        when it ran, RFC 3339 (default: now)
  -h, --help                      help for record-manual
      --project string            project of the package
      --reason string             why it was run by hand (required)
      --signing-key-file string   private key file to sign events (default $SQL2DEVOPS_SIGNING_KEY)
      --skip-database             record only in the control repository
      --status string             outcome: succeeded, failed_rolled_back, failed_not_rolled_back, failed_rollback_failed (default "succeeded")
      --target string             target for a single-script folder without a manifest
      --ticket string             incident or change ticket
      --version int               package version (default: latest submitted)

sql2devops review

Record the review of the emergency or manual executions that are waiting
for one. The reviewer cannot be the person who ran them; project.yaml
(emergency: reviewers) can restrict who reviews. Without --package and
--env, lists what is waiting.

Usage:
  sql2devops review [flags]

Flags:
      --control-dir string        control repository folder (default $SQL2DEVOPS_CONTROL_DIR)
      --env string                environment of the execution
  -h, --help                      help for review
      --notes string              what was checked
      --package string            package to review
      --project string            project
      --signing-key-file string   private key file to sign events (default $SQL2DEVOPS_SIGNING_KEY)

sql2devops status

Show, for the latest submitted version of every package, its state in each
environment and what it needs to move on:

  ok         succeeded here
  FAILED x2  the last of 2 attempts failed
  approved   approved here, not deployed yet
  v1 ok      an older version is applied here; the latest is not
  -          nothing yet

Usage:
  sql2devops status [flags]

Flags:
      --control-dir string        control repository folder (default $SQL2DEVOPS_CONTROL_DIR)
  -h, --help                      help for status
      --project string            project to show
      --signing-key-file string   private key file to sign events (default $SQL2DEVOPS_SIGNING_KEY)

sql2devops ui

Serve a read-only web interface over the control repository and open it in
the browser: every project's packages across its environments, follow-ups
after emergencies, the history timeline with filters, each execution with its
steps and failure report, the stored packages with their SQL, and the
history check (verify).

It listens on 127.0.0.1 only. The link printed at start carries a session
key; without it, the pages refuse to open. Stop it with Ctrl+C.

Usage:
  sql2devops ui [flags]

Flags:
      --control-dir string        control repository folder (default $SQL2DEVOPS_CONTROL_DIR)
  -h, --help                      help for ui
      --no-browser                only print the link
      --port int                  port to listen on (default: a free one)
      --signing-key-file string   private key file to sign events (default $SQL2DEVOPS_SIGNING_KEY)

sql2devops verify

Check every project's history: the sequence has no gaps, each event points
at the hash of the one before, each hash matches the event's content, each
signature is valid for a registered key, and every stored package copy still
matches its submitted hash.

Unsigned events are reported as warnings; with --strict they are errors.

Usage:
  sql2devops verify [flags]

Flags:
      --control-dir string        control repository folder (default $SQL2DEVOPS_CONTROL_DIR)
  -h, --help                      help for verify
      --signing-key-file string   private key file to sign events (default $SQL2DEVOPS_SIGNING_KEY)
      --strict                    treat unsigned events as errors

sql2devops version

Print version information

Usage:
  sql2devops version [flags]

Flags:
  -h, --help   help for version