Update the Configuration File for PostgreSQL Region and Cross-Region Databases

Use these steps to create or update a configuration file to include entries to one or more region databases, and a cross-region databases.

You should only create or update a configuration file using the dbfhconfig command line utility.

If you are configuring a file that has previously been configured for the database instance that you are working with, you can jump to step 5, ensuring that you use the same <server-name> as previously used.

Open an command prompt.
Set the MFDBFH_CONFIG environment variable to locate the configuration file to be created or updated:
```
set MFDBFH_CONFIG=<location-and-name-of-file>
```
If you do not set this variable, a file named MFDBFH.cfg is assumed to be located in the current directory.

Note: The MFDBFH_SCRIPT_DIR environment variable is also required to point to the stored procedures used to interact with a datastore; however, this variable is implicitly set already when using an command prompt.
Add a database server instance that you intend to connect to:
```
dbfhconfig -add -server:<server-name> -provider:pg
```
where <server-name> is the name of the database server instance. An entry of localhost:<port> is also valid, which defaults to your machine name. If you have already updated the configuration file with the PostgreSQL datastores, this entry will already exist, and you will receive a message informing you of this; you can skip to the next step.

Now specify the required databases within the instance.
Firstly, you need to create a reference to the postgres database - this is the primary configuration database supplied with PostgreSQL:
Note: If the <server> element for your database server instance already exists, this reference should already exist as well, and so again, skip this step.
```
dbfhconfig -add -server:<server-name> -dsn:<name> -type:database -name:postgres [-user:<user-name>] [-connect:<connection-string>]
```
where <name> is either the name you will give an ODBC data source for the PostgreSQL postgres database (in which case, make a note of it for a later step), or a unique name within the server configuration in which to reference the database if you are using a connection string; <user-name> is a valid user for the instance; and <connection-string> is the database connection string if you are establishing a database connection without the use of an ODBC data source - see Database Connection Strings for the database-specific syntax.
Repeat the following step for each required region database:
```
dbfhconfig -add -server:<server-name> -dsn:<name> [-db:<existing-db>] [odbcdsn:<dsn-name>] -type:region -name:<region-name> -feature:<options> [-user:<user-name>] [-connect:<connection-string>]
```
where <name> is either the name you will give an ODBC data source for the region database (in which case, make a note of it for a later step), or a unique name within the server configuration in which to reference the region database if you are using a connection string; <existing-db> is the name of an existing database in which the region database is stored - if this option is omitted, it is implied that the region database is housed in its own database; <dsn-name> is the name of the data source for the shared connection (if you are using ODBC data sources and using a single physical database) - see Database Connections for more information; <region-name> is the name of the enterprise server region that this database will serve; and <options> is a list of features for which the region will use the database.
<options> can be one or more of:
- all - all available region features enabled (default).
- none - no region features enabled.
- [+|-]reslocking - enables\disables database resource locking.
Now add a reference to a single cross-region database:
```
dbfhconfig -add -server:<server-name> -dsn:<name> -type:crossregion [-db:<existing-db>] [odbcdsn:<dsn-name>] [-user:<user-name>] [-connect:<connection-string>] 
```
where <name> is either the name you will give an ODBC data source for the cross-region database (in which case, make a note of it for a later step), or a unique name within the server configuration in which to reference the cross-region database if you are using a connection string; <existing-db> is the name of an existing database in which the cross-region database is stored - if this option is omitted, it is implied that the cross-region database is housed in its own database; <dsn-name> is the name of the data source used as a shared database connection (if you are using ODBC data sources and using a single physical database) - see Database Connections for more information.

Example configuration file

The following is an example of a configuration file that contains a datastore, a region database, and a cross-region database. As the login credentials are required to establish a connection to this database, the secrets vault has also been enabled: see Configure a Secrets Vault for the Micro Focus Database File Handler for more information.

<datastores usevault="true">
   <server name="MyMainDB" type="postgresql" access="odbc">
      <dsn name="PG.POSTGRES" type="database" dbname="postgres" userid="clerk" password="$$vault$$"/>
      <dsn name="PG.VSAM" type="datastore" dsname="VSAM" dbname="MyMainDB" optio="none +ooseq" userid="clerk" password="$$vault$$"/>
      <dsn name="PG.ESDEMO" type="region.cas" region="PGDEMO" dbname="MyMainDB" feature="all" userid="clerk" password="$$vault$$"/>
      <dsn name="PG.CROSSREGION" type="crossregion.cas" dbname="MyMainDB" userid="clerk" password="$$vault$$"/>
   </server>
</datastores>

Next, if you have not used connection strings in your database configuration file, you must create the data sources for each of the databases you have configured. If you have configured connection strings, you can skip the data source creation and configure your enterprise server regions to use the region and cross-region databases.