Please rate how useful you found this document: 
Average: 3 (5 votes)


Each ProcessMaker workspace uses one MySQL database to store internal information about processes, user permissions and reports. Nonetheless, ProcessMaker can also be configured to connect to external databases, allowing an organization to integrate ProcessMaker with other DBMS and business applications that utilize databases.

ProcessMaker can establish database connections to MySQL, PostgreSQL, SQL Server/Sybase and Oracle databases. By default, it is only possible to connect to MySQL databases, but other types of databases can be used if the server running ProcessMaker has the client drivers installed and the PHP modules for those databases. See the PostgreSQL, SQL Server/Sybase and Oracle documentation to enable database connections to those databases.

To connect to another type of database, it is possible to use PHP's Open Database Connectivity (OBDC) functions in a trigger to connect to the database. See Other Types of Databases.

ProcessMaker automatically detects which database modules for PHP are installed on the server. For example, if the php-pgsql module is installed on the ProcessMaker server, ProcessMaker will offer the option to connect to PostgreSQL databases.


An Internet connection is required to access external databases and to download third-party components not supported by ProcessMaker that you may not have installed.

Creating a New Database Connection

To create a new database connection, open the project in which the connection will be used. Then go to right side of the screen and click on the + icon next to the Database Connections option in the Process Objects toolbox.

A dialog box will open where a new database connection can be defined:

  • Engine: Select the type of database software: MySQL, PostgreSQL, SQL Server or Oracle. Note that ProcessMaker will only offer databases in the dropdown list that have PHP modules installed on the server running ProcessMaker. To use a Sybase database, select SQL Server. To consult one of ProcessMaker's internal databases, select MySQL.
  • Encode: If a MySQL or PostgreSQL database is being used, then this field will appear to select the character encoding used in the external database. To consult one of ProcessMaker's internal databases, select utf8-UTF-8 Unicode.
  • Server: (Required) Enter the IP address or domain name where the database source is installed. If the database is located on the same server as ProcessMaker, then enter:
  • Database Name: (Required) Enter the name of the database to be consulted. Database names generally aren't case sensitive.
  • Username: (Required) Enter the username to log into the external database.
  • Password: Enter the password (if necessary) to log into the external database.
  • Port: (Required) Enter the port number used by the external database. By default, it is set to 3306 for MySQL, 5432 for PostgreSQL, 1521 for Oracle, and 1433 for SQL Server.
  • Description: Enter a brief description of the database connection.

After filling out the information about the external database connection, click on Cancel to close the window without saving the configuration, or click on Test Connection to check if the configuration is correct.

If ProcessMaker succesfully connects to the external database, all testing criteria will be checked. The test results will be displayed in a new window, as seen in the image below.

Click on Back to return to the previous window. To save the database connection, click on Save and it will be added to the list of existing database connections. A flash message will appear at the top of the window indicating that the connection was saved successfully.

If the connection was unsuccessful, the failed criteria will be marked with an X.

Managing Database Connections

To manage the database connections inside a process, click on the Database Connections option inside the Process Objects toolbox.

A dialog box will open with a list of the existing database connections and their details:

  1. Show ID: Click on this button to display the unique ID of the database connection, which is a 32-digit hexadecimal number used by ProcessMaker to identify the connection. This number is needed to use the executeQuery() function in a trigger.

  2. Type: Shows the database engine used by the connection.
  3. Server: Shows the IP address or domain name of the server where the external database is located.
  4. Database name: Shows the name of the external database.
  5. Description: Displays a description of the connection next to the database name.
  6. Edit: Click to edit the database connection.
  7. Delete: Click to delete the connection. A window will appear to confirm the deletion. Click Yes to close the window and return to the list of databases. Click No to delete the connection, and a flash message confirming the deletion will be shown at the top of the window.

  8. Pagination control: Use this control to navigate through the pages of connections, which show 10 connections per page.
  9. Search field: Enter text into this field to search for a particular database connection.
  10. Create: Click this button to create a new database connection.