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

SHOW ALL

[title]
allows displaying
all the objects

HIDE flag [, ...] objectName [ db=dbName ][ type=objectType[, ...] ]

[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

HIDE ALL

[title]
forbids displaying
all the objects

SHOW flag [, ...] objectName [ db=dbName ] [ type=objectType [, ...] ]

[rule]
allows to display
an object

Where:

objectName, dbName, objectType
identifiers for object search identical to the PostgreSQL identifiers
to use special characters (for example, in regular expressions), the identifier should be put in quotation marks
see 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)
or
line 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:

_images/white_black_hierarchy_project.png

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

HIDE ALL
[title]
forbids displaying
all the objects

SHOW REGEX K
[rule]
allows to display
objects that partially
match the regular
expression “K”

show_regex

HIDE ALL
[title]
forbids displaying
all the objects

SHOW CONTENT D
[rule]
allows to display
object D and its content

show_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

show_none

HIDE ALL
[title]
forbids displaying
all the objects

SHOW NONE D
[rule]
allows to display
object D only

show_none

Examples for black list

Example and discription

Effective range

SHOW ALL
[title]
allows displaying
all the objects

show_all

SHOW ALL
[title]
allows displaying
all the objects

HIDE REGEX K
[rule]
excludes objects which
partially match the
regular expression “K”

hide_regex

SHOW ALL
[title]
allows displaying
all the objects)

HIDE CONTENT D
[rule]
exludes object D
and its content

hide_content

SHOW ALL
[title]
allows displaying
all the objects

HIDE QUALIFIED ‘A.C.D’
[rule]
excludes object D only
with parent A.C

hide_none

SHOW ALL
[title]
allows displaying
all the objects

HIDE NONE D
[rule]
excludes object D only

hide_none


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

_images/white_black_hierarchy_regex_hide.png _images/white_black_hierarchy_regex_show_2.png

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

_images/ignore_list_diff.png _images/white_black_hierarchy_example_project_base.png

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

_images/ignore_list_pattern_diff.png _images/white_black_hierarchy_example_project_regex.png

To exclude the object “ignore2” and its content, you should write the following rules in .pgcodekeeperignore:

SHOW ALL
HIDE CONTENT ignore2

Result

Schema

_images/ignore_list_content_diff.png _images/white_black_hierarchy_example_project_content.png

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

_images/ignore_list_type_diff.png _images/white_black_hierarchy_example_project_regex_type.png

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

_images/ignore_list_diff.png _images/white_black_hierarchy_example_project_base.png

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

_images/ignore_list_db.png _images/white_black_hierarchy_example_project_content_regex_db_type.png

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

_images/ignore_list_pattern_diff.png _images/white_black_hierarchy_example_project_regex.png _images/white_black_hierarchy_example_project_content_white.png

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.