Connecting to MariaDB
Description
Alpha Anywhere AlphaDAO includes a MariaDB native driver built on the MariaDB C library. Alpha Anywhere does not require any additional software or separate client side configuration to connect to a MariaDB database.
Using the MariaDB Connection String Dialog
When you select MariaDB as your connection type in the connection string dialog, the dialog below will be displayed. Enter your host and server name and provide any authentication information required to connect to your database. The values you select will be generated into the connection string at the top of the dialog for you as you make changes. Before you begin, make sure you have installed and configured your MariaDB server. For more information on installing and configuring MariaDB, see https://mariadb.com/
The MariaDB connection string dialog has tab pages for general properties, TLS/SSL, SSH tunneling, and advanced properties. Each of the properties are described below.
The TLS/SSL tab is used to enable TLS (also called SSL) connections. These connections are encrypted between Alpha Anywhere and the database. The database presents a certificate to the client and the client verifies that it trusts the certificate. You will need to provide a certificate file with trusted certificates (and possibly the certificate being provided by the server). You can also require that the server certificate match a name, company and/or unit values that you provide.
The SSH tab is used to enable a connection to a database using an SSH2 tunnel.These connections are made from a local tunnel that is connected to a remote server and then finally to the actual database, typically behind a firewall. Alpha Anywhere will create and manage the tunnel for you based on the values you provide on this page.
The Advanced tab is used to set an initial command to be executed at connect time and to configure Connection Pooling for the connection.
To execute one or more commands immediately after connecting to the database, enter native MariaDB commands separated by a semi-colon.
Connection pooling is an automatically managed process designed to reduce the cost of constantly reconnecting to servers. This can save up to 50 to 100 milliseconds per open depending on the proximity and power of the database server.
When a connection is closed from Xbasic, the driver checks to see if the connection is pooled. If it is, the connection is not actually closed, but is added to a pool of like connections.
When a connection is opened from Xbasic, the driver first checks to see if the connection is pooled and a matching connection is available in the pool. If this is the case, it simply takes an already open connection out of the pool and returns it to the caller.
Considerations
A separate pool of connections is created for each driver, server, username and password, database, port and login and connection timeout combination. Other connection string differences are currently ignored as of this writing.
If the current database, or schema, or other session specific settings are altered during the connection lifetime, the connection may be in an incorrect state when returned to the pool and then reused. If you expect to change connection settings in this way, pooling will be unreliable.
When pooling connections, consideration needs to be paid to the number of application servers and the number processes running per server as this can increase the load on the database server.
If SSH tunneling is used (see separate discussion) then pooled connections will force a tunnel connection; which can reduce availability of the tunnel across connection pools.
MariaDB Connection String Properties
- Connection Property
- Description
- A5API
Setting the connection property A5API to 'MariaDB' will load the MariaDB driver when you open a connection.
- A5DBVersion
The version number of MariaDB your server is running. This will assure that your client connects using the driver best matched to your MariaDB server.
- Server
Enter the DNS name or IP address of your server.
- Port
MariaDB defaults to an IP address of 2638. It is a good practice to set the server port to a different value so that it is not as obvious that MariaDB is being served. This is not a substitute for using secure connections.
- UserName
Set this value to the user name you wish to connect to the database with.
- Password
Set this value to the password value you wish to connect to the database with.
- Database
Enter or select the name of the database you are targeting.
- A5LoginTimeout
Set this value to control the timeout for new connections in seconds. Omit this setting to use the MariaDB driver default value.
- A5ConnectionTimeOut
Set this value to control the timeout for the lifetime of a connection in seconds. Omit this setting to use the MariaDB driver default value.
- A5TraceSQL
Set this value to Y to trace SQL statements. Within Alpha Anywhere messages are written to the trace pane. For Application Servers the output is written to a file. The actual location varies by server.
- A5TraceSQLLevel
Set this value to determine how much detail will be written to the trace log. When set to "Errors", only errors will be reported. When set to "SQL" a summary of each statement and the results will be reported, including errors. When set to "Complete" all errors and SQL will be reported as well as key function calls and translated queries with argument markers as well as any caller context provided. When set to "Diagnostic", all of the previous output will be included along with the user thread name, the argument values and bind mappings. All other values are treated as if "SQL" was set.
- A5TraceSQLFormat
Set this value to indicate the output format desired. When set to "JSON", information will be written in JSON format with a trailing comma. Parsing a file in JSON format can be done by stripping the last trailing comma and wrapping the text in square brackets "[]". When set to "Text", the output is written as formatted text. This is the default format.
- A5SSL
Setting this value to Y requests that connections made to MariaDB be done using TLS (Transport Level Security). The predecessor to TLS is SSL (Secure Sockets Level) and is no longer the current protocol, but you will often see SSL in documentation and common usage.
The connection string properties for TLS connections are discussed separately in Connecting Securely with TLS and SSL.
- A5SSHTunnel
Setting this value to Y requests that a tunnel be created to connect to the target database.
The connection string properties for SSH connections are discussed separately in Connecting Securely with SSH.
- A5InitialCommand
Set this value to the semi-colon delimited list of commands you want to execute after a connection is opened.
- A5Pool
Set this value to 'Y' to enable pooling for the connection. The default value is 'N'.
- A5PoolSize
Set the maximum number of connections that will be kept in the pool for this connection string. The number of connections that remain open can affect the server as it must retain open connections even if they are in the pool. The default pool size is 5.
- A5Pooltimeout
The number of seconds a connection should remain in the pool. This setting is used to avoid keeping stale connections in the connection pool as well as keeping connections in the pool from losing connectivity with the server because the server closes the connection. The default timeout is 300 seconds (5 minutes). This value is reasonable on small/single application server environments. It may be too long for active servers.
Setting the connection timeout to a smaller value than that of A5PoolSize could result in a connection in the pool being disconnected while still in the pool. As a result, when pooling is enabled, the maximum value of connection timeout and pool timeout is used when connecting to the database.- A5TrustServerCertificate
Setting this value to Y skips verification of the host name for a TLS/SSL certificate.
Using Portable SQL with MariaDB
A MariaDB connection automatically selects MariaDB as it's syntax. The MariaDB syntax handler reads table information, and generates DDL (Data Definition Language) such as CREATE TABLE, DROP TABLE and DML (Data Manipulation Language) such as SELECT, INSERT, UPDATE, DELETE. It is also responsible for translating AlphaDAO Portable SQL functions into native implementations.
- The MariaDB syntax handler may be used with the ODBC and ADO.Net drivers as well.
Character Sets and Collations in MariaDB
The AlphaADO MariaDB driver automatically sets the values of character_set_results, character_set_client, and character_set_connection to "utf8mb4".The value of collation_connection is set to "utf8mb4_unicode_ci" for better international support.
Setting these values to "utf8mb4" is necessary because of an old issue with the MySQL implementation. MySQL's utf8 character set only supports three byte characters; which is incorrect. UTF-8 characters can often be four bytes long. Emoticons use four byte characters, and this can, as you might guess, create problems. MySQL introduced utf8mb4 as a new character set around 2010 as a workaround. You will want to check the settings of your database installation to make sure that character sets for the system and database are also set properly.