API Reference

This section documents the C++ classes and functions that make up the Perseid libraries.

Database

class Config

A database connection configuration

Public Functions

Config() = delete
Config(const string &dbname, const string &host = {}, int port = 0, const string &user = {}, const string &password = {})

Constructor

Parameters:

  • dbname – database name

  • host – server hostname

  • port – server port

  • user – user name

  • password – password

inline const string &dbname() const
inline const string &host() const
inline int port() const
inline const string &user() const
inline const string &password() const
class Database

A database definition, from its catalogs and/or a YAML spec A Database is initialized with a Config object specifying connection information.

Public Functions

Database() = delete
Database(const Config &cfg)

Initialize the database

Parameters:

cfg – database connection configuration

YAML::Node to_yaml(bool no_owner = true, bool no_privs = true, const vector<string> &schemas = {}, const vector<string> &tables = {})

Convert the database schema to a YAML node

Parameters:

  • no_owner – exclude object owner information

  • no_privs – exclude privilege information

  • schemas – schema names to include

  • tables – table names to include

Returns:

YAML node

void from_yaml(const YAML::Node &node)

Populate the database schema from an input YAML node

Parameters:

node – a YAML node defining the database schema

vector<Statement> diff_yaml(const YAML::Node &node, bool no_owner = true, bool no_privs = true)

Generate SQL statements to transform the database into the input node

Compares the current database (as read from the catalogs) to the input YAML node and generates SQL statements to transform it into the one represented by the input.

Parameters:

  • node – the input YAML node defining the database

  • no_owner – exclude object owner changes

  • no_privs – exclude privilege changes

Returns:

SQL statements

void from_catalog()

Populate the database objects by querying the catalogs

void fetch_reserved_words()

Fetch PostgreSQL reserved words into the dbobject module

inline Rel_db *db() const

Return the underlying relational database connection wrapper

Returns:

the Rel_db instance, or nullptr if none

inline const Database_map &map() const

Return the database object maps

Returns:

the object maps

inline Database_map &map()
class Database_map

The collection of all database objects, wrapping the schema and table maps

Public Functions

void from_catalog(Rel_db &db)

Initialize the object maps from the database catalogs

Parameters:

db – database connection

void from_yaml(const YAML::Node &node)

Initialize the object maps from an input YAML node

Parameters:

node – a YAML node defining the database schema

vector<Statement> diff_yaml(const YAML::Node &node)

Generate SQL statements to transform the database into the input node

Parameters:

node – the input YAML node defining the database

Returns:

SQL statements

inline const map<string, Schema> &schemas() const

Return the schemas

Returns:

schemas

inline const map<string, Table> &tables() const

Return the tables

Returns:

tables

Database objects

class Db_object

A single object in a database catalog, e.g., a schema, a table.

Subclassed by perseid::Schema, perseid::Schema_object

Public Functions

Db_object() = default
inline Db_object(const string &name, const string &description, const string &owner)

Constructor

Parameters:

  • name – object name

  • description – comment text describing object

  • owner – owner name

virtual ~Db_object() = default
virtual string obj_type() const = 0

Type of object as an uppercase string, for SQL syntax generation

This is used in most CREATE, ALTER and DROP statements. It is also used by extern_key() in lowercase form.

Returns:

string

virtual string extern_key() const

Return the key to be used in external maps for this object

The common format for an external key is object-type non-schema-qualified-name, where object-type is the lowercase version of obj_type, e.g., table tablename.

Returns:

string

virtual string identifier() const

Returns a full identifier for the database object

This is used by comment(), alter_owner() and drop() to generate SQL syntax referring to the object. It does not include the object type, but it may include (in overridden methods) other elements.

Returns:

string

virtual vector<Statement> create() const = 0

Return SQL statements to create the object

Returns:

SQL statements

virtual vector<Statement> drop() const

Generate SQL to drop the current object

Returns:

SQL statements

string comment() const

Return SQL statement to create a COMMENT on the object

Returns:

SQL statement

string alter_owner() const

Return ALTER statement to set the OWNER of an object

Returns:

SQL statement

virtual vector<Statement> alter(const Db_object &rhs, bool no_owner = false) const

Generate SQL to transform an existing database object

Compares the current object to an input object and generates SQL statements to transform it into the one represented by the input. The default implementation handles description and owner changes.

Parameters:

  • rhs – the new object

  • no_owner – exclude object owner changes

Returns:

SQL statements

inline string name() const
inline void set_name(const string &nm)
inline string description() const
inline void set_description(const string &desc)
inline string owner() const
inline void set_owner(const string &own)
class Schema_object : public perseid::Db_object

A database object that is owned by a certain schema

Subclassed by perseid::Constraint, perseid::Relation

Public Functions

Schema_object() = default
inline Schema_object(const string &name, const string &schema, const string &description, const string &owner)

Constructor

Parameters:

  • name – object name

  • schema – schema name

  • description – comment text

  • owner – owner name

virtual string extern_key() const override

Return the key to be used in external maps for this object

Returns:

string

virtual string identifier() const override

Return a full identifier for a schema object

Returns:

string

string qual_name(const string &schema = {}, const string &objname = {}) const

Return the schema-qualified name of self or a related object

Parameters:

  • schema – schema name (defaults to own schema)

  • objname – object name (defaults to own name)

Returns:

string

inline string schema() const
inline void set_schema(const string &sch)
class Schema : public perseid::Db_object

A database schema definition, i.e., a named collection of tables, views, triggers and other schema objects.

Public Functions

Schema() = default
Schema(const string &name, const string &description = {}, const string &owner = {})

Constructor

Parameters:

  • name – schema name (from nspname)

  • description – comment text (from obj_description())

  • owner – owner name (from rolname via nspowner)

inline virtual string obj_type() const override

Type of object as an uppercase string, for SQL syntax generation

This is used in most CREATE, ALTER and DROP statements. It is also used by extern_key() in lowercase form.

Returns:

string

virtual vector<Statement> create() const override

Generate SQL statements to CREATE the schema

Returns:

SQL statements

virtual vector<Statement> drop() const override

Generate SQL to drop the schema

Returns:

SQL statements

YAML::Node to_yaml(bool no_owner = false) const

Convert the schema to a YAML node

Parameters:

no_owner – exclude owner information

Returns:

YAML node

Public Static Functions

static string catalog_query(unsigned dbversion = 0)

Return the catalog query to load schemas

Parameters:

dbversion – database server version (e.g. 160006 for 16.6), 0 for unknown; may alter the query on version-specific catalogs

Returns:

SQL query string

static Schema from_yaml(const string &name, const YAML::Node &node)

Initialize a schema from a YAML node

Parameters:

  • name – schema name

  • node – YAML node defining the schema

Returns:

schema instance

class Schema_map

The collection of schemas in a database

Public Functions

void from_catalog(Rel_db &db)

Initialize schemas from the database catalogs

Queries catalogs for schemas other than system/information schemas, and populates the map.

Parameters:

db – database connection

vector<Statement> transform(const Schema_map &rhs) const

Transform current Schema_map into the input collection

Compares this (current) map to the input (new) map and generates SQL statements to transform it into the one represented by the input.

Parameters:

rhs – the target collection of schemas

Returns:

SQL statements

inline const map<string, Schema> &schemas() const
inline void set_schemas(const map<string, Schema> &schemas)
class Relation : public perseid::Schema_object

A database relation (table, view, sequence, etc.)

This corresponds to the pg_class catalog entry. It serves as the common base class for all relation types that have a schema, owner, and columns.

Subclassed by perseid::Table

Public Functions

Relation() = default
inline Relation(const string &name, const string &schema = {}, const string &description = {}, const string &owner = {})

Constructor

Parameters:

  • name – relation name

  • schema – schema name

  • description – comment text

  • owner – owner name

inline string key() const

Return the relation name for use as a map key

Returns:

relation name

class Table : public perseid::Relation

A database table definition

A table is identified by its schema name and table name. It should have a list of columns. It may have a primary_key, zero or more foreign_keys, zero or more unique_constraints, and zero or more check_constraints.

Public Functions

Table() = default
Table(const string &name, const string &schema = {}, const string &description = {}, const string &owner = {})

Constructor

Parameters:

  • name – table name

  • schema – schema name

  • description – comment text

  • owner – owner name

inline virtual string obj_type() const override

Type of object as an uppercase string, for SQL syntax generation

This is used in most CREATE, ALTER and DROP statements. It is also used by extern_key() in lowercase form.

Returns:

string

virtual vector<Statement> create() const override

Return SQL statements to CREATE the table

Returns:

SQL statements

virtual vector<Statement> drop() const override

Generate SQL to drop the table, dropping its constraints first

Returns:

SQL statements

vector<Statement> alter(const Table &rhs, bool no_owner = false) const

Generate SQL to transform an existing table

Compares the current table to an input table and generates SQL statements to transform it into the one represented by the input.

Parameters:

  • rhs – the new table definition

  • no_owner – exclude object owner changes

Returns:

SQL statements

virtual vector<Statement> alter(const Db_object &rhs, bool no_owner = false) const override

Generate SQL to transform an existing table (virtual override)

Parameters:

  • rhs – the new object

  • no_owner – exclude object owner changes

Returns:

SQL statements

YAML::Node to_yaml(bool no_owner = false) const

Serialize the table to a YAML node

Parameters:

no_owner – exclude owner information

Returns:

YAML node

inline const vector<Column> &columns() const

Return columns

Returns:

columns

inline void set_columns(const vector<Column> &cols)

Set columns

Parameters:

cols – columns

inline void add_column(const Column &col)

Add a column

Parameters:

col – column to add

inline const map<string, Check_constraint> &check_constraints() const

Return check constraints

Returns:

check constraints

inline void set_check_constraints(const map<string, Check_constraint> &cks)

Set check constraints

Parameters:

cks – check constraints

inline void add_check_constraint(const Check_constraint &ck)

Add a check constraint

Parameters:

ck – check constraint to add

inline const std::optional<Primary_key> &primary_key() const

Return primary key

Returns:

primary key

inline void set_primary_key(const Primary_key &pk)

Set primary key

Parameters:

pk – primary key

inline void reset_primary_key()

Clear primary key

inline const map<string, Foreign_key> &foreign_keys() const

Return foreign keys

Returns:

foreign keys

inline void set_foreign_keys(const map<string, Foreign_key> &fks)

Set foreign keys

Parameters:

fks – foreign keys

inline void add_foreign_key(const Foreign_key &fk)

Add a foreign key

Parameters:

fk – foreign key to add

inline const map<string, Unique_constraint> &unique_constraints() const

Return unique constraints

Returns:

unique constraints

inline void set_unique_constraints(const map<string, Unique_constraint> &ucs)

Set unique constraints

Parameters:

ucs – unique constraints

inline void add_unique_constraint(const Unique_constraint &uc)

Add a unique constraint

Parameters:

uc – unique constraint to add

Public Static Functions

static string catalog_query(unsigned dbversion = 0)

Return the catalog query to load tables

Parameters:

dbversion – database server version (e.g. 160006 for 16.6), 0 for unknown; may alter the query on version-specific catalogs

Returns:

SQL query string

static Table from_yaml(const string &name, const string &schema, const YAML::Node &node)

Initialize a table from a YAML node

Parameters:

  • name – table name

  • schema – schema name

  • node – YAML node defining the table

Returns:

table instance

class Table_map

The collection of tables in a database

Public Functions

void from_catalog(Rel_db &db)

Initialize tables from the database catalogs

Queries catalogs for tables and their attributes and constraints, populating the map. Dropped columns and system/information schemas are excluded.

Parameters:

db – database connection

void from_yaml(const string &schema, const YAML::Node &node)

Initialize tables from a YAML node

Parameters:

  • schema – schema name

  • node – the input YAML node defining the tables

vector<Statement> transform(const Table_map &rhs) const

Transform current Table_map into the input collection

Compares this (current) map to the input (new) map and generates SQL statements to transform it into the one represented by the input.

Parameters:

rhs – the target collection of tables

Returns:

SQL statements

vector<string> topo_sort() const

Return table keys (schema.name) in dependency (creation) order

Tables referenced by foreign keys are ordered before the tables that reference them, so that CREATE TABLE statements can be executed in the returned order.

Returns:

vector of schema-qualified table names

inline const map<string, Table> &tables() const

Return tables

Returns:

tables

inline Table &table(const string &key)

Return a table by schema-qualified key

Parameters:

key – schema-qualified table key (“schema.name”)

Returns:

table reference

inline void set_tables(const map<string, Table> &tables)

Set tables

Parameters:

tables – tables

inline void add_table(const Table &t)

Add a table

Tables are keyed by their schema-qualified name so that same-named tables in different schemas do not collide.

Parameters:

t – table to add

Public Static Functions

static inline string key(const string &schema, const string &name)

Return a table key (“schema.name”) identifying the table

Parameters:

  • schema – schema name

  • name – table name

Returns:

schema-qualified key

class Column : public Attribute

A table column or attribute of a composite type

Public Functions

Column() = default
Column(const string &name, const string &type, int number = 0, const string &description = {}, bool not_null = false, const string &default_val = {})

Constructor

Parameters:

  • name – column/attribute name

  • type – data type (built-in or user-defined type name)

  • number – attribute ordinal position

  • description – comment text

  • not_null – not null constraint

  • default_val – default value expression

string add() const

Return a string to specify the column in a CREATE or ALTER TABLE

Returns:

partial SQL statement

string comment(const string &qual_name) const

Return a SQL COMMENT statement for the column

Parameters:

qual_name – schema-qualified table name

Returns:

SQL statement

string drop_column(const string &qual_name) const

Return string to drop the column via ALTER TABLE

Parameters:

qual_name – schema-qualified table name

Returns:

SQL statement

string rename_column(const string &qual_name, const string &oldname) const

Return SQL statement to RENAME the column

Parameters:

  • qual_name – schema-qualified table name

  • oldname – the old name of the column

Returns:

SQL statement

string identifier(const string &qual_name) const

Return a full identifier for the column

Parameters:

qual_name – schema-qualified table name

Returns:

string

vector<Statement> alter(const Column &rhs, const string &qual_name) const

Generate SQL to transform an existing column

Compares the column to an input column and generates partial SQL statements to transform it into the one represented by the input.

Parameters:

  • rhs – the new column definition

  • qual_name – schema-qualified table name

Returns:

list of partial SQL statements

YAML::Node to_yaml() const

Convert the column to a YAML node

Returns:

YAML node

inline int number() const

Return the ordinal position of the column

inline void set_number(int num)
inline std::optional<bool> not_null() const

Return the not null constraint, if set

inline void set_not_null(bool nn)
inline string default_val() const

Return the default value expression

inline void set_default(const string &d)
inline string description() const

Return the comment text for the column

inline void set_description(const string &d)

Public Static Functions

static string catalog_query(unsigned dbversion = 0)

Return the catalog query to load columns

Dropped columns are excluded since they must not appear in dbtoyaml output. When the diff/alter engine is implemented, dropped columns must be retained (with a “dropped” flag) so their attnum slots stay aligned for positional matching, as Pyrseas does.

Parameters:

dbversion – database server version (e.g. 160006 for 16.6), 0 for unknown; may alter the query on version-specific catalogs

Returns:

SQL query string

static Column from_yaml(const string &name, const YAML::Node &node)

Initialize a column from a YAML node

Parameters:

  • name – column name

  • node – YAML node defining the column

Returns:

Column instance

class Constraint : public perseid::Schema_object

A constraint definition, such as a primary key, foreign key or unique constraint. This also covers check constraints on domains.

Subclassed by perseid::Check_constraint, perseid::Foreign_key, perseid::Primary_key, perseid::Unique_constraint

Public Functions

Constraint() = default
Constraint(const string &name, const string &schema, const string &table, const string &description = {})

Constructor

Parameters:

  • name – constraint name

  • schema – schema name

  • table – table name

  • description – comment text

inline virtual string obj_type() const override

Type of object as an uppercase string, for SQL syntax generation

This is used in most CREATE, ALTER and DROP statements. It is also used by extern_key() in lowercase form.

Returns:

string

virtual string identifier() const override

Return a full identifier for the constraint

Returns:

quoted constraint name

string key_columns() const

Return comma-separated list of key column names

Returns:

string

virtual string add() const

Return string to add the constraint via ALTER TABLE

Works as is for primary keys and unique constraints but has to be overridden for check constraints and foreign keys.

Returns:

SQL statement

virtual vector<Statement> drop() const override

Return string to drop the constraint via ALTER TABLE

Returns:

SQL statement

string comment() const

Return SQL statement to create COMMENT on constraint

Returns:

SQL statement

virtual YAML::Node to_yaml() const

Convert the constraint to a YAML node

Returns:

YAML node

inline string table() const
inline void set_table(const string &tbl)
inline const vector<string> &columns() const
inline void set_columns(const vector<string> &cols)
inline void add_column(const string &col)
class Check_constraint : public perseid::Constraint

A check constraint definition

Public Functions

inline virtual string obj_type() const override

Type of object as an uppercase string, for SQL syntax generation

This is used in most CREATE, ALTER and DROP statements. It is also used by extern_key() in lowercase form.

Returns:

string

inline virtual vector<Statement> create() const override

Return SQL statements to create the object

Returns:

SQL statements

virtual string add() const override

Return string to add the CHECK constraint via ALTER TABLE

Returns:

SQL statement

virtual YAML::Node to_yaml() const override

Convert the check constraint to a YAML node

Returns:

YAML node

inline string expression() const
inline void set_expression(const string &expr)
Constraint() = default
Constraint(const string &name, const string &schema, const string &table, const string &description = {})

Constructor

Parameters:

  • name – constraint name

  • schema – schema name

  • table – table name

  • description – comment text

Public Static Functions

static std::string catalog_query(unsigned dbversion = 0)

Return the catalog query to load check constraints

Parameters:

dbversion – database server version (e.g. 160006 for 16.6), 0 for unknown; may alter the query on version-specific catalogs

Returns:

SQL query string

static Check_constraint from_yaml(const string &name, const string &schema, const string &table, const YAML::Node &node)

Initialize a check constraint from a YAML node

Parameters:

  • name – constraint name

  • schema – schema name

  • table – table name

  • node – YAML node defining the constraint

Returns:

Check_constraint instance

class Primary_key : public perseid::Constraint

A primary key constraint definition

Public Functions

inline virtual string obj_type() const override

Type of object as an uppercase string, for SQL syntax generation

This is used in most CREATE, ALTER and DROP statements. It is also used by extern_key() in lowercase form.

Returns:

string

inline virtual vector<Statement> create() const override

Return SQL statements to create the object

Returns:

SQL statements

virtual YAML::Node to_yaml() const override

Convert the primary key to a YAML node

Returns:

YAML node

inline string access_method() const
inline void set_access_method(const string &am)
Constraint() = default
Constraint(const string &name, const string &schema, const string &table, const string &description = {})

Constructor

Parameters:

  • name – constraint name

  • schema – schema name

  • table – table name

  • description – comment text

Public Static Functions

static std::string catalog_query(unsigned dbversion = 0)

Return the catalog query to load primary keys

Parameters:

dbversion – database server version (e.g. 160006 for 16.6), 0 for unknown; may alter the query on version-specific catalogs

Returns:

SQL query string

static Primary_key from_yaml(const string &name, const string &schema, const string &table, const YAML::Node &node)

Initialize a primary key from a YAML node

Parameters:

  • name – constraint name

  • schema – schema name

  • table – table name

  • node – YAML node defining the constraint

Returns:

Primary_key instance

class Foreign_key : public perseid::Constraint

A foreign key constraint definition

Public Functions

inline virtual string obj_type() const override

Type of object as an uppercase string, for SQL syntax generation

This is used in most CREATE, ALTER and DROP statements. It is also used by extern_key() in lowercase form.

Returns:

string

inline virtual vector<Statement> create() const override

Return SQL statements to create the object

Returns:

SQL statements

virtual string add() const override

Return string to add the foreign key via ALTER TABLE

Returns:

SQL statement

virtual YAML::Node to_yaml() const override

Convert the foreign key to a YAML node

Returns:

YAML node

inline string ref_schema() const
inline void set_ref_schema(const string &s)
inline string ref_table() const
inline void set_ref_table(const string &t)
inline const vector<string> &ref_columns() const
inline void set_ref_columns(const vector<string> &cols)
inline void add_ref_column(const string &col)
inline string on_update() const
inline void set_on_update(const string &action)
inline string on_delete() const
inline void set_on_delete(const string &action)
Constraint() = default
Constraint(const string &name, const string &schema, const string &table, const string &description = {})

Constructor

Parameters:

  • name – constraint name

  • schema – schema name

  • table – table name

  • description – comment text

Public Static Functions

static std::string catalog_query(unsigned dbversion = 0)

Return the catalog query to load foreign keys

Parameters:

dbversion – database server version (e.g. 160006 for 16.6), 0 for unknown; may alter the query on version-specific catalogs

Returns:

SQL query string

static Foreign_key from_yaml(const string &name, const string &schema, const string &table, const YAML::Node &node)

Initialize a foreign key from a YAML node

Parameters:

  • name – constraint name

  • schema – schema name

  • table – table name

  • node – YAML node defining the constraint

Returns:

Foreign_key instance

class Unique_constraint : public perseid::Constraint

A unique constraint definition

Public Functions

inline virtual string obj_type() const override

Type of object as an uppercase string, for SQL syntax generation

This is used in most CREATE, ALTER and DROP statements. It is also used by extern_key() in lowercase form.

Returns:

string

inline virtual vector<Statement> create() const override

Return SQL statements to create the object

Returns:

SQL statements

virtual YAML::Node to_yaml() const override

Convert the unique constraint to a YAML node

Returns:

YAML node

Constraint() = default
Constraint(const string &name, const string &schema, const string &table, const string &description = {})

Constructor

Parameters:

  • name – constraint name

  • schema – schema name

  • table – table name

  • description – comment text

Public Static Functions

static std::string catalog_query(unsigned dbversion = 0)

Return the catalog query to load unique constraints

Parameters:

dbversion – database server version (e.g. 160006 for 16.6), 0 for unknown; may alter the query on version-specific catalogs

Returns:

SQL query string

static Unique_constraint from_yaml(const string &name, const string &schema, const string &table, const YAML::Node &node)

Initialize a unique constraint from a YAML node

Parameters:

  • name – constraint name

  • schema – schema name

  • table – table name

  • node – YAML node defining the constraint

Returns:

Unique_constraint instance

Command-line arguments

struct Common_args

Common command line options shared by dbtoyaml and yamltodb

An argparse::ArgumentParser pre-populated with the PostgreSQL connection options common to both tools. Tool-specific options are added by each utility before parsing.

Public Functions

Common_args(const string &program, const string &description)

Create a parser with the common PostgreSQL options

Parameters:

  • program – argv[0], used for the usage line and –version output

  • description – text describing the program

Config config()

Build a database connection configuration from the parsed options.

void add_connection_options()

Register the server connection options in a “Connection options” help group. Called by parse_args after the tool-specific options so the latter appear before the group.

Public Members

string prog

Program name sans directories, e.g. “dbtoyaml”.

argparse::ArgumentParser parser
optional<int> perseid::parse_args(Common_args &cmd, int argc, char *argv[])

Parse the command line, displaying usage errors argparse-style

Parameters:

  • cmd – the parser created by the Common_args constructor

  • argc – number of arguments

  • argv – argument vector

Returns:

nullopt if parsing succeeded and execution should continue, otherwise the process exit code to return (0 for –help or –version, 1 for errors)