MySQL connector
The MySQL connector supports all version of MySQL from 5.5, as well as all protocol-compatible databases such as MariaDB.
It fully supports SSL/TLS connections from database clients and to database servers if valid certificates and a private key are provided in the project.
Parameters
The MySQL connector accepts the following parameters:
Connection name
Can be any name you wish. Cannot be empty.
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 (and then click Publish), then the connection is "commented out" -- it's as if it didn't exist, but you can still keep it around for later.
Server host
Required. 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 (like 266a:1790:2920:69e0::15e0).Â
If you are running Gallium Data as a Docker container, and the database is on the same machine, you can use host.docker.internal (on Windows or Mac, but see here for Linux).
Server port
Required. The port on the database server. For MySQL, it's usually 3306 but it can also be something else.
Local address
The address on which to listen for requests. This is typically only relevant if your server has more than one address. By default, Gallium Data will listen on all addresses (which is equivalent to 0.0.0.0).
Local port
Required. The port number in the Gallium Server that will be listening to requests from database clients. Keep in mind that this is the port in the Docker container.
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). You can also use the Trust server certificate option (see below).
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 Crypto area (under Project > Properties).
Timeout to server
If specified, the number of milliseconds to wait when trying to establish a connection to the database server, before giving up and returning an error. If this is set to 0, the connection will never timeout. If this is unspecified, the default is 30000 (30 seconds).
Trust server certificate
If this is checked, any SSL connection to the database server will not check whether the server's SSL certificate is trusted -- it will just accept whatever certificate the server presents. This can be useful when dealing with self-signed certificates, but obviously this can also create a security vulnerability.
Result set batch size (rows)
If set, result sets will be processed in batches of rows, and regular result set filters will not be invoked -- only result set batch filters (if any). This number indicates the largest number of rows in batches. The actual batches may contain fewer rows if the end of the result set has been reached, or if the Result set batch size (bytes) parameter is also specified.
Typical values are between 10 and 1000. Very large values may require more heap allocated to the JVM.
Result set batch size (bytes)
If set, result sets will be processed in batches, and regular result set filters will not be invoked -- only result set batch filters (if any). This number indicates approximately the largest amount of memory that a batch should grow to before it is submitted to the response filters. The actual batches may contain fewer rows if the end of the result set has been reached, or if the Result set batch size (rows) parameter is also specified.
Typical values are between 1000 and 1000000. Very large values may require more heap allocated to the JVM.
Maximum concurrent connections (v. 1.8.1 and above)
If set, the maximum number of client connections that are open at the same time. By default, this number is 1000. Each connection takes some memory, so this number should not be higher than required. Typical values are between 500 and 20000. The minimum value is 100, the maximum value is 100000. Any value outside of that range will revert to the default of 1000.
Actions
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.
Delete this connection
Will delete the connection after confirmation. This is not undoable, unless you recover from a backup.
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 MySQL 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 if you're running in a managed environment like Kubernetes or OpenShift.
Filter types
This connector supports a number of request filters, response filters and duplex filters.
All filters can expect the object context.myutils to be defined.