Documentation

Modules

Changes for version 0.990

  • New Features
    • Added new command and feature: `target`. Use it to manage multiple database targets, each with an associated URI and, optionally, a registry name and command-line client. Inspired by Git remotes.
    • Added Firebird engine. Three cheers to Ștefan Suciu for this contribution!
    • Added support for the generation of arbitrary scripts from templates to the `add` command. Just add template files to subdirectories of the `templates` directory, and scripts will be created in a directory of the same name based on those templates.
    • Added `--open-editor` option (and aliases) to the `add` and `rework` commands. This option will open the newly-added change scripts in the preferred editor. Thanks to Thomas Sibley for the patch!
  • Improvements
    • Improved database driver loading to ensure the proper version of the driver is required.
    • Non-fatal but possibly unexpected messages -- which correspond to exit value 1 -- now send their messages to STDOUT instead of STDERR, and respect the `--quiet` option. Thanks to @giorgio-v for the report!
    • Added or replaced the `--target` option to commands that connect to a database to specify the name of target managed by the new `target` command or a database URI.
    • `HEAD` and `ROOT` are now recognized as aliases for `@HEAD` and `@ROOT`, respectively, since they are disallowed as change names, anyway, and folks often use them out of habit from Git.
  • Internals
    • Replaced the engine-specific connection attributes with three attributes use by every engine:
      • `target`: The name of a target managed by the new `target` command. Defaults to a value stored for the `core.$engine.target` configuration variable. If that variable does not exist, the target falls back on the stringification of `uri`.
      • `uri`: a database URI with the format `db:{engine}:{dbname}` or `db:{engine}://{user}:{password}@{host}:{port}/{dbname}`. If its value is not passed to the constructor, a `uri` value is looked up for the associated `target`. If `target` is not passed or configured, or if it has no URI associated with it, the `config.$engine.uri` configuration variable is used. If that value does not exist, the URI defaults to `db:$engine:`. In any of these cases, if any of the `--db-*` options are passed, they will be merged into the URI.
      • `registry`: the name to use for the Sqitch registry schema or database, where Sqitch's own data will be stored, as appropriate to each engine. If its value is not passed to the constructor, a `registry` value is looked up for the associated `target`. If `target` is not passed or configured, or if it has no registry associated with it, the `config.$engine.registry` configuration variable is used. If no value is found there, it defaults to an engine-specific value, usually "sqitch".
  • Bug Fixes
    • Fixed a bug when installing under local::lib. Thanks to Thomas Sibley for the pull request!
    • Eliminated "Wide character in print" warnings when piping the `log` command.
    • Documented that reworked changes do not have their verify tests run by the `verify` command. They do run when using the `--verify` deploy option.
    • Removed the documentation for the `add.with_deploy`, `add.with_revert`, and `add.with_verify` configuration variables, which were never implemented.
  • Deprecations
    • Deprecated engine-specific connection attributes and configuration variables. See the "Internals" section for their replacements. The deprecated options are:
      • `core.$engine.username`
      • `core.$engine.password`
      • `core.$engine.db_name`
      • `core.$engine.host`
      • `core.$engine.port`
      • `core.$engine.sqitch_schema`
      • `core.$engine.sqitch_db`
    • Deprecated all command-specific options with the string "target" in them, such as `--to-target`, `--upto-target`, etc. They have been replaced with options containing the string "change", instead, such as `--to-change` and `--upto-change`. Few people used these options, preferring their shorter aliases (`--to`, `--upto`, etc.).
    • Deprecated the `--deploy-template`, `--revert-template`, and `--verify-template` options to the `add` command. They are replaced with a single option, `--use` which takes a key/value pair for the script name and template path. This makes it useful for arbitrary script generation, as well.
    • Deprecated the `--deploy`, `--revert`, and `--verify` options to the `add` command, as well as their `--no-*` variants. They are replaced with two new options, `--with` and `--without`, to which a script name is passed. These are useful for arbitrary script generation, as well.
    • Deprecated the `add.deploy_template`, `add.revert_template`, and `add.verify_template` configuration settings. They have been replaced with a section, `add.templates`, which is more general, and supports arbitrary script generation, as well.
  • Incompatibilities
    • Removed the undocumented `--test` option to the `add` command.
    • Changed the meaning of `--target` from specifying a change to specifying a deployment target. Use the new `--change` option to specify a change.