Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
sqitch-config(3)      User Contributed Perl Documentation     sqitch-config(3)

Name
       sqitch-config - Get and set local, user,	or system Sqitch options

Synopsis
	 sqitch	config [<file-option>] [type] name [value [value_regex]]
	 sqitch	config [<file-option>] [type] --add name value
	 sqitch	config [<file-option>] [type] --replace-all name value [value_regex]
	 sqitch	config [<file-option>] [type] --get name [value_regex]
	 sqitch	config [<file-option>] [type] --get-all	name [value_regex]
	 sqitch	config [<file-option>] [type] --get-regexp name_regex [value_regex]
	 sqitch	config [<file-option>] --unset name [value_regex]
	 sqitch	config [<file-option>] --unset-all name	[value_regex]
	 sqitch	config [<file-option>] --rename-section	old_name new_name
	 sqitch	config [<file-option>] --remove-section	name
	 sqitch	config [<file-option>] -l | --list
	 sqitch	config [<file-option>] -e | --edit

Description
       You can query/set/replace/unset Sqitch options with this	command. The
       name is actually	the section and	the key	separated by a dot, and	the
       value will be escaped.

       Multiple	lines can be added to an option	by using the "--add" option.
       If you want to update or	unset an option	which can occur	on multiple
       lines, a	Perl regular expression	"value_regex" needs to be given. Only
       the existing values that	match the regex	will be	updated	or unset. If
       you want	to handle lines	that do	not match the regex, just prepend a
       single "!" (exclamation point) in front (see Examples).

       The "type" specifier can	be "--int", "--num", or	"--bool", to ensure
       that the	variable(s) are	of the given type and convert the value	to the
       canonical form (simple integer for "--int", decimal number for "--num",
       a "true"	or "false" string for "--bool")	If no type specifier is
       passed, no checks or transformations are	performed on the value.

       The "file-option" can be	one of "--local", "--user", "--system",	or
       "--file", which specify where the values	will be	read from or written
       to. The default is to assume the	local config file in the current
       project directory, for editing, and the all files merged	for fetching
       (see "Files").

       On success, the command returns the exit	code 0.

Options
       "--replace-all"
	   The default behavior	is to replace at most one line.	This replaces
	   all lines matching the key (and optionally the "value_regex").

       "--add"
	   Adds	a new line to the option without altering any existing values.
	   This	is the same as providing "^$" as the value_regex in
	   "--replace-all".

       "--get"
	   Get the value for a given key (optionally filtered by a regex
	   matching the	value).	Returns	error code 1 if	the key	was not	found
	   and error code 2 if multiple	values were found.

       "--get-all"
	   Like	"--get", but does not fail if the number of values for the key
	   is not exactly one.

       "--get-regexp"
	   Like	"--get-all", but interprets the	name as	a regular expression
	   and writes out the key names	and value.

       "--local"
	   For writing options:	write to the local ./sqitch.conf file. This is
	   the default if no file option is specified.

	   For reading options:	read only from the local ./sqitch.conf file
	   rather than from all	available files.

	   See also "Files".

       "--user"
	   For writing options:	write to the user ~/.sqitch/sqitch.conf	file
	   rather than the repository ./sqitch.conf.

	   For reading options:	read only from the user	~/.sqitch/sqitch.conf
	   file	rather than from all available files.

	   See also "Files".

       "--system"
	   For writing options:	write to system-wide
	   $(prefix)/etc/sqitch/sqitch.conf file rather	than the repository
	   ./sqitch.conf.

	   For reading options:	read only from system-wide
	   $(prefix)/etc/sqitch/sqitch.conf file rather	than from all
	   available files.

	   Call	"sqitch	--etc-path" to find out	exactly	where the system
	   configuration file lives (e.g., "$(sqitch
	   --etc-path)/sqitch.conf").

	   See also "Files".

       "-f config-file,	--file config-file"
	   Use the given config	file instead of	the one	specified by
	   $SQITCH_CONFIG.

       "--remove-section"
	   Remove the given section from the configuration file.

       "--rename-section"
	   Rename the given section to a new name.

       "--unset"
	   Remove the line matching the	key from config	file.

       "--unset-all"
	   Remove all lines matching the key from config file.

       "-l, --list"
	   List	all variables set in config file.

       "--bool"
	   "sqitch config" will	ensure that the	output is "true" or "false".

       "--int"
	   "sqitch config" will	ensure that the	output is a simple integer.

       "--num"
	   "sqitch config" will	ensure that the	output is a simple decimal
	   number.

       "--bool-or-int"
	   "sqitch config" will	ensure that the	output matches the format of
	   either "--bool" or "--int", as described above.

       "-e, --edit"
	   Opens an editor to modify the specified config file;	either
	   "--local", "--user",	"--system", or "--file". If none of those
	   options is specified, the local file	will be	opened.

Files
       If not set explicitly with "--file", there are three files in which
       "sqitch config" will search for configuration options:

       ./sqitch.conf
	   Local, project-specific configuration file.

       ~/.sqitch/sqitch.conf
	   User-specific configuration file.

       $(prefix)/etc/sqitch/sqitch.conf
	   System-wide configuration file.

Environment
       "SQITCH_CONFIG"
	   Take	the local configuration	from the given file instead of
	   ./sqitch.conf.

       "SQITCH_USER_CONFIG"
	   Take	the user configuration from the	given file instead of
	   ~/.sqitch/sqitch.conf.

       "SQITCH_SYSTEM_CONFIG"
	   Take	the system configuration from the given	file instead of
	   $($etc_prefix)/sqitch.conf.

Examples
       Given a ./sqitch.conf like this:

	 #
	 # This	is the config file, and
	 # a '#' or ';'	character indicates
	 # a comment
	 #

	 ; core	variables
	 [core]
		 ; Use PostgreSQL
		 engine	   = pg

	 ; Bundle command settings.
	 [bundle]
		 from	   = gamma
		 tags_only = false
		 dest_dir  = _build/sql

	 ; Revert command settings
	 [core "revert"]
		 set	    = foo=bar
		 set	    = baz=yo

       You can set the "tags_only" setting to true with

	 % sqitch config bundle.tags_only true

       The hypothetical	"set" key in the "core.revert" section might need to
       set "foo" to "hi" instead of "bar". Here's how to make that change:

	 % sqitch config core.revert.set foo=bar foo=hi

       To delete the entry for "bundle.from", do

	 % sqitch config --unset bundle.from

       If you want to delete an	entry for a multivalue setting (like
       "core.revert.set"), provide a regex matching the	value of exactly one
       line.

       To query	the value for a	given key, do:

	 % sqitch config --get core.engine

       Or:

	 % sqitch config core.engine

       Or, to query a multivalue setting for only those	values that match
       "/ba/":

	 % sqitch config --get core.revert.set ba

       If you want to know all the values for a	multivalue setting, do:

	 % sqitch config --get-all core.revert.set

       If you like to live dangerously,	you can	replace	all "core.revert.set"
       with a new one with

	 % sqitch config --replace-all core.revert.set bring=funk

       However,	if you only want to replace the	line without "baz", do
       something like this:

	 % sqitch config core.revert.set = '!baz'

       To match	only values with an exclamation	mark, you have to escape them:

	 % sqitch config section.key value '[!]'

       To add a	new setting without altering any of the	existing ones, use:

	 % sqitch config core.revert.set widget=fred

Configuration File
       The sqitch configuration	file contains a	number of variables that
       affect the sqitch command's behavior. The ./sqitch.conf file local to
       each project is used to store the configuration for that	project, and
       $HOME/.sqitch/sqitch.conf is used to store a per-user configuration as
       fallback	values for the ./sqitch.conf file. The file
       $($etc_prefix)/sqitch.conf can be used to store a system-wide default
       configuration.

       The variables are divided into sections,	wherein	the fully qualified
       variable	name of	the variable itself is the last	dot-separated segment
       and the section name is everything before the last dot. The variable
       names are case-insensitive, allow only alphanumeric characters and -,
       and must	start with an alphabetic character. Some variables may appear
       multiple	times.

   Syntax
       The syntax is fairly flexible and permissive; white space is mostly
       ignored.	 The "#" and ";" characters begin comments to the end of line,
       blank lines are ignored.

       The file	consists of sections and variables. A section begins with the
       name of the section in square brackets and continues until the next
       section begins.	Section	names are not case sensitive. Only
       alphanumeric characters,	"-" and	"." are	allowed	in section names. Each
       variable	must belong to some section, which means that there must be a
       section header before the first setting of a variable.

       Sections	can be further divided into subsections. To begin a subsection
       put its name in double quotes, separated	by space from the section
       name, in	the section header, like in the	example	below:

	    [section "subsection"]

       Subsection names	are case sensitive and can contain any characters
       except newline (double quote and	backslash have to be escaped as	"\""
       and "\\", respectively).	Section	headers	cannot span multiple lines.
       Variables may belong directly to	a section or to	a given	subsection.
       You can have "[section]"	if you have "[section "subsection"]", but you
       don't need to.

       All the other lines (and	the remainder of the line after	the section
       header) are recognized as setting variables, in the form	"name =
       value". If there	is no equal sign on the	line, the entire line is taken
       as name and the variable	is recognized as boolean "true". The variable
       names are case-insensitive, allow only alphanumeric characters and "-",
       and must	start with an alphabetic character. There can be more than one
       value for a given variable; we say then that the	variable is
       multivalued.

       Leading and trailing whitespace in a variable value is discarded.
       Internal	whitespace within a variable value is retained verbatim.

       The values following the	equals sign in variable	assignments are	either
       strings,	integers, numbers, or booleans.	Boolean	values may be given as
       yes/no, 1/0, true/false or on/off. Case is not significant in boolean
       values, when converting value to	the canonical form using the "--bool"
       type specifier; "sqitch config" will ensure that	the output is "true"
       or "false".

       String values may be entirely or	partially enclosed in double quotes.
       You need	to enclose variable values in double quotes if you want	to
       preserve	leading	or trailing whitespace,	or if the variable value
       contains	comment	characters (i.e. it contains "#" or ";"). Double quote
       and backslash characters	in variable values must	be escaped: use	"\""
       for """ and "\\"	for "\".

       The following escape sequences (beside "\"" and "\\") are recognized:
       "\n" for	newline	character (NL),	"\t" for horizontal tabulation (HT,
       TAB) and	"\b" for backspace (BS). No other character escape sequence or
       octal character sequence	is valid.

       Variable	values ending in a "\" are continued on	the next line in the
       customary UNIX fashion.

       Some variables may require a special value format.

   Example
	 # Core	variables
	 [core]
	     engine    = pg
	     top_dir   = migrations
	     extension = ddl

	 [engine "pg"]
	     registry  = widgetopolis

	 [revert]
	     to	       = gamma

	 [bundle]
	     from      = gamma
	     tags_only = yes
	     dest_dir  = _build/sql

   Variables
       Note that this list is not comprehensive	and not	necessarily complete.
       For command-specific variables, you will	find a more detailed
       description in the appropriate manual page.

       "core.plan_file"
	   The plan file to use. Defaults to $top_dir/sqitch.plan.

       "core.engine"
	   The database	engine to use. Supported engines include:

	   o   "pg" - PostgreSQL <http://postgresql.org/> and Postgres-XC
	       <http://sourceforge.net/>

	   o   "sqlite"	- SQLite <http://sqlite.org/>

	   o   "oracle"	- Oracle <http://www.oracle.com/us/products/database/>

	   o   "mysql" - MySQL <http://dev.mysql.com/> and MariaDB
	       <https://mariadb.com/>

	   o   "firebird" - Firebird <http://www.firebirdsql.org/>

	   o   "vertica" - Vertica <https://my.vertica.com/>

       "core.top_dir"
	   Path	to directory containing	deploy,	revert,	and verify SQL
	   scripts. It should contain subdirectories named "deploy", "revert",
	   and (optionally) "verify". These may	be overridden by "deploy_dir",
	   "revert_dir", and "verify_dir". Defaults to ".".

       "core.deploy_dir"
	   Path	to a directory containing SQL deployment scripts. Overrides
	   the value implied by	"core.top_dir".

       "core.revert_dir"
	   Path	to a directory containing SQL reversion	scripts. Overrides the
	   value implied by "core.top_dir".

       "core.verify_dir"
	   Path	to a directory containing SQL verify scripts. Overrides	the
	   value implied by "core.top_dir".

       "core.extension"
	   The file name extension on deploy, revert, and verify SQL scripts.
	   Defaults to "sql".

       "core.verbosity"
	   An integer determining how verbose Sqitch should be.	Defaults to 1.
	   Set to 0 to silence status messages and to 2	or three to increase
	   verbosity. Error message output will	not be affected	by this
	   property.

       "user"

       Configuration properties	that identify the user.

       "user.name"
	   Your	full name, to be recorded in changes and tags added to the
	   plan, and to	commits	to the database.

       "user.email"
	   Your	email address, to be recorded in changes and tags added	to the
	   plan, and to	commits	to the database.

       "engine.$engine"

       Each supported engine offers a set of configuration variables, falling
       under the key "engine.$engine" where $engine may	be any value accepted
       for "core.engine".

       "engine.$engine.target"
	   A database target, either the name of target	managed	by the
	   "target" command, or	a database connection URI. If it's a target
	   name, then the associated "uri", "registry",	and "client" values
	   will	override any values specified for the values below. Targets
	   are the preferred way to configure engines on a per-database	basis,
	   and the one specified here should be	considered the default.

       "engine.$engine.uri"
	   A database connection URI.

       "engine.$engine.registry"
	   The name of the Sqitch registry schema or database. Sqitch will
	   store its own data in this schema.

       "engine.$engine.client"
	   Path	to the engine command-line client. Defaults to the first
	   instance found in the path.

       Notes on	engine-specific	configuration:

       "engine.pg.registry"
	   For the PostgreSQL engine, the "registry" value identifies the
	   schema for Sqitch to	use for	its own	data. No other data should be
	   stored there. Defaults to "sqitch".

       "engine.sqlite.registry"
	   For the SQLite engine, if the "registry" value looks	like an
	   absolute path, then it will be the database file. Otherwise,	it
	   will	be in the same directory as the	database specified by the
	   "uri". Defaults to "sqitch".

       "engine.mysql.registry"
	   For the MySQL engine, the "registry"	value identifies the database
	   for Sqitch to use for its own data. If you need to manage multiple
	   databases on	a single server, and don't want	them all to share the
	   same	registry, change this property to a value specific for your
	   database. Defaults to "sqitch".

       "engine.oracle.registry"
	   For Oracle, "registry" value	identifies the schema for Sqitch to
	   use for its own data. No other data should be stored	there. Uses
	   the current schema by default (usually the same name	as the
	   connection user).

       "engine.firebird.registry"
	   For the Firebird engine, if the "registry" value looks like an
	   absolute path, then it will be the database file. Otherwise,	it
	   will	be in the same directory as the	database specified by the
	   "uri". Defaults to "sqitch.$extension", where $extension is the
	   same	as that	in the "uri", if any.

       "engine.vertica.registry"
	   For the Vertica engine, the "registry" value	identifies the schema
	   for Sqitch to use for its own data. No other	data should be stored
	   there. Defaults to "sqitch".

       "core.vcs"

       Configuration properties	for the	version	control	system.	Currently,
       only Git	is supported.

       "core.vcs.client"
	   Path	to the "VCS" command-line client. Defaults to the first
	   instance of git found in the	path.

       "user"

       "user.email"
	   Your	email address to be recorded in	any newly planned changes.

       "user.name"
	   Your	full name to be	recorded in any	newly planned changes.

Sqitch
       Part of the sqitch suite.

perl v5.24.1			  2017-07-03		      sqitch-config(3)

Name | Synopsis | Description | Options | Files | Environment | Examples | Configuration File | Sqitch

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=sqitch-config&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help