Skip to main content
Version: 1.2.0

Installation

warning

pgModeler 1.x series is no longer receiving support. We recommend upgrading to a 2.x release. See the pgModeler 2.x installation page for up-to-date instructions.

This page gives some essential instructions about building pgModeler from source, installing, and running it on all supported platforms. Please, read it carefully and avoid skipping any steps below even if you're an experienced user in compiling software from source. If you stumble on any problem just ask for help at the GitHub issues page by posting as many details as possible about it so the correct support can be provided. Finally, if you find any error in this document, please report it so the proper fixes can be applied. All suggestions or constructive criticisms to make the building steps easier to understand are welcome!

Requirements overview​

On all supported platforms, the first requirement is the Qt framework in at least the version 6.6.x. At the moment these instructions were being updated, Qt 6.10.3 was the latest stable version. Make sure to use a compatible version to avoid any further problems in the steps below.

Bear in mind that failing to observe this first requirement in most cases will cause the compilation to fail due to incompatibilities between pgModeler's source code and the Qt framework, or even the deployment steps below may not be enough to make the software work after a successful build.

Second, you will need a PostgreSQL server installation. In this document we are using the RDBMS in its version 17, so note that the location of headers and libraries in the settings below may vary depending on the version of the database system you've chosen.

Finally, you will need to download a fresh copy of pgModeler's source code. See the source download form for more details about retrieving the source code. Once the source code is retrieved, extract it (in case of using a tarball) and run all the commands in the below sections from the root folder.

Important notes

  1. Some Linux distros already deliver Qt framework runtime libraries and development packages, but in some few cases, the system installs different versions of the framework causing incompatibilities during the execution of the compilation procedures, so in order to make this step-by-step as simple as possible make sure to be using the Qt version compatible with the codebase being built.

  2. Due to the constant improvements in the Qt framework some deprecation warnings may be displayed during the building process. These warnings are harmless in 99.9% of cases but if the build is aborted due to errors that may point out some incompatibility, please, report it as soon as possible so a patch can be applied to pgModeler's source.

Platform specific requirements​

1) Qt framework: in the majority of Linux distros the Qt framework is provided by their package repositories, just make sure to install the runtime libraries and development packages. For these procedures, please refer to your preferred distro's docs for more information about the installation of the framework. To check if Qt is correctly installed run the command in the line (1) below in the console. If the result is similar to the lines (2) and (3), then the Qt framework is already installed. If an error is returned you need to check the installation.

qmake -version
QMake version 3.1
Using Qt version [version] in /usr/lib64

2) GCC or Clang compiler: pgModeler is coded in C++ language, so make sure to have a version of the mentioned compilers installed that supports C++17 in order to enable full language support.

3) XML2 library: generally the runtime files are already installed but the needed headers are absent in most cases. Make sure to access your distro's software management and install the development packages for XML2 which bundles the source code and libraries for compilation purposes. To check if the library is correctly installed run the command in the line (1) below in the console. If the result is similar to the line (2), then libxml2 is already installed. If an error is returned, you need to check the installation.

pkg-config libxml-2.0 --cflags --libs
-I/usr/include/libxml2 -lxml2

4) PostgreSQL client library: the communication between pgModeler and a database server is made through the PostgreSQL client interface called libpq. The library installation details are retrieved via pkg-config command during compile time so to check if everything is okay run the command on line (1) in the console. If the result is similar to the line (2), then the library is correctly installed. If an error is returned, you need to check the installation.

pkg-config libpq --cflags --libs
-I/usr/include -L/usr/lib64/libpq.so

Tweaking the building script​

If you are compiling pgModeler on Windows or macOS there is a preliminary step before running the main compilation command. You need to configure the location of the dependency headers and libraries by editing the file pgmodeler.pri. Assuming that you've already got the source code, open the mentioned file in your favorite text editor and locate the following lines:

windows {
  !defined(PGSQL_LIB, var): PGSQL_LIB = C:/msys64/mingw64/bin/libpq.dll
  !defined(PGSQL_INC, var): PGSQL_INC = C:/msys64/mingw64/include
  !defined(XML_INC, var): XML_INC = C:/msys64/mingw64/include/libxml2
  !defined(XML_LIB, var): XML_LIB = C:/msys64/mingw64/bin/libxml2-2.dll
  ...
}
macx {
  PGSQL_LIB = /Library/PostgreSQL/16/lib/libpq.dylib
  PGSQL_INC = /Library/PostgreSQL/16/include
  XML_INC = /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/usr/include/libxml2
  XML_LIB = /usr/lib/libxml2.dylib
  ...
}

Make sure to edit only the section corresponding to your platform. You need to change the values of the variables PGSQL_LIB, PGSQL_INC, XML_INC and XML_LIB. These variables tell the compiler where to find the headers and libraries for libxml2 as well as libpq.

Update the values according to the location of the files or folders in your system. Save the file and proceed to the next step.

Building the software​

We are now able to run the main building process. This step differs a bit on each operating system and it is described below. All the commands must be executed inside the console and from the root of the pgModeler's source code folder. In Windows systems remember to run the commands from the MSYS2 MinGW 64-bit console available under MSYS2 group at start menu.

In the following procedures, to shorten the commands, we are assuming that $QT_ROOT is the full path to the Qt installation which varies from system to system, so remember to replace the variable with the real path according to your system.

The variable $INSTALLATION_ROOT is the path where pgModeler should be installed after the building process is complete. Again, don't forget to replace the variables by the respective full path according to the running operating system.

$QT_ROOT/bin/qmake -r CONFIG+=release PREFIX=$INSTALLATION_ROOT BINDIR=$INSTALLATION_ROOT \
                   PRIVATEBINDIR=$INSTALLATION_ROOT PRIVATELIBDIR=$INSTALLATION_ROOT/lib pgmodeler.pro
make
make install

Resolving dependencies​

After successfully compiling the source code and installing the binaries we need to copy some dependencies into the pgModeler's installation folder and run some commands to make the binaries locate them properly. As in the previous section, in the steps below replace the variable $INSTALLATION_ROOT by the path where pgModeler is now installed. The variable $PGSQL_ROOT must be replaced by the full path to PostgreSQL's installation folder. The variable $PGMODELER_SOURCE must be replaced by the full path to pgModeler's source code directory, and $MSYS2_ROOT must be replaced by the full path to MSYS2 installation (only for Windows).

Note to Windows users

Since pgModeler building relies on MSYS2 infrastructure, depending on the version of the latter in your system, the DLLs to be copied in the steps below may not be enough.

So, the recommendation is that you run the copy commands below as is and try to run pgModeler in the destination folder. If any error regarding a missing DLL is reported you can copy that one DLL from MSYS2 folder to pgModeler's installation path. This procedure must be repeated until the software runs without errors.

Please, don't forget to report which DLLs are missing so this step-by-step can be updated accordingly.

mkdir $INSTALLATION_ROOT/lib/qtplugins
mkdir $INSTALLATION_ROOT/lib/qtplugins/imageformats
mkdir $INSTALLATION_ROOT/lib/qtplugins/printsupport
mkdir $INSTALLATION_ROOT/lib/qtplugins/platforms
echo -e "[Paths]\nPrefix=.\nPlugins=lib/qtplugins\nLibraries=lib" > $INSTALLATION_ROOT/qt.conf
cd $QT_ROOT/lib
cp libQt6DBus.so.6 libQt6PrintSupport.so.6 libQt6Widgets.so.6 libQt6Network.so.6 libQt6Gui.so.6 \
   libQt6XcbQpa.so.6 libQt6Core.so.6 libQt6Svg.so.6 libicui18n.so.* libicuuc.so.* libicudata.so.* $INSTALLATION_ROOT/lib
cd $QT_ROOT/plugins
cp -r imageformats/libqgif.so imageformats/libqico.so imageformats/libqjpeg.so \
      imageformats/libqsvg.so $INSTALLATION_ROOT/lib/qtplugins/imageformats
cp -r printsupport/libcupsprintersupport.so $INSTALLATION_ROOT/lib/qtplugins/printsupport
cp -r platforms/libqxcb.so platforms/libqoffscreen.so $INSTALLATION_ROOT/lib/qtplugins/platforms
mkdir $INSTALLATION_ROOT/lib/qtplugins/tls
cp -r platforms/tls/* $INSTALLATION_ROOT/lib/qtplugins/tls

Running pgModeler​

Finally, pgModeler can be started. Just open the installation folder and double click the application pgmodeler.exe (Windows), pgmodeler (Linux) or pgmodeler.app (macOS) and have fun.

Enjoy!

Environment variables​

pgModeler uses eleven custom environment variables in order to keep track of its resource files, directories, and executables. You seldom need to use them but if you want to configure different locations of these resources you must specify them before running the tool. Each variable has a special meaning and they are described as follows:

VariableDescription
PGMODELER_SCHEMAS_DIRStores the path to the schemas folder. This folder contains all the files needed to generate SQL and XML code.
PGMODELER_CONF_DIRStores the path to the conf folder. This folder contains all the configuration files for the current user.
PGMODELER_TMPL_CONF_DIRStores the path to the template conf folder. This folder contains all the template configuration files that are copied for all users.
PGMODELER_LANG_DIRStores the path to the lang folder. This folder contains all available UI translations.
PGMODELER_PLUGINS_DIRStores the path to the plugins folder. This folder contains all the available plug-ins.
PGMODELER_TMP_DIRStores the path to the tmp folder. This folder is used by pgModeler to write temporary models as well as log files for certain operations.
PGMODELER_SAMPLES_DIRStores the path to the samples folder. This folder contains the samples models.
PGMODELER_CH_PATHStores the path to the crash handler executable called pgmodeler-ch.
PGMODELER_CLI_PATHStores the path to the command line interface executable called pgmodeler-cli.
PGMODELER_SE_PATHStores the path to the schema file editor executable called pgmodeler-se.
PGMODELER_PATHStores the path to the main executable called pgmodeler.

Custom build parameters​

This optional section describes how the build process can be customized in such a way that the files are generated in different directories other than the default ones. This way pgModeler introduces eleven custom parameters that can be passed to qmake in order to configure the custom output folders. The use of custom build parameters is a good mechanism for package maintainers (in case of Linux distros) to create custom releases that better suit each system's requirements. The details of these parameters and how they can be used are shown in the table below. Note that if you modify the value of any custom parameter you'll need to reflect these changes on the building steps above.

ParameterDescription
PREFIXThe path to the root directory where the compiled files will be placed.
BINDIRThe path to the folder where executables accessible by the user will reside.
CONFDIRThe path to the folder where the pgModeler's template configuration folder conf will be installed.
DOCDIRThe path to the folder where the documentation related files are placed.
LANGDIRThe path to the folder where the UI translation folder lang resides.
SAMPLESDIRThe path to the folder where the sample models folder samples resides.
SCHEMASDIRThe path to the folder where the object's schemas folder schemas resides.
SHAREDIRThe path to the folder where shared files and resources must be placed. Generally, this is the root path where folders like lang, samples and schemas will be placed.
PRIVATEBINDIRThe path to the folder where executables not directly accessible by the user will be placed (e.g. crash handler executable – pgmodeler-ch).
PRIVATELIBDIRThe path to the folder where libraries not directly shared through the system will reside.
PLUGINSDIRThe path to the folder where third party plug-ins are installed.

Now, to use one of these parameters run qmake as following:

$QT_ROOT/bin/qmake pgmodeler.pro PREFIX=[PATH] BINDIR=[PATH] CONFDIR=[PATH]

After running qmake command with the custom parameters a small summary is displayed so you can check if the configured variables really point to the desired locations. From here, you can (re)build the application by following the building steps from previous sections so the changes in the custom parameters can take effect.

** pgModeler build details **

PREFIX = /home/user/pgmodeler/build
BINDIR = /home/user/pgmodeler/build
PRIVATEBINDIR = /home/user/pgmodeler/build
PRIVATELIBDIR = /home/user/pgmodeler/build
PLUGINSDIR = /home/user/pgmodeler/build/plugins
SHAREDIR = /home/user/pgmodeler/build
CONFDIR = /home/user/pgmodeler/build/conf
DOCDIR = /home/user/pgmodeler/build
LANGDIR = /home/user/pgmodeler/build/lang
SAMPLESDIR = /home/user/pgmodeler/build/samples
SCHEMASDIR = /home/user/pgmodeler/build/schemas

* To change a variable value run qmake again setting the desired value e.g.:
> qmake PREFIX+=/usr/local -r pgmodeler.pro

* Proceed with build process by running:
> make && make install