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 2.0.0 - 20261012. Qt 6.10.3
PostgreSQL Database Modeler Project - pgmodeler.io
(c) Copyright 2006-2026 Raphael Araújo e Silva <raphael@pgmodeler.io>
Development, maintenance and commercial distribution by:
Nullptr Labs Software e Tecnologia LTDA <contact@nullptrlabs.io>
This tool provides a command-line interface for the main operations
available in GUI. All available options are described below.
Usage: pgmodeler-cli [OPTIONS]
# 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 an 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.
-im, --import-db Imports a database to an output file.
-df, --diff Compares a model and a database or two databases. ↲
Generates an SQL script to synchronize the latter with the former.
-lc, --list-conns Lists the available connections. File location: connections.conf.
-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. ↲
Stored in the user's local storage.
-mt, --dbm-mime-type [ACTION] Handles the DBM file association to pgModeler binaries. ↲
Available actions: [install | uninstall].
-h, --help Shows this help menu.
-v, --version Prints the version info and exit.
# 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 model fix or export to SQL, HTML, PNG, SVG.
-pv, --pgsql-ver Forces PostgreSQL syntax to the specified version when generating SQL code. ↲
Version format: [major].[minor], e.g., 18.0.
-ne, --no-escape-comments Disables E'' escape-string syntax on COMMENT ON statements during export. ↲
All comments are written in the common string syntax.
-s, --silent Silent execution. Only critical messages and errors are displayed.
# 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 Groups the SQL code of all objects of the same type in a single file. ↲
Only for split mode.
-gd, --gen-drop-script Creates a separate script with DROP commands. Used to destroy database objects.
# 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 as a separate image. Only for PNG images.
-oc, --override-bg-color Overrides the original canvas color using a white background. PNG images only.
-zf, --zoom [FACTOR] Applies zoom before exporting to an image. Accepted range: 0.1 to 5 (PNG only).
# Data dictionary export options:
-sp, --split Data dictionaries are generated in separate files. ↲
Placed inside the specified output directory.
-ni, --no-index Avoids generating the navigation index. ↲
Used to 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 on the server.
-ic, --ignore-error-codes [LIST] Ignores additional errors by their error codes. ↲
Provide comma-separated alphanumeric codes.
-dd, --drop-database Drops the database before executing the export process.
-ff, --force Forces termination of all connections to the target database before dropping it. ↲
Ignored on PostgreSQL 12 or earlier.
-do, --drop-objects Executes DROP commands attached to objects with enabled SQL code.
-sm, --simulate Simulates the export process by executing all steps. ↲
Rolls back any modifications at the end.
-tn, --use-tmp-names Generates temporary names for databases, roles, and tablespaces. ↲
Used in simulation mode.
-nt, --non-transactional Executes the export process in non-transactional mode. ↲
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 on which the 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. Tries to create as many objects as possible.
-is, --import-sys-objs Imports built-in system objects. May increase model size due to unnecessary objects.
-ix, --import-ext-objs Imports extension objects. May increase model size due to unnecessary objects.
-cl, --comments-as-aliases Uses objects' comments as aliases. ↲
Affects objects graphically represented in the model.
-fo, --filter-objects [FILTER] Imports only objects matching the filter(s). FILTER format: type:pattern:mode.
-om, --only-matching Imports only objects matching the provided filter(s). ↲
Non-matching objects are discarded.
-mn, --match-by-name Performs object matching based on names. Does not use signatures ([schema].[name]).
-fc, --force-children [OBJECTS] Forces importing child objects related to tables/views/foreign tables. ↲
Provide comma-separated list of types.
-d, --debug-mode Executes the import in debug mode. Prints all queries executed on the server.
-se, --seg-mode [MODE] Segments the imported model's canvas into multiple scenes. ↲
Available modes: [schema | threshold].
-th, --seg-threshold [NUMBER] Number of tables/views/foreign tables per scene. Only for --seg-mode threshold.
-hr, --hide-rels Hides the relationships between tables of the same scene in the imported model.
# Diff options:
-cf, --compare-file [FILE] The database model file used in the comparison. Implies the use of option --save.
-cd, --compare-db [DBNAME] The database used in the comparison. All generated SQL is applied to it.
-pd, --partial Switches to partial diff operation. ↲
Provide object filters using import option --filter-objects.
-ff, --force Forces a full diff if the provided filters fail. Used for partial diff operations.
-st, --start-date Matches model objects with modification dates from the specified date. ↲
Only for partial diff.
-et, --end-date Matches model objects with modification dates up to 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 Skips previewing the generated diff code before applying it to the server.
-dc, --drop-cluster-objs Drops cluster-level objects such as roles and tablespaces.
-rv, --revoke-perms Revokes existing permissions on the database. ↲
New permissions from input model are applied.
-dm, --drop-missing Generates DROP commands for objects present in source model. ↲
Targets objects missing from compared database.
-fd, --force-drop-cols Forces dropping missing 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 existing sequence and creates a new one.
-ru, --recreate-unmod Recreates unmodifiable objects. These cannot be changed via ALTER command.
-rm, --replace-mod Replaces modifiable objects. These support CREATE OR REPLACE command.
-fr, --force-re-create [OBJECTS] Uses DROP and CREATE commands to completely modify changed objects. ↲
Provide comma-separated list of types.
# Model fix options:
-ft, --fix-tries [NUMBER] Model fix attempts. Invalid objects are discarded when reaching maximum count.
# 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 and 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, if none of the options --dependencies, --children,
and --group-by-type are specified, the generated files will be named to reflect the correct order.
** The FILTER value in the --filter-objects option has the form type:pattern:mode.
* The section `type' is the type of the filtered object being (invalid types are 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 to match against object names.
* The `mode' section defines how the pattern matching is performed. 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 child objects accepts these values:
> constraint, index, policy, rule, trigger
> Use the special keyword `all' to include all child 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 always forces the options --only-matching and --force-children = all for better 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-db), 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-db.
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 an 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. |
-im, --import-db | Imports a database to an output file. |
-df, --diff | Compares a model and a database or two databases. Generates an SQL script to synchronize the latter with the former. |
-lc, --list-conns | Lists the available connections. File location: connections.conf. |
-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. Stored in the user's local storage. |
-mt, --dbm-mime-type [ACTION] | Handles the DBM file association to pgModeler binaries. Available actions: [install | uninstall]. |
-h, --help | Shows this help menu. |
-v, --version | Prints the version info and exit. |
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 model fix or export to SQL, HTML, PNG, SVG. |
-pv, --pgsql-ver | Forces PostgreSQL syntax to the specified version when generating SQL code. Version format: [major].[minor], e.g., 18.0. |
-ne, --no-escape-comments | Disables E'' escape-string syntax on COMMENT ON statements during export. All comments are written in the common string syntax. |
-s, --silent | Silent execution. Only critical messages and errors are displayed. |
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 | Groups the SQL code of all objects of the same type in a single file. Only for split mode. |
-gd, --gen-drop-script | Creates a separate script with DROP commands. Used to destroy database objects. |
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 as a separate image. Only for PNG images. |
-oc, --override-bg-color | Overrides the original canvas color using a white background. PNG images only. |
-zf, --zoom [FACTOR] | Applies zoom before exporting to an image. Accepted range: 0.1 to 5 (PNG only). |
Data dictionary export options
| Parameter | Description |
|---|---|
-sp, --split | Data dictionaries are generated in separate files. Placed inside the specified output directory. |
-ni, --no-index | Avoids generating the navigation index. Used to 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 on the server. |
-ic, --ignore-error-codes [LIST] | Ignores additional errors by their error codes. Provide comma-separated alphanumeric codes. |
-dd, --drop-database | Drops the database before executing the export process. |
-ff, --force | Forces termination of all connections to the target database before dropping it. Ignored on PostgreSQL 12 or earlier. |
-do, --drop-objects | Executes DROP commands attached to objects with enabled SQL code. |
-sm, --simulate | Simulates the export process by executing all steps. Rolls back any modifications at the end. |
-tn, --use-tmp-names | Generates temporary names for databases, roles, and tablespaces. Used in simulation mode. |
-nt, --non-transactional | Executes the export process in non-transactional mode. 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 on which the 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. Tries to create as many objects as possible. |
-is, --import-sys-objs | Imports built-in system objects. May increase model size due to unnecessary objects. |
-ix, --import-ext-objs | Imports extension objects. May increase model size due to unnecessary objects. |
-cl, --comments-as-aliases | Uses objects' comments as aliases. Affects objects graphically represented in the model. |
-fo, --filter-objects [FILTER] | Imports only objects matching the filter(s). FILTER format: type:pattern:mode. |
-om, --only-matching | Imports only objects matching the provided filter(s). Non-matching objects are discarded. |
-mn, --match-by-name | Performs object matching based on names. Does not use signatures ([schema].[name]). |
-fc, --force-children [OBJECTS] | Forces importing child objects related to tables/views/foreign tables. Provide comma-separated list of types. |
-d, --debug-mode | Executes the import in debug mode. Prints all queries executed on the server. |
-se, --seg-mode [MODE] | Segments the imported model's canvas into multiple scenes. Available modes: [schema | threshold]. |
-th, --seg-threshold [NUMBER] | Number of tables/views/foreign tables per scene. Only for --seg-mode threshold. |
-hr, --hide-rels | Hides the relationships between tables of the same scene in the imported model. |
Diff options
| Parameter | Description |
|---|---|
-cf, --compare-file [FILE] | The database model file used in the comparison. Implies the use of option --save. |
-cd, --compare-db [DBNAME] | The database used in the comparison. All generated SQL is applied to it. |
-pd, --partial | Switches to partial diff operation. Provide object filters using import option --filter-objects. |
-ff, --force | Forces a full diff if the provided filters fail. Used for partial diff operations. |
-st, --start-date | Matches model objects with modification dates from the specified date. Only for partial diff. |
-et, --end-date | Matches model objects with modification dates up to 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 | Skips previewing the generated diff code before applying it to the server. |
-dc, --drop-cluster-objs | Drops cluster-level objects such as roles and tablespaces. |
-rv, --revoke-perms | Revokes existing permissions on the database. New permissions from input model are applied. |
-dm, --drop-missing | Generates DROP commands for objects present in source model. Targets objects missing from compared database. |
-fd, --force-drop-cols | Forces dropping missing 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 existing sequence and creates a new one. |
-ru, --recreate-unmod | Recreates unmodifiable objects. These cannot be changed via ALTER command. |
-rm, --replace-mod | Replaces modifiable objects. These support CREATE OR REPLACE command. |
-fr, --force-re-create [OBJECTS] | Uses DROP and CREATE commands to completely modify changed objects. Provide comma-separated list of types. |
Model fix options
| Parameter | Description |
|---|---|
-ft, --fix-tries [NUMBER] | Model fix attempts. Invalid objects are discarded when reaching maximum count. |
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 and 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-dict, --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 on the input model, you must specify the input and output files, and they must have different names, or the process will be aborted.
Command line examples
Below are some command samples. Note that, on any operation that involves a 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).
-
Export a model to the server using a connection alias:
pgmodeler-cli --export-to-dbms --input demo.dbm --conn-alias local-db -
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 -
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 -
Export a model to SQL script forcing the generation of code for PostgreSQL 15:
pgmodeler-cli --export-to-file --input demo.dbm --output demo.sql --pgsql-ver 15.0 -
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 -
Diff a model and a database applying the changes on the server:
pgmodeler-cli --diff --input demo.dbm --compare-db demodb --conn-alias local-db --apply -
Diff two databases living on different servers using connection aliases:
pgmodeler-cli --diff --input-db pagila --compare-db demodb --conn-alias local-db --conn-alias1 remote-db --apply -
Diff two databases living on different servers using connection parameters and saving the diff to a file:
pgmodeler-cli --diff --input-db pagila --compare-db demodb --output diff.sql -H localhost -u postgres -w postgres -D postgres -H1 localhost -u1 postgres -w1 postgres -D1 postgres --save -
Perform a partial diff by using objects modified in the model since June 1st:
pgmodeler-cli --diff --partial --input my_model.dbm --compare-db my_database --conn-alias local-db --start-date 2020-06-01 --apply -
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-db my_prod_db --conn-alias local-db --apply --filter-objects "table:schema_a.*:wildcard" --force-children all -
Compare two model files, saving the diff code to a file:
pgmodeler-cli --diff --input demo.dbm --compare-file demo_old.dbm --output diff.sql
References
Apache Ant
http://ant.apache.org