.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "PGCOPYDB" "5" "May 22, 2024" "0.16" "pgcopydb"
.SH NAME
pgcopydb \- pgcopydb
.sp
Manual page for the configuration of pgcopydb. The \fBpgcopydb\fP command
accepts sub\-commands and command line options, see the manual for those
commands for details. The only setup that \fBpgcopydb\fP commands accept is
the filtering.
.SH FILTERING
.sp
Filtering allows to skip some object definitions and data when copying from
the source to the target database. The pgcopydb commands that accept the
option \fB\-\-filter\fP (or \fB\-\-filters\fP) expect an existing filename as the
option argument. The given filename is read in the INI file format, but only
uses sections and option keys. Option values are not used.
.sp
Here is an inclusion based filter configuration example:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
[include\-only\-table]
public.allcols
public.csv
public.serial
public.xzero

[exclude\-index]
public.foo_gin_tsvector

[exclude\-table\-data]
public.csv
.EE
.UNINDENT
.UNINDENT
.sp
Here is an exclusion based filter configuration example:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
[exclude\-schema]
foo
bar
expected

[exclude\-table]
\(dqschema\(dq.\(dqname\(dq
schema.othername
err.errors
public.serial

[exclude\-index]
schema.indexname

[exclude\-table\-data]
public.bar
nsitra.test1
.EE
.UNINDENT
.UNINDENT
.sp
Filtering can be done with pgcopydb by using the following rules, which are
also the name of the sections of the INI file.
.SS include\-only\-table
.sp
This section allows listing the exclusive list of the source tables to copy
to the target database. No other table will be processed by pgcopydb.
.sp
Each line in that section should be a schema\-qualified table name. \fI\%Postgres
identifier quoting rules\fP can be used to avoid ambiguity.
.sp
When the section \fBinclude\-only\-table\fP is used in the filtering
configuration then the sections \fBexclude\-schema\fP and \fBexclude\-table\fP are
disallowed. We would not know how to handle tables that exist on the source
database and are not part of any filter.
.SS exclude\-schema
.sp
This section allows adding schemas (Postgres namespaces) to the exclusion
filters. All the tables that belong to any listed schema in this section are
going to be ignored by the pgcopydb command.
.sp
This section is not allowed when the section \fBinclude\-only\-table\fP is
used.
.SS include\-only\-schema
.sp
This section allows editing schema (Postgres namespaces) to the exclusion
filters by listing the schema that are not going to be excluded. This is a
syntaxic sugar facility that helps with entering a long list of schemas to
exclude when a single schema is to be selected.
.sp
Despite the name, this section is an exclusion filter.
.sp
This section is not allowed when the section \fBexclude\-schema\fP is used.
.SS exclude\-table
.sp
This section allows to add a list of qualified table names to the exclusion
filters. All the tables that are listed in the \fBexclude\-table\fP section are
going to be ignored by the pgcopydb command.
.sp
This section is not allowed when the section \fBinclude\-only\-table\fP is
used.
.SS exclude\-index
.sp
This section allows to add a list of qualified index names to the exclusion
filters. It is then possible for pgcopydb to operate on a table and skip a
single index definition that belong to a table that is still processed.
.SS exclude\-table\-data
.sp
This section allows to skip copying the data from a list of qualified table
names. The schema, index, constraints, etc of the table are still copied
over.
.SH REVIEWING AND DEBUGGING THE FILTERS
.sp
Filtering a \fBpg_restore\fP archive file is done through rewriting the
archive catalog obtained with \fBpg_restore \-\-list\fP\&. That\(aqs a little hackish
at times, and we also have to deal with dependencies in pgcopydb itself.
.sp
The following commands can be used to explore a set of filtering rules:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
\fI\%pgcopydb list depends\fP
.IP \(bu 2
\fI\%pgcopydb restore parse\-list\fP
.UNINDENT
.UNINDENT
.UNINDENT
.SH AUTHOR
Dimitri Fontaine
.SH COPYRIGHT
2022-2024, Dimitri Fontaine
.\" Generated by docutils manpage writer.
.