You can install PostgreSQL, create a local database, and connect an MDrivenServer application to it; this page is for developers running PostgreSQL as a separate database server, including on Windows.
PostgreSQL is a server-based database. It is not an embedded database: MDrivenServer connects to a running PostgreSQL server through a connection string.
Before you begin
You need:
- A running PostgreSQL installation.
- The password for the PostgreSQL user you will use to connect. The example on this page uses the default
postgresuser. - An MDrivenServer installation, or a running MDrivenServerCore instance.
- A database created for the MDriven application.
Keep the database name and credentials available when you configure MDrivenServer.
Install PostgreSQL and create a database
The following steps describe a local Windows installation using pgAdmin and the PostgreSQL command-line tools.
- Install PostgreSQL and record the password you assign during installation.
- Start pgAdmin 4. A typical installation path is
C:\Program Files\PostgreSQL\16\pgAdmin 4\runtime\pgAdmin4.exe. - In pgAdmin, register or connect to the local server using:
- Host:
localhost - Port:
5432 - User:
postgres
- Host:
- Create a database. For example, create a database named
First.
Use the exact database name consistently in the command line and in the MDrivenServer connection string. The original setup notes identify the database name as case-sensitive; do not change its capitalization between these steps.
Check the database with psql
You can test the database connection with the PostgreSQL command-line client.
- Open a command prompt.
- Run the PostgreSQL environment script. For a version 16 installation, this is typically:
C:\Program Files\PostgreSQL\16\pg_env.bat
- Change to the PostgreSQL
bindirectory and connect to the database:
cd "C:\Program Files\PostgreSQL\16\bin"
psql.exe dbname=First
If the connection succeeds, PostgreSQL is running and the database is available to the credentials used by psql. Resolve this connection before configuring MDrivenServer.
Configure MDrivenServer
Configure the database from the MDrivenServer web interface.
- Open MDrivenServer in a browser and sign in.
- Select Running > Model.
- If the application is running, click Pause App.
- Set Connection Type to
PostgreSQL. - Enter the PostgreSQL connection string in Alternate Connection String. Replace the example password and database name with your own values.
Server=localhost;Port=5432;User Id=postgres;Password=<yourpwd>;Database=First;Include Error Detail=True
- Start the application.
- Upload your model to MDrivenServer.
| Setting | Example | Purpose |
|---|---|---|
Server
|
localhost
|
The PostgreSQL host for a local installation. |
Port
|
5432
|
The PostgreSQL server port used in this example. |
User Id
|
postgres
|
The PostgreSQL login used by MDrivenServer. |
Password
|
<yourpwd>
|
The password for that PostgreSQL login. |
Database
|
First
|
The database that stores the MDriven application data. |
Verify the MDriven connection
After you upload a model, create or view data through the application and inspect it from MDrivenServer. The MDrivenServer debugging tools can show the generated SQL for an OCL expression, which lets you confirm that queries are reaching the configured database.
For example, in a test model that has a Detail class, execute an OCL expression that retrieves its instances and compare the returned objects with the data you created. In the PostgreSQL walkthrough, a pass-through SQL query returning select version() was also used to confirm the PostgreSQL server version. Use this type of check only when you need to diagnose the active database connection.
Using an existing PostgreSQL database
If you reverse an existing PostgreSQL schema into an MDriven model, do not treat the first model upload as a new, empty database. Configure the server for the reversed database before uploading the model so that the existing tables are preserved.
MDrivenServer needs administrative tables to track the mapping and differences between the model and database schema. Use MDrivenServer's Ensure admin tables and sync mapping and DB function to create and synchronize these tables for a reversed database. Do not create these tables manually unless you have a specific reason to follow the legacy procedure in HowTos:MDriven Administrative Database Tables.
For a concrete walkthrough that includes composite keys, see PostgreSQL Database Reversing With MDriven.
PostgreSQL in a production Docker deployment
This page covers a separately installed PostgreSQL server. If you downloaded an MDriven production deployment package with PostgreSQL, use the supplied Docker Compose configuration instead of recreating the database setup described above. The package initializes PostgreSQL from databases/postgres, keeps credentials in postgres.env, and persists database data in /postgres-data on the host.
Follow Documentation:Configuring Production Databases PostgreSQL MySQL MSSQL for the Docker-specific network, credential, connection-string, and backup details. When connecting a host-side client such as pgAdmin to a Docker database, use 127.0.0.1 or the server's public IP and the externally exposed port, not the Docker-internal database name.
Troubleshooting
| Symptom | Check |
|---|---|
psql cannot connect
|
Confirm that PostgreSQL is running, that the host is localhost, the port is 5432, and the database name and credentials are correct.
|
| MDrivenServer cannot connect | Pause the app, verify that Connection Type is PostgreSQL, and compare every connection-string value with the successful PostgreSQL connection.
|
| An existing schema is changed or upload does not behave as expected | Confirm that the server is configured for a reversed database and use Ensure admin tables and sync mapping and DB. See HowTos:MDriven Administrative Database Tables. |
| pgAdmin cannot reach a Docker-hosted database | Connect to the host address and external port defined by the Compose configuration; do not use the internal Docker service name from a host-side tool. |