Ignore List
Ignore List is a list of objects that should or should not be displayed when comparing databases.
Attention
Objects filtered with the help of these lists participate in the comparison and can end up in the resulting migration script of the dependance.
There are two types of lists of ignored objects:
- black list
allows displaying all the objects except the ones indicated in the rules of the list;
- white list
in opposition to black list, forbids displaying all the objects except the ones indicated in the rules of the list.
In each project, it is possible to create a ignore list, applying only to current project. To do this, create the .pgcodekeeperignore file in the project root and fill it with the rules according to the list syntax.
Attention
The .pgcodekeeperignore file format is case-sensitive. You should use UTF-8.
In the following, in the List syntax section, we will consider the rules of forming the .pgcodekeeperignore file.
Note
In addition to the .pgcodekeeperignore file, in the graphical version of pgCodeKeeper, there is a general list of ignored objects. It affects all the projects located in the project directory. You can fill it on the global settings page in the Excluded objects section.
List syntax
.pgcodekeeperignore consists of two parts:
- title
is obligatory, occupies the first line and determines type of the list;
- rules
lines of rules which forbid or allow (depending on the type of list) displaying some object.
Black list allows to display only the objects which are not specified by rules. It is constructed so that the heading of the list allows displaying all the objects, and the rules following it exclude the objects from displaying.
# комментарий
SHOW ALL
HIDE flag [, ...] objectName [ db=dbName ] [ type=objectType [, ...] ] # комментарий
[ ... ]
Description of black list components
.pgcodekeeperignore file line |
Description |
---|---|
|
[title]
allows displaying
all the objects
|
|
[rule]
excludes from displaying
an object
|
White list, on the contrary, allows to display only the objects which are specified by rules. It is constructed so that the heading of the list forbids displaying all the objects, and the rules following it allow to display the objects.
# комментарий
HIDE ALL
SHOW flag [, ...] objectName [ db=dbName ] [ type=objectType [, ...] ] # комментарий
[ ... ]
Description of white list components
.pgcodekeeperignore file line |
Description |
---|---|
|
[title]
forbids displaying
all the objects
|
|
[rule]
allows to display
an object
|
Where:
- objectName, dbName, objectType
- identifiers for object search identical to the PostgreSQL identifiersto use special characters (for example, in regular expressions), the identifier should be put in quotation markssee the identifier rule below for more info
objectName |
name of the target object (is an obligatory part of the rule) |
dbName |
name of the database where the search for the object will take place (optional) |
objectType |
type of the target object (optional) |
Important
objectType may be equal to one of the following values: CAST, USER, ROLE, ASSEMBLY, SCHEMA, EXTENSION, TYPE, DOMAIN, SEQUENCE, OPERATOR, FTS_PARSER, FTS_TEMPLATE, FTS_DICTIONARY, FTS_CONFIGURATION, TABLE, FUNCTION, PROCEDURE, AGGREGATE, CONSTRAINT, VIEW, INDEX, TRIGGER, RULE, POLICY.
- identifier
- identifier string without quotes, consisting of latin characters, numerals and underlining;can’t start with a numeral;identifier string can’t be a key word (reserved language directive)orline limited by double quotes
"
or apostrophes'
(separation symbols in the beginning and the end of the line should match);separation symbols contained in the line, are escaped by repeating the symbol (for example:"1""2'3"
или'1"2''3'
)
Attention
“objectType” is case-sensitive.
- flag { NONE | REGEX | CONTENT | QUALIFIED }
flag of ways of searching the object
REGEX |
treats objectName as a regular expression [1] |
CONTENT |
applies the rule for the matched object and all of its content |
QUALIFIED |
compares objectName to the qualified name of the object |
NONE |
complete match without the regular expression and content |
Content is the object content, according to the pgCodeKeeper project hierarchy:
For example, “INDEX1”, “TRIGGER1” and “RULE1” will be the content of “TABLE1”.
Additional options:
db=dbName the rule will work only for the DB, the name of which matches the regular expression set by this parameter
type=objectType the rule will work only for the objects with the specified type
Note
To specify several types of one and the same object, you should separate them with commas.
Attention
Database name is case sensitive.
Examples for white list
Example and discription |
Effective range |
---|---|
HIDE ALL
[title]
forbids displaying
all the objects
|
|
HIDE ALL
[title]
forbids displaying
all the objects
SHOW REGEX K
[rule]
allows to display
objects that partially
match the regular
expression “K”
|
|
HIDE ALL
[title]
forbids displaying
all the objects
SHOW CONTENT D
[rule]
allows to display
object D and its content
|
|
HIDE ALL
[title]
forbids displaying
all the objects
SHOW QUALIFIED ‘A.C.D’
[rule]
allows to display
object D only
with parent A.C
|
|
HIDE ALL
[title]
forbids displaying
all the objects
SHOW NONE D
[rule]
allows to display
object D only
|
Examples for black list
Example and discription |
Effective range |
---|---|
SHOW ALL
[title]
allows displaying
all the objects
|
|
SHOW ALL
[title]
allows displaying
all the objects
HIDE REGEX K
[rule]
excludes objects which
partially match the
regular expression “K”
|
|
SHOW ALL
[title]
allows displaying
all the objects)
HIDE CONTENT D
[rule]
exludes object D
and its content
|
|
SHOW ALL
[title]
allows displaying
all the objects
HIDE QUALIFIED ‘A.C.D’
[rule]
excludes object D only
with parent A.C
|
|
SHOW ALL
[title]
allows displaying
all the objects
HIDE NONE D
[rule]
excludes object D only
|
Key words:
HIDE SHOW ALL REGEX CONTENT QUALIFIED NONE
These words cannot be identifiers, since they need to be enclosed in quotes to be used. Only the words which match the case perfectly, are reserved. For example - Content is an allowed identifier.
As an example of excluding the object - the name which matches perfectly (including the case) the key word SHOW:
SHOW ALL
HIDE NONE "SHOW"
Combined use of black and white lists
Black and white lits can be used together. In this case, their rules are combined into a common list. The rules which regulate displaying of one and the same object, combine into one common rule according to the following principles:
if the rules are different in “range”, then the rule with a broader range (includes the object and its content) prevails
if the “range” of the rules is the same, then the rule that hides the object prevails
Rule’s “range” is including or not including an object’s content into the effective range of the rule, that is, the condition of the CONTENT flag (for common list of the pgCodeKeeper graphic version, it’s the “Ignore contents” option, described in the Excluded objects section).
Example of combined use of black and white lists:
black list file
SHOW ALL
HIDE REGEX K
white list file
HIDE ALL
SHOW CONTENT KF
Effective range of the rule
Black list |
White List |
---|---|
As as result, the object with the name “KF” will be displayed, because the condition of the white list for current object surpasses the condition of the black list in “range”.
Note
When working with the graphic version of pgCodeKeeper, adding the second list of exclusions is possible by using the general list of the excluded objects or by adding the external list through DB storage. CLI version pgCodeKeeper allows to add additional lists of exclusions with the help of the command: pgcodekeeper-cli --ignore-list <path> SOURCE DEST
.
Examples of work with .pgcodekeeperignore
Suppose there is a view named ignore4 and a set of tables with the names: ignore, ignore2, ignore3. In its turn, ignore2 has some content.
Result |
Schema |
---|---|
To exclude all the objects partially matching the regular expression “ignore”, you should write the following rules in .pgcodekeeperignore:
SHOW ALL
HIDE REGEX ignore
Result |
Schema |
---|---|
To exclude the object “ignore2” and its content, you should write the following rules in .pgcodekeeperignore:
SHOW ALL
HIDE CONTENT ignore2
Result |
Schema |
---|---|
To exclude all the objects with the “TABLE” type, partially matching the regular expression “ignore”, you should write the following rules in .pgcodekeeperignore:
SHOW ALL
HIDE REGEX ignore type=TABLE
Result |
Schema |
---|---|
To exclude all the objects partially matching the regular expression “ignore” with the “TABLE” type and content for the specified database, you should write the following rules in .pgcodekeeperignore:
SHOW ALL
HIDE CONTENT,REGEX ignore db=name_of_other_db type=TABLE
abovementioned rules use the name of another database, not the one which is in work in this example, so everything will remain unchanged
Result |
Schema |
---|---|
but if you specify the name of the database in work, then all the objects will disappear from the displayed, except the one which doesn’t match the type.
SHOW ALL
HIDE CONTENT,REGEX ignore db=db1 type=TABLE
Result |
Schema |
---|---|
To allow displaying the object “ignore2” using black and white lists at the same time, you need to write the following rules:
file .pgcodekeeperignore - black list
SHOW ALL
HIDE REGEX ignore
additional file of the list of excluded objects - white list
HIDE ALL
SHOW CONTENT ignore2
Note
How to add an additional list is discribed in the Combined use of black and white lists section.
The aim of the black list is to exclude all the objects partially matching the regular expression “ignore”.
The aim of the white list is to remove “ignore2” from the excluded objects.
Result |
Black list |
White List |
---|---|---|
As a result, only “ignore2” will remain in the compared objects, because thanks to the “CONTENT” flag for the “ignore2” the white list rule surpasses the black list rule “HIDE REGEX ignore” in “range”.
Note
Interaction between the rules of different lists which regulate the display of one and the same object is described in the Combined use of black and white lists section.