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