List of excluded objects

List of excluded objects is a list of objects, which should not or, alternatively, should be displayed during database comparison. Accordingly, there are two types of lists of excluded 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 list of excluded objects, 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 list of excluded objects of the .pgcodekeeperignore file, in the graphical version of pgCodeKeeper, there is a general list of excluded objects which 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.

# comment
SHOW ALL
HIDE flag [, …] objectName [ db=dbName ] [ type=objectType [, …] ] # comment
[ … ]

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
some
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.

# comment
HIDE ALL
SHOW flag [, …] objectName [ db=dbName ] [ type=objectType [, …] ] # comment
[ … ]

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 for
displaying
some
object

Where:

objectName, dbName, objectType
identifiers for object search which have a common syntactic rule of spelling described in identifier
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: CONSTRAINT, DOMAIN, EXTENSION, FUNCTION, INDEX, RULE, SCHEMA, SEQUENCE, TABLE, TRIGGER, TYPE, VIEW.

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 screened off by repeating the symbol (for example: “1”“2‘3” или ‘1”2’‘3’)

Attention

Currently it is not possible to use qualified names as “objectName”.

Attention

“objectType” is case sensitive.

flag { NONE | REGEX | CONTENT }
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
NONE:complete match without the regular expression and content
[1]REGEX flag allows the rule to search for partial matches with the regular expression.

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
_images/white_black_hierarchy_all_hide.png
HIDE ALL
[title]
forbids displaying
all the objects

SHOW REGEX K
[rule]
allows to display
objects that partially
match the regular
expression “K”
_images/white_black_hierarchy_regex_show.png
HIDE ALL
[title]
forbids displaying
all the objects

SHOW CONTENT D
[rule]
allows to display
object D and its
content
_images/white_black_hierarchy_content_show.png
HIDE ALL
[title]
forbids displaying
all the objects

SHOW NONE D
[rule]
allows to display
object D only
_images/white_black_hierarchy_none_show.png

Examples for black list

Example and discription Effective range
SHOW ALL
[title]
allows displaying
all the objects
_images/white_black_hierarchy_all_show.png
SHOW ALL
[title]
allows displaying
all the objects

HIDE REGEX K
[rule]
excludes objects
which partially
match the regular
expression “K”
_images/white_black_hierarchy_regex_hide.png
SHOW ALL
[title]
allows displaying
all the objects)

HIDE CONTENT D
[rule]
exludes object D
and its content
_images/white_black_hierarchy_content_hide.png
SHOW ALL
[title]
allows displaying
all the objects

HIDE NONE D
[rule]
excludes only
object D
_images/white_black_hierarchy_none_hide.png

Key words:

HIDE SHOW ALL REGEX CONTENT 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 content” 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 -I (–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.