ADC

DataStream reference

February 7, 2024

Contributed by:

C S S

This reference describes the MySQL and TDS protocols, the database versions, the authentication methods, and the character sets supported by the DataStream feature. It also describes how the Citrix ADC handles transaction requests and special queries that modify the state of a connection.

You can also configure the Citrix ADC appliance to generate audit log messages for the DataStream feature.

Supported database versions, protocols, and authentication methods

	MySQL Database	MS SQL Database
Database Versions	MySQL database versions 4.1, 5.0, 5.1, 5.4, 5.5, 5.6	MS SQL database versions 70, 2000, 2000SP1, 2005, 2008, 2008R2, 2012, 2014 (Kerberos Authentication support). You can configure the backend MS SQL server with TDS 7.4 on 2016, 2017, 2019, and 2022 by configuring NetScaler parameter `-mssqlServerVersion 2014`. Always On availability group is supported only in MS SQL versions 2012 and 2014.
Protocols	MySQL protocol version 10. For information about the MySQL protocol, see MySQL Client/Server Protocol	Tabular Data Stream (TDS) protocol version 7.1 to 7.4. For information about the TDS protocol, see Tabular Data Stream Protocol
Authentication Methods	MySQL native authentication is supported.	SQL server authentication and Windows Authentication (Kerberos/NTLM) are supported.

Character sets

The DataStream feature supports only the UTF-8 charset.

The character set used by the client while sending a request might be different from the character set used in the database server responses. Although the charset parameter is set during the connection establishment, it can be changed at any time by sending an SQL query. The character set is associated with a connection, and therefore, requests on connections with one character set cannot be multiplexed onto a connection with a different character set.

The Citrix ADC appliance parses the queries sent by the client and the responses sent by the database server.

The character set associated with a connection can be changed after the initial handshake by using the following two queries:

SET NAMES <charset> COLLATION <collation>

SET CHARACTER SET <charset>
<!--NeedCopy-->

Transactions

In MySQL, transactions are identified by using the connection parameter AUTOCOMMIT or the BEGIN:COMMIT queries. The AUTOCOMMIT parameter can be set during the initial handshake, or after the connection is established by using the query SET AUTOCOMMIT.

The Citrix ADC appliance explicitly parses each query to determine the beginning and end of a transaction.

In the MySQL protocol, the response contains two flags to indicate whether the connection is a transaction: the TRANSACTION and AUTOCOMMIT flags.

If the connection is a transaction, the TRANSACTION flag is set. Or, if the AutoCommit mode is OFF, the AUTOCOMMIT flag is not set. The ADC appliance parses the response, and if either the TRANSACTION flag is set or the AUTOCOMMIT flag is not set, it does not do connection multiplexing. When these conditions are no longer true, the ADC appliance begins connection multiplexing.

Note

Transactions are also supported for MS SQL.

Special queries

There are special queries, such as SET and PREPARE, that modify the state of the connection and might break request switching, and therefore, these queries need to be handled differently.

On receiving a request with special queries, the Citrix ADC appliance sends an OK response to the client and also, stores the request in the connection.

When a non-special query, such as INSERT and SELECT, is received along with a stored query, the ADC appliance looks for the server-side connection on which the stored query has already been sent to the database server. If no such connections exist, the ADC appliance creates a connection, and sends the stored query first, and then, sends the request with the non-special query.

In SET, USE db, and INIT_DB special queries, the appliance modifies a field in the server side connection corresponding to the special query. This modification results in better reuse of the server side connection.

Only 16 queries are stored in each connection.

The following is a list of the special queries for which the ADC appliance has a modified behavior.

SET query

The SET SQL queries define variables that are associated with the connection. These queries are also used to define global variables, but as of now, the ADC appliance is unable to differentiate between local and global variables. For this query, the ADC appliance uses the ‘store and forward’ mechanism.
USE <db> query

Using this query, the user can change the database associated with a connection. In this case, the ADC appliance parses the <db> value sent and modifies a field in the server side connection to reflect the new database to be used.
INIT_DB command

Using this query, the user can change the database associated with a connection. In this case, the ADC appliance parses the <init_db> value sent and modifies a field in the server side connection to reflect the new database to be used.
COM_PREPARE

The ADC appliance stops request switching on receiving this command.
PREPARE query

This query is used to create prepared statements that are associated with a connection. For this query, the ADC appliance uses the ‘store and forward’ mechanism.

Audit log message support

You can now configure the Citrix ADC appliance to generate audit log messages for the DataStream feature. Audit log messages are generated when client-side and server-side connections are established, closed, or dropped. The categories of messages that you can log and view are ERROR and INFO. Error messages for client-side connections begin with “CS” and error messages for server-side connections begin with “SS.” Additional information is provided where necessary. For example, log messages for closed connections (CS_CONN_CLOSED) include only the connection ID. However, log messages for established connections (CS_CONN_ESTD) include information such as the user name, database name, and the client IP address in addition to the connection ID.

The official version of this content is in English. Some of the Cloud Software Group documentation content is machine translated for your convenience only. Cloud Software Group has no control over machine-translated content, which may contain errors, inaccuracies or unsuitable language. No warranty of any kind, either expressed or implied, is made as to the accuracy, reliability, suitability, or correctness of any translations made from the English original into any other language, or that your Cloud Software Group product or service conforms to any machine translated content, and any warranty provided under the applicable end user license agreement or terms of service, or any other agreement with Cloud Software Group, that the product or service conforms with any documentation shall not apply to the extent that such documentation has been machine translated. Cloud Software Group will not be held responsible for any damage or issues that may arise from using machine-translated content.

DataStream reference

February 7, 2024

Contributed by:

C S S

February 7, 2024

Contributed by:

C S S

DataStream reference

Supported database versions, protocols, and authentication methods

Character sets

Transactions

Special queries

Audit log message support

In this article