# The C# SqlLocalConnection and SqlRemoteConnection Classes

These classes provide methods for connecting to and interacting with a SQL Server database.

### For an overview see page C# Classes

## Class Definition

        // ISqlConnection interface
        public interface ISqlConnection {
            // Methods
            SqlResultSet ExecuteQuery(String query, params Object[] args);
            int ExecuteStatement(String stmt, params Object[] args);
            void Disconnect();
            void DetachResultSet(SqlResultSet result);

            // Properties
            IDatabaseWrapper Wrapper { get; }
        }

        // SqlLocalConnection class
        public class SqlLocalConnection : Connection, ISqlConnection {
            // Constructors
            public SqlLocalConnection(Database db);
            public SqlLocalConnection(Connection con);

            // Properties
            public IDatabaseWrapper Wrapper { get; }

            // Query Execution Methods
            public SqlResultSet ExecuteQuery(String query, params Object[] args);
            public int ExecuteStatement(String stmt, params Object[] args);

            // Transaction Methods (overrides)
            public override void StartTransaction(Database.TransactionType type, Database.TransactionPriority pri, Database.IsolationLevel level);
            public override bool CommitTransaction();
            public override void RollbackTransaction();

            // Lifecycle Methods
            public override void Disconnect();
            public override void Dispose();

            // Utility Methods
            public void Grab();
            public void DetachResultSet(SqlResultSet result);
            public IntPtr GetEngine();
        }

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

            // Nested Configuration Class
            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();
            }

            // Constructors (single-node)
            public SqlRemoteConnection(Database db, string host, int port, int maxAttempts);
            public SqlRemoteConnection(Database db, string host, int port, int maxAttempts, int txBufSize);

            // Constructors (distributed)
            public SqlRemoteConnection(Database db, string[] nodes);
            public SqlRemoteConnection(Database db, string[] nodes, int nReplicas, ReplicationType replType, int maxAttempts, int txBufSize);

            // Constructor (full parameters)
            public SqlRemoteConnection(Database db, OpenParameters parameters);

            // Properties
            public IDatabaseWrapper Wrapper { get; }

            // Query Execution Methods
            public SqlResultSet ExecuteQuery(String query, params Object[] args);
            public int ExecuteStatement(String stmt, params Object[] args);

            // Lifecycle Methods
            public void Disconnect();
            public void Dispose();

            // Internal Management
            public void DetachResultSet(SqlResultSet res);
        }

## Member Descriptions

ISqlConnection.ExecuteQuery(String, params Object[])
Executes a SQL SELECT query with parameter placeholders ('?'). Returns a cursor (`SqlResultSet`) for iterating through the selected tuples.
ISqlConnection.ExecuteStatement(String, params Object[])
Executes a SQL DML statement (INSERT, UPDATE, DELETE) with parameter placeholders. Returns the number of affected records.
ISqlConnection.Disconnect()
Closes the database connection and releases associated resources.
ISqlConnection.DetachResultSet(SqlResultSet)
Internal method called by `SqlResultSet` to detach itself from the connection. Should not be called directly by applications.
ISqlConnection.Wrapper
Gets the internal `IDatabaseWrapper` instance for low-level database operations.
SqlLocalConnection(Database)
Creates a local SQL connection for an already opened database. Initializes the SQL engine for the current thread.
SqlLocalConnection(Connection)
Creates a local SQL connection by copying an existing connection. Useful for sharing database access across contexts while maintaining thread isolation.
SqlLocalConnection.ExecuteQuery / ExecuteStatement
Executes SQL queries or statements on the local database engine. Throws `SqlException` if the connection is already closed.
SqlLocalConnection.StartTransaction(...)
Begins a new SQL transaction with specified type, priority, and isolation level. Supports nested transactions via reference counting.
SqlLocalConnection.CommitTransaction()
Commits the current transaction. For nested transactions, only commits when the outermost transaction is reached. Returns `false` if no active transaction exists.
SqlLocalConnection.RollbackTransaction()
Rolls back the current transaction and resets the nested transaction counter. Releases the native transaction handle.
SqlLocalConnection.Disconnect()
Closes the connection: disposes all attached result sets, closes the SQL engine, and calls base `Disconnect()` if this is not a copied connection.
SqlLocalConnection.Dispose()
Releases resources by calling `Disconnect()`. Implements the `IDisposable` pattern.
SqlLocalConnection.Grab()
Associates the current thread with this SQL engine instance. Required for thread-safe access to the local engine.
SqlLocalConnection.GetEngine()
Returns the native handle (`IntPtr`) to the underlying SQL engine. For advanced interop scenarios.
SqlLocalConnection.Wrapper
Provides access to the internal database wrapper for low-level operations.
ReplicationType enum
Defines replication modes for distributed connections: `SQLReplication` (standard SQL-level replication) or `HAReplication` (high-availability mode).
OpenParameters class
Configuration container for remote connection parameters: host/port, node list, replication settings, timeouts, buffer sizes, SSL, and authentication credentials.
SqlRemoteConnection(Database, OpenParameters)
Creates a remote connection using full configuration via `OpenParameters`. Supports both single-node and distributed cluster connections.
SqlRemoteConnection(Database, host, port, maxAttempts[, txBufSize])
Creates a remote connection to a single xSQL server. `maxAttempts` defines retry count (1-second intervals). Optional `txBufSize` sets the serialization buffer size.
SqlRemoteConnection(Database, nodes[, ...])
Creates a distributed connection to multiple cluster nodes. Each node string must be in "HOST:PORT" format. Supports redundancy level (`nReplicas`) and replication type.
SqlRemoteConnection.ExecuteQuery / ExecuteStatement
Executes SQL queries or statements on the remote server. Automatically disposes any previous result set before executing a new query.
SqlRemoteConnection.Disconnect()
Closes the remote connection: disposes the active result set (if any) and closes the native engine handle.
SqlRemoteConnection.Dispose()
Releases resources by calling `Disconnect()`. Implements the `IDisposable` pattern.
SqlRemoteConnection.Wrapper
Provides access to the internal database wrapper for low-level remote protocol operations.
SqlRemoteConnection.DetachResultSet(SqlResultSet)
Internal method to detach a result set from the connection, allowing independent lifecycle management.
Thread Safety Note
Each thread working with the database must use its own `ISqlConnection` instance. Local connections bind to a thread via `Grab()`; remote connections are inherently thread-isolated.
Parameter Binding
Both `ExecuteQuery` and `ExecuteStatement` support parameterized queries using '?' placeholders. Parameters are passed as `params Object[]` and are automatically bound by position.
String Encoding
All connections use the database's `defaultStringEncoding` for converting .NET strings to the wire format expected by the eXtremeDB engine.