v1.2.0 Summary Chapter 6: Advanced tools 6. Introduction 6.13. Command line interface
No documentation was found matching the provided version! Browsing the latest one.

6.13. Command line interface

The pgModeler command-line interface, or pgmodeler-cli, encapsulates the most important pgModeler operations like export, import, diff, and other auxiliary features. The idea behind the CLI is to enable the user to perform a set of operations over a model or database without the need to do the tasks in the graphical interface. This approach can be handy when dealing with software deployment, for instance.

To exemplify a software deployment using the CLI, let's say you need to export a model to a database server during the installation of Java-based software through the Apache Ant tool. You can easily integrate the pgmodeler-cli command to execute the export process, taking a database model file as an input parameter in the middle of the deployment process, like this:pgmodeler-cli -ed -if demo.dbm -ca local-db.

The command-line interface has dozens of parameters that can be combined to optimize operations to be executed. One important thing to observe is that the CLI accepts short and long parameters, and they can appear in any order. The options must be separated from their values (when accepted) by a blank space. All options are described below:

pgModeler Plus command line interface.
Version 1.2.0 - 20250430.550ab5e46 Qt 6.8.3
PostgreSQL Database Modeler Project - pgmodeler.io
Copyright 2006-2025 Raphael Araújo e Silva 

Usage: pgmodeler-cli [OPTIONS]
This CLI tool provides several operations with models and databases without needing to perform them
in pgModeler's graphical interface. All available options are described below.

Operation mode options: 
 -ef, --export-to-file            Exports the input model to SQL script file(s).
 -ep, --export-to-png             Exports the input model to a PNG image.
 -es, --export-to-svg             Exports the input model to a SVG file.
 -ec, --export-to-dict            Exports the input model to a data dictionary in HTML format.
 -ed, --export-to-dbms            Exports the input model directly to a PostgreSQL server.
 -lc, --list-conns                Lists the available connections in file connections.conf.
 -im, --import-db                 Import a database to an output file.
 -df, --diff                      Compares a model and a database or two databases, generating an SQL script to sync the latter with the former.
 -fm, --fix-model                 Tries to fix the structure of the input model file to make it loadable again.
 -cc, --create-configs            Creates pgModeler's configuration folder and files in the user's local storage.
 -mt, --dbm-mime-type [ACTION]    Handles the DBM file association to pgModeler binaries. The ACTION can be [install | uninstall].
 -h, --help                       Shows this help menu.

General options: 
 -if, --input [FILE]              Input model file (.dbm). Required for export and model fix operations.
 -id, --input-db [DBNAME]         Input database name. Required for import operation.
 -of, --output [FILE|DIRECTORY]   Output file or directory. Required for fixing models or exporting to SQL, HTML, PNG, or SVG.
 -v, --pgsql-ver                  Force the PostgreSQL syntax to the specified version when generating SQL code. The version string must be in the form [major].[minor], e.g., 17.0.
 -s, --silent                     Silent execution. Only critical messages and errors are displayed during the process.

SQL file export options: 
 -sp, --split                     The database model SQL code is split into several files, one per object.
 -ds, --dependencies              Includes the object's dependencies SQL code in the generated file. (Only for split mode)
 -cs, --children                  Includes the object's children SQL code in the generated file. (Only for split mode)
 -gt, --group-by-type             Instead of creating a separate SQL file per object, groups the SQL code of all objects of the same type in a single file. (Only for split mode)
 -gd, --gen-drop-script           Create a separate script containing the DROP commands to destroy objects in the database.

PNG and SVG export options: 
 -sg, --show-grid                 Draws the grid in the exported image.
 -sl, --show-delimiters           Draws the page delimiters in the exported image.
 -pp, --page-by-page              Each page will be exported in a separate image. (Only for PNG images)
 -oc, --override-bg-color         Don't use the original canvas color in the exported image; instead, a white background is used. (Only for PNG images)
 -zf, --zoom [FACTOR]             Applies a zoom (in percent) before export to an image. Accepted zoom interval: 0.1 to 5 (Only for PNG images)

Data dictionary export options: 
 -sp, --split                     The data dictionaries are generated in separate files inside the specified output directory.
 -ni, --no-index                  Avoids generating the index that is used to help navigate through the data dictionary.
 -md, --markdown                  Generates a data dictionary in Markdown format (.md) instead of HTML format.

DBMS export options: 
 -ir, --ignore-duplicates         Ignores errors related to duplicate objects that may exist in the server.
 -ic, --ignore-error-codes [LIST] Ignores additional errors by their codes. Provide a comma-separated list of alphanumeric codes.
 -dd, --drop-database             Drop the database before executing an export process.
 -ff, --force                     Forces the termination of all connections to the target database before dropping it. This option is ignored when exporting to PostgreSQL 12 or below.
 -do, --drop-objects              Runs the DROP commands attached to objects in which SQL code is enabled.
 -sm, --simulate                  Simulates an export process by executing all steps but undoing any modifications in the end.
 -tn, --use-tmp-names             Generates temporary names for database, roles, and tablespaces when in simulation mode.
 -nt, --non-transactional         Run the export process in a non-transactional mode where changes are not rolled back in case of errors.

Connection options: 
 -ca, --conn-alias [ALIAS]        Connection configuration alias to be used.
 -H, --host [HOST]                PostgreSQL host in which a task will operate.
 -p, --port [PORT]                PostgreSQL host listening port.
 -u, --user [USER]                PostgreSQL username.
 -w, --passwd [PASSWORD]          PostgreSQL user password.
 -D, --initial-db [DBNAME]        Connection's initial database.

Database import options: 
 -ie, --ignore-errors             Ignores all errors and tries to create as many objects as possible.
 -is, --import-sys-objs           Imports built-in system objects. This option may bloat the model due to importing unnecessary objects.
 -ix, --import-ext-objs           Imports extension objects. This option may bloat the model due to importing unnecessary objects.
 -cl, --comments-as-aliases       Uses objects' comments as aliases. This option affects objects graphically represented in the database model.
 -fo, --filter-objects [FILTER]   Imports only objects matching the filter(s). The FILTER must be formatted as type:pattern:mode.
 -om, --only-matching             Imports only objects matching the provided filter(s). Objects not matching the filter(s) are discarded.
 -mn, --match-by-name             Performs object matching based on their names instead of their signature ([schema].[name]).
 -fc, --force-children [OBJECTS]  Forces importing children objects related to tables/views/foreign tables matched by the filter(s). Provide a comma-separated list of types.
 -d, --debug-mode                 Runs the import in debug mode, printing all queries executed on the server.

Diff options: 
 -ct, --compare-to [DBNAME]       The database used in the comparison. All generated SQL code is applied to it.
 -pd, --partial                   Switches to partial diff operation. Provide object filters using the import option --filter-objects.
 -ff, --force                     Forces a full diff if the provided filters fail to retrieve objects for a partial diff operation.
 -st, --start-date                Matches database model objects with modification dates starting from the specified date. (Only for partial diff)
 -et, --end-date                  Matches database model objects with modification dates ending on the specified date. (Only for partial diff)
 -sd, --save                      Saves the generated diff code to the output file.
 -ad, --apply                     Applies the generated diff code to the database server.
 -np, --no-preview                Does not preview the generated diff code before applying it to the server.
 -dc, --drop-cluster-objs         Drops cluster-level objects like roles and tablespaces.
 -rv, --revoke-perms              Revokes existing permissions on the database. New permissions configured in the input model are still applied.
 -dm, --drop-missing              Drops missing objects. Generates DROP commands for objects present in the input model but not in the compared database.
 -fd, --force-drop-cols           Forces dropping missing columns and constraints. Only affects columns and constraints; other missing objects are preserved.
 -rn, --rename-db                 Renames the destination database when the involved databases have different names.
 -nd, --no-cascade                Disables cascade mode when dropping objects.
 -ns, --no-sequence-reuse         Disables sequence reuse on serial columns. Drops the old sequence assigned to a serial column and creates a new one.
 -ru, --recreate-unmod            Recreates unmodifiable objects (those that cannot be changed via ALTER command).
 -rm, --replace-mod               Replaces modifiable objects (those that support CREATE OR REPLACE command).
 -fr, --force-re-create [OBJECTS] Uses DROP and CREATE commands to fully modify changed objects. Provide a comma-separated list of types.

Model fix options: 
 -ft, --fix-tries [NUMBER]        Model fix attempts. When reaching the maximum count, invalid objects will be discarded.

File association options: 
 -sw, --system-wide               Applies DBM file association system-wide instead of for the current user only.
 -ff, --force                     Forces mime type installation or uninstallation.

Config files creation options: 
 -mo, --missing-only              Copies only missing configuration files to the user's local storage.
 -ff, --force                     Forces recreation of all configuration files. Backs up current settings.

Plugins options: 
 -lp, --list-plugins              Lists available plugins.
 -ip, --ignore-faulty             Ignores errors from plugins that failed to load.

SDBM export plug-in options: 
  -xs, --export-sdbm              Runs the export operation over a split database model (.sdbm)

SDBM fix plug-in options: 
  -fs, --fix-sdbm                 Runs the database model fix operation over a split model file (.sdbm)
  -ri, --rebuild-index            Rebuilds the index file by scanning subfolders on the input file path.


** When exporting to SQL file in split mode and none of the options --dependencies, --children, and --group-by-type
   are specified then the generated files will be named in such a way to reflect the correct creation order.

** The FILTER value in the --filter-objects option has the form type:pattern:mode. 
   * The section `type' is the type of object to be filtered and accepts the following values (invalid types ignored): 
     > any, schema, table, view, aggregate, cast, collation, constraint
     > conversion, domain, eventtrigger, extension, foreigndatawrapper, foreignserver, foreigntable, function
     > index, language, opclass, operator, opfamily, policy, procedure, role
     > rule, sequence, tablespace, transform, trigger, usermapping

   * The special type `any' allows writing a single filter that applies to all object types.

   * The `pattern' section is the text pattern matched against the objects' names.

   * The `mode' section defines how the pattern is matched. It accepts two values:
     > `wildcard' treats the pattern as a wildcard string when matching object names.
     > `regexp' treats the pattern as a Perl-like regular expression when matching object names.

   * The option --force-children takes effect only when used with --only-matching and prevents discarding children of matched tables.
     Other tables imported as dependencies of matched objects will have their children discarded.
     The comma-separated list of table children objects accepts these values:
     > constraint, index, policy, rule, trigger
     > Use the special keyword `all' to include all children objects.

   * NOTE: All comparisons during filtering are case-insensitive.
     Using filtering options may import additional objects due to automatic dependency resolution.

** The diff process supports all import-related options.
   It also accepts these export operation options: `--ignore-duplicates', `--ignore-error-codes', and `--non-transactional'.

** The partial diff operation always forces the options --only-matching and --force-children = all for more reliable results.
   * The options --start-date and --end-date accept ISO8601 date/time format: `yyyy-MM-dd hh:mm:ss'.

** When diffing between two databases (--input-db and --compare-to), you can specify separate connections/aliases.
   If only one connection is specified, it will be used for both the input database and the comparison database.
   To specify a second connection, append `1' to any connection parameter listed above.
   This associates the connection exclusively with --compare-to.

Operation mode options

Parameter Description
-ef, --export-to-file Exports the input model to SQL script file(s).
-ep, --export-to-png Exports the input model to a PNG image.
-es, --export-to-svg Exports the input model to a SVG file.
-ec, --export-to-dict Exports the input model to a data dictionary in HTML format.
-ed, --export-to-dbms Exports the input model directly to a PostgreSQL server.
-lc, --list-conns Lists the available connections in file connections.conf.
-im, --import-db Import a database to an output file.
-df, --diff Compares a model and a database or two databases, generating an SQL script to sync the latter with the former.
-fm, --fix-model Tries to fix the structure of the input model file to make it loadable again.
-cc, --create-configs Creates pgModeler's configuration folder and files in the user's local storage.
-mt, --dbm-mime-type [ACTION] Handles the DBM file association to pgModeler binaries. The ACTION can be [install | uninstall].
-h, --help Shows this help menu.

General options

Parameter Description
-if, --input [FILE] Input model file (.dbm). Required for export and model fix operations.
-id, --input-db [DBNAME] Input database name. Required for import operation.
-of, --output [FILE|DIRECTORY] Output file or directory. Required for fixing models or exporting to SQL, HTML, PNG, or SVG.
-v, --pgsql-ver Force the PostgreSQL syntax to the specified version when generating SQL code. The version string must be in the form [major].[minor], e.g., 17.0.
-s, --silent Silent execution. Only critical messages and errors are displayed during the process.

SQL file export options

Parameter Description
-sp, --split The database model SQL code is split into several files, one per object.
-ds, --dependencies Includes the object's dependencies SQL code in the generated file. (Only for split mode)
-cs, --children Includes the object's children SQL code in the generated file. (Only for split mode)
-gt, --group-by-type Instead of creating a separate SQL file per object, groups the SQL code of all objects of the same type in a single file. (Only for split mode)
-gd, --gen-drop-script Create a separate script containing the DROP commands to destroy objects in the database.

PNG and SVG export options

Parameter Description
-sg, --show-grid Draws the grid in the exported image.
-sl, --show-delimiters Draws the page delimiters in the exported image.
-pp, --page-by-page Each page will be exported in a separate image. (Only for PNG images)
-oc, --override-bg-color Don't use the original canvas color in the exported image; instead, a white background is used. (Only for PNG images)
-zf, --zoom [FACTOR] Applies a zoom (in percent) before export to an image. Accepted zoom interval: 0.1-%4 (Only for PNG images)

Data dictionary export options

Parameter Description
-sp, --split The data dictionaries are generated in separate files inside the specified output directory.
-ni, --no-index Avoids generating the index that is used to help navigate through the data dictionary.
-md, --markdown Generates a data dictionary in Markdown format (.md) instead of HTML format.

DBMS export options

Parameter Description
-ir, --ignore-duplicates Ignores errors related to duplicate objects that may exist in the server.
-ic, --ignore-error-codes [LIST] Ignores additional errors by their codes. Provide a comma-separated list of alphanumeric codes.
-dd, --drop-database Drop the database before executing an export process.
-ff, --force Forces the termination of all connections to the target database before dropping it. This option is ignored when exporting to PostgreSQL 12 or below.
-do, --drop-objects Runs the DROP commands attached to objects in which SQL code is enabled.
-sm, --simulate Simulates an export process by executing all steps but undoing any modifications in the end.
-tn, --use-tmp-names Generates temporary names for database, roles, and tablespaces when in simulation mode.
-nt, --non-transactional Run the export process in a non-transactional mode where changes are not rolled back in case of errors.

Connection options

Parameter Description
-ca, --conn-alias [ALIAS] Connection configuration alias to be used.
-H, --host [HOST] PostgreSQL host in which a task will operate.
-p, --port [PORT] PostgreSQL host listening port.
-u, --user [USER] PostgreSQL username.
-w, --passwd [PASSWORD] PostgreSQL user password.
-D, --initial-db [DBNAME] Connection's initial database.

Database import options

Parameter Description
-ie, --ignore-errors Ignores all errors and tries to create as many objects as possible.
-is, --import-sys-objs Imports built-in system objects. This option may bloat the model due to importing unnecessary objects.
-ix, --import-ext-objs Imports extension objects. This option may bloat the model due to importing unnecessary objects.
-cl, --comments-as-aliases Uses objects' comments as aliases. This option affects objects graphically represented in the database model.
-fo, --filter-objects [FILTER] Imports only objects matching the filter(s). The FILTER must be formatted as type:pattern:mode.
-om, --only-matching Imports only objects matching the provided filter(s). Objects not matching the filter(s) are discarded.
-mn, --match-by-name Performs object matching based on their names instead of their signature ([schema].[name]).
-fc, --force-children [OBJECTS] Forces importing children objects related to tables/views/foreign tables matched by the filter(s). Provide a comma-separated list of types.
-d, --debug-mode Runs the import in debug mode, printing all queries executed on the server.

Diff options

Parameter Description
-ct, --compare-to [DBNAME] The database used in the comparison. All generated SQL code is applied to it.
-pd, --partial Switches to partial diff operation. Provide object filters using the import option --filter-objects.
-ff, --force Forces a full diff if the provided filters fail to retrieve objects for a partial diff operation.
-st, --start-date Matches database model objects with modification dates starting from the specified date. (Only for partial diff)
-et, --end-date Matches database model objects with modification dates ending on the specified date. (Only for partial diff)
-sd, --save Saves the generated diff code to the output file.
-ad, --apply Applies the generated diff code to the database server.
-np, --no-preview Does not preview the generated diff code before applying it to the server.
-dc, --drop-cluster-objs Drops cluster-level objects like roles and tablespaces.
-rv, --revoke-perms Revokes existing permissions on the database. New permissions configured in the input model are still applied.
-dm, --drop-missing Drops missing objects. Generates DROP commands for objects present in the input model but not in the compared database.
-fd, --force-drop-cols Forces dropping missing columns and constraints. Only affects columns and constraints; other missing objects are preserved.
-rn, --rename-db Renames the destination database when the involved databases have different names.
-nd, --no-cascade Disables cascade mode when dropping objects.
-ns, --no-sequence-reuse Disables sequence reuse on serial columns. Drops the old sequence assigned to a serial column and creates a new one.
-ru, --recreate-unmod Recreates unmodifiable objects (those that cannot be changed via ALTER command).
-rm, --replace-mod Replaces modifiable objects (those that support CREATE OR REPLACE command).
-fr, --force-re-create [OBJECTS] Uses DROP and CREATE commands to fully modify changed objects. Provide a comma-separated list of types.

Model fix options

Parameter Description
-ft, --fix-tries [NUMBER] Model fix attempts. When reaching the maximum count, invalid objects will be discarded.

File association options

Parameter Description
-sw, --system-wide Applies DBM file association system-wide instead of for the current user only.
-ff, --force Forces mime type installation or uninstallation.

Config files creation options

Parameter Description
-mo, --missing-only Copies only missing configuration files to the user's local storage.
-ff, --force Forces recreation of all configuration files. Backs up current settings.

Plugins options

Parameter Description
-lp, --list-plugins Lists available plugins.
-ip, --ignore-faulty Ignores errors from plugins that failed to load.

SDBM export plug-in options

Parameter Description
-xs, --export-sdbm Runs the export operation over a split database model (.sdbm)

SDBM fix plug-in options

Parameter Description
-fs, --fix-sdbm Runs the database model fix operation over a split model file (.sdbm)
-ri, --rebuild-index Rebuilds the index file by scanning subfolders on the input file path.


Despite the usefulness of the command line interface there are two important limitations in the tool which need to be described. The first one is that only one operation is supported per execution, in other words, the parameters --export-to-file, --export-to-png, --export-to-svg, --export-to-dbms, --import-db, --diff, --fix-model and --dbm-mime-type can't appear in the same command call. The second limitation is that in any operation that produces an output file based upon the input model you are obligated to specify the input and output files and these files should have different names or the process will be aborted.

6.13.1. Command line examples

Below we have some command samples, an important note to be given is that on any operation that involves the connection to a database server, you can either use the parameter --conn-alias alone or specify the entire connection configuration using the rest of the connection options (see above).

  1. Export a model to the server using a connection alias:
    pgmodeler-cli --export-to-dbms --input demo.dbm --conn-alias local-db

  2. Export a model to the server using the connections options:
    pgmodeler-cli --export-to-dbms --input demo.dbm --host localhost --user myuser --passwd mypass --initial-db mydb

  3. Export a model to PNG file applying a zoom factor of 200%:
    pgmodeler-cli --export-to-png --input demo.dbm --output demo.png --zoom 200

  4. Export a model to SQL script forcing the generation of code to PostgreSQL 9.6:
    pgmodeler-cli --export-to-file --input demo.dbm --output demo.sql --pgsql-ver 9.6

  5. Import a database ignoring errors and in debug mode:
    pgmodeler-cli --import-db --input-db demodb --output demo_imported.dbm --conn-alias local-db --ignore-errors --debug-mode

  6. Diff a model and a database applying the changes on the server:
    pgmodeler-cli --diff --input demo.dbm --compare-to demodb --conn-alias local-db --apply-diff

  7. Diff two databases living on different servers using connection aliases:
    pgmodeler-cli --diff --input-db pagila --compare-to demodb --conn-alias local-db --conn-alias1 remote-db --apply-diff

  8. Diff two databases living on different servers using connection parameters and saving the diff to a file:
    pgmodeler-cli --diff --input-db pagila --compare-to demodb --output diff.sql -H localhost -u postgres -w postgres -D postgres -H1 localhost -u1 postgres -w1 postgres -D1 postgres --save-diff

  9. Perform a partial diff by using objects modified in the model since June, 1st:
    pgmodeler-cli --diff --partial --input my_model.dbm --compare-to my_database --conn-alias local-db --start-date 2020-06-01 --apply

  10. Perform a partial diff between two databases and filter all tables and their children residing in the schema schema_a:
    pgmodeler-cli --diff --partial --input-db my_dev_db --compare-to my_prod_db --conn-alias local-db --apply --filter-objects "table:schema_a.*:wildcard" --force-children all


Apr 30, 2025 at 15:50