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 <raphael@pgmodeler.io>
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).
-
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 to PostgreSQL 9.6:
pgmodeler-cli --export-to-file --input demo.dbm --output demo.sql --pgsql-ver 9.6 -
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-to demodb --conn-alias local-db --apply-diff -
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 -
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 -
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 -
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
References
Apache Ant