Connecting to a database

You connect to a database by creating a connection object in a project. Each connection has a number of parameters. The example here is for Postgres, but other databases are similar.

Connection name: can be any name you want


Active: if checked, then this connection will be active any time Gallium Data is running, meaning that the local port will be open and listening for requests. If you uncheck this, then the connection is "commented out" -- it's as if it didn't exist, but you can still keep it around for later.


Type: the type of database for this connection. This is selected when you create the connection and cannot be changed afterwards.


Server host: the name or address of the database server. This can be a partial name (like dbserver), a full name (like dbserver.it.acme.com), an IP4 address (like 181.77.230.42) or an IP6 address if your network supports IP6 (e.g. 266a:1790:2920:69e0:35c:d8ac:da8e:15e0).


Server port: this is the port on the database server. For Postgres, it's usually 5432 but it can also be something else. For MongoDB, it's usually 27017.


Local port: the port number in the Gallium Server that will be listening to requests from database clients.


Use SSL to server: whether to use SSL when connecting to the database server. There are three options:

  • never: disables SSL completely when talking to the server

  • always: always use SSL when talking to the server

  • on request: use SSL if the client uses SSL

Note that, if you want to use SSL (i.e. either always or on request), the database server's certificate must be trusted by Gallium Data, meaning that either the database server uses a certificate that is signed by a well-known certificate authority, or the certificate is installed in the Gallium Data project's trust (under Project > Properties).


Use SSL to client: similarly, three values are possible:

  • never: disable SSL from clients, SSL connection attempts will be rejected

  • always: always require SSL for client connections, non-SSL connections will be rejected

  • on request: accept SSL connections from clients, as well as non-SSL requests

If you use always or on request, you must install a private key, as well as any certificates going with it, in the project's key area (under Project > Properties).


Timeout to server: this specifies the number of milliseconds to wait when establishing a connection to the database server. The default value (10 seconds) is usually adequate for most cases.


Test: once the required parameters are filled, and published to the server, you can press the Test button to verify that Gallium Data can talk to the specified database server. This will attempt to open a connection to the database server, thereby establishing basic network connectivity. In addition, if the Use SSL to server option is either Always or On request, Gallium Data will also attempt to establish an SSL connection to verify that certificates are properly installed. Note that no login is performed, since Gallium Data does not have any database credentials.


As soon as you Publish to the server, the connection will become active (or inactive if you unclicked Active). If you make any changes to the parameters, these changes will become effective as soon as you publish.


About host names and addresses

If you are running Gallium Data as a Docker container, keep in mind that IP addresses and host names need to be from the perspective of the Docker container. If, for instance, you are running a Postgres database on your local machine, and you usually connect to it using host name localhost or 127.0.0.1 (or maybe ::1 if you use IP6), the same name or address will not work from the Docker container (since localhost would refer to the Docker virtual machine, not the host machine).

The host name of your machine, as seen from a Docker container running on the same machine, is usually host.docker.internal on Windows and Mac. For Linux and other operating systems, you may need to dig a little deeper.

If you are running both Gallium Data and the database server(s) in Docker, you can make connectivity easy by running them in the same Docker network, but there are many other ways to accomplish the same goal.