The C# SqlRemoteConnection Class

SqlRemoteConnection implements ISqlConnection and provides remote SQL access to an xSQL server or a distributed SQL deployment.

For an overview see page SQL Classes

Class Definition

    public class SqlRemoteConnection : ISqlConnection, IDisposable {
        public enum ReplicationType { SQLReplication, HAReplication }

        public class OpenParameters {
            public String host;
            public int port;
            public String[] nodes;
            public int nReplicas;
            public ReplicationType replType;
            public int maxAttempts;
            public int txBufSize;
            public int connectTimeout;
            public int readTimeout;
            public bool localDomain;
            public int compressionLevel;
            public Database.SSLParameters sslParameters;
            public String user;
            public String password;
            public OpenParameters();
        }

        public SqlRemoteConnection(Database db, string host, int port, int maxAttempts);
        public SqlRemoteConnection(Database db, string host, int port, int maxAttempts, int txBufSize);
        public SqlRemoteConnection(Database db, string[] nodes);
        public SqlRemoteConnection(Database db, string[] nodes, int nReplicas, ReplicationType replType, int maxAttempts, int txBufSize);
        public SqlRemoteConnection(Database db, OpenParameters parameters);

        public IDatabaseWrapper Wrapper { get; }

        public SqlResultSet ExecuteQuery(String query, params Object[] args);
        public int ExecuteStatement(String stmt, params Object[] args);
        public void Disconnect();
        public void Dispose();
        public void DetachResultSet(SqlResultSet res);
    }

Member Descriptions

ReplicationType enum
Defines distributed remote connection modes: SQLReplication for standard distributed SQL access and HAReplication for HA-aware distributed access.
OpenParameters class
Configuration container for remote connection parameters such as host, port, cluster node list, retry policy, buffer sizes, timeouts, transport options, SSL settings, and authentication data.
OpenParameters.host / port / nodes
Use host and port for a single remote SQL server, or nodes for a distributed connection where each element has the form HOST:PORT.
OpenParameters defaults
Defaults are suitable for a basic remote connection: nReplicas = 1, replType = SQLReplication, maxAttempts = 10, txBufSize = 64*1024, connectTimeout = 2000, readTimeout = 1200*1000, compressionLevel = 0, and localDomain = false.
OpenParameters.localDomain / sslParameters / user / password
localDomain requests local-domain transport where supported by the runtime. sslParameters, user, and password configure secure and authenticated remote access.
SqlRemoteConnection(Database, OpenParameters)
Creates a remote connection using an OpenParameters object. This overload supports both single-node and distributed configurations. At least one of host or nodes must be specified; otherwise the constructor throws DatabaseError.
SqlRemoteConnection(Database, host, port, maxAttempts)
Creates a remote connection to a single SQL server using the default transmit buffer size, default timeout values, no compression, no SSL, and no authentication credentials.
SqlRemoteConnection(Database, host, port, maxAttempts, txBufSize)
Creates a remote connection to a single SQL server and explicitly sets the size of the internal transmit buffer used for query and statement serialization.
SqlRemoteConnection(Database, nodes)
Creates a distributed remote connection to the specified node list using the default distributed settings: one replica, SQLReplication, ten connection attempts, and a 64 KB transmit buffer.
SqlRemoteConnection(Database, nodes, nReplicas, replType, maxAttempts, txBufSize)
Creates a distributed remote connection to multiple nodes. Each node string must have the form HOST:PORT. This overload is used when the application needs to control redundancy level, replication mode, retry count, and transmit buffer size.
Wrapper
Provides access to the internal IDatabaseWrapper used for low-level remote SQL operations.
ExecuteQuery(String, params Object[])
Executes a parameterized SQL SELECT query on the remote SQL server. If a previous result set is still attached, it is disposed before the new query is executed, so each remote connection keeps at most one attached result set. Throws SqlException if the connection has already been closed.
ExecuteStatement(String, params Object[])
Executes a parameterized SQL DML statement on the remote SQL server and returns the number of affected rows. Throws SqlException if the connection has already been closed.
Disconnect()
Closes the remote SQL engine and disposes the currently attached result set, if any. Calling Disconnect() on an already closed connection has no effect.
Dispose()
Releases resources by calling Disconnect().
DetachResultSet(SqlResultSet)
Internal method called by SqlResultSet to clear the currently attached result from the remote connection.
Thread Safety
Each thread should use its own remote SQL connection. A remote connection represents a single client-side SQL session and should not be shared for concurrent command execution without external synchronization.
Result Set Lifetime
A remote connection keeps only one attached SqlResultSet. Executing another query or disconnecting the connection automatically disposes the previous result set.
Parameter Binding
SQL parameters are supplied through params Object[] and bound to ? placeholders by position.
String Encoding
Strings are encoded using the database object's defaultStringEncoding and converted to the wire format expected by the remote SQL engine.
Authentication and SSL
When secure remote SQL access is required, populate OpenParameters.SSLParameters and credentials before creating the connection. Applications typically initialize SSL support on the owning Database object before opening SSL-protected remote connections.