Configuring CollectionSpace to connect to a remote PostgreSQL database server

You can configure CollectionSpace to connect to - and store its data in - a remote PostgreSQL database server; that is, a database server that is running on a different host computer than the CollectionSpace server itself.

Configuring connections to a remote database server

This configuration is done entirely in CollectionSpace's Services layer, by editing a single file: the build.properties file at the top of the Services source code tree.

The relevant properties in the build.properties file are:

db.host=localhost

Change localhost, as shown above, to the IP address or hostname of your remote PostgreSQL database server.

#For postgresql, uncomment this, and comment out mysql section
db.port=5432

If (and only if) your remote PostgreSQL database server is listening on a port that's different from its default port number, change 5432, as shown above, to that port number.

# Here is an example of how to set the JDBC options for connecting to an SSL enabled
# PostgreSQL server.
#
#db.jdbc.urloptions=ssl=true&sslfactory=org.postgresql.ssl.NonValidatingFactory&foo=true
#db.jdbc.urloptions.encoded=ssl=true&sslfactory=org.postgresql.ssl.NonValidatingFactory&foo=true

If (and only if) connections to your remote PostgreSQL database server require a non-default set of JDBC options, uncomment the db.jdbc.urloptions and db.jdbc.urloptions.encoded declarations, as shown above, by removing the # signs from the beginning of their lines, and set their values to the required option or set of options.

The values of both declarations should be entirely identical ... except that any ampersand(s) appearing in the db.jdbc.urloptions value should be replaced by & in the db.jdbc.urloptions.encoded value, as shown in the examples above.

Setting up the PostgreSQL server to allow connections from your CollectionSpace server

The second part of this process is to configure the remote PostgreSQL database server to allow connections from your CollectionSpace server, over the network.

As noted in the setup documents for PostgreSQL, in PostgreSQL's host-based authentication configuration file, pg_hba.conf, there is a section for IPv4 connections that looks much like this:

# IPv4 local connections:
host    all             postgres        samehost                md5
host    all             nuxeo           samehost                md5
host    cspace          cspace          samehost                md5

To allow remote connections to this database server from your CollectionSpace server, replace each occurrence of samehost, as shown above, with the IP address of your CollectionSpace server.

If you wish to allow connections to this database server from more than one CollectionSpace server, duplicate the three lines above for each such server, and replace samehost with that CollectionSpace server's IP address.

If you wish to allow connections to this database server from any CollectionSpace server(s) on a particular network, see the PostgreSQL documentation on the pg_hba.conf file for instructions on how to specify this.

After making any of these changes, you will need to restart your PostgreSQL database server, if it is currently running. (There are a variety of ways to do so; using the pg_ctl utility is one such method.)

Setting up your host operating system to allow connections from your CollectionSpace server

Finally, if the operating system on the computer (or VM, container, etc.) that is hosting your shared, remote PostgreSQL database server uses a host-based firewall and/or other means of restricting connections, be sure to configure that software to allow incoming connections from each CollectionSpace server that will be accessing this database server. (Since the means of doing so varies widely, please refer to the appropriate instructions for your own host's operating system and firewall - or other access restricting - software.)