ToC path:

The C# SqlLocalConnection Class

SqlLocalConnection extends Connection, implements ISqlConnection, and provides in-process SQL access to an opened database through a local SQL engine.

For an overview see page SQL Classes

Class Definition

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

        public IDatabaseWrapper Wrapper { get; }

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

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

        public override void Disconnect();
        public override void Dispose();

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

Member Descriptions

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 from an existing Connection. This overload opens a SQL engine on top of the existing database connection and marks the SQL connection as a copy, so disposing it does not disconnect the original base connection.

Wrapper

Provides access to the internal IDatabaseWrapper instance used for low-level SQL engine operations.

ExecuteQuery(String, params Object[])

Executes a parameterized SQL SELECT query on the local SQL engine and returns a SqlResultSet. The returned result remains attached to this connection until it is disposed or the connection is disconnected. Throws SqlException if the connection has already been closed.

ExecuteStatement(String, params Object[])

Executes a parameterized SQL DML statement on the local SQL engine and returns the number of affected rows. If an SQL transaction is active, the statement executes in that transaction context. Throws SqlException if the connection has already been closed.

StartTransaction(...)

Starts an SQL transaction with the specified type, priority, and isolation level. The native SQL transaction is opened only for the outermost call; additional calls increase an internal nesting counter.

CommitTransaction()

Commits the current SQL transaction. For nested transactions, the underlying transaction is released only when the outermost transaction is committed. Returns false if no SQL transaction is active.

RollbackTransaction()

Rolls back the current SQL transaction, releases the native SQL transaction handle, resets the nested transaction counter, and rolls back the underlying base connection state.

Disconnect()

Closes the SQL engine and disposes all attached result sets. If this object was created directly from Database, it also disconnects the base Connection; if it was created from an existing Connection, only the SQL engine owned by this object is closed.

Dispose()

Releases resources by calling Disconnect().

Grab()

Associates the current thread with this SQL engine instance. Use it when the local SQL engine is reused from another thread or callback context before executing SQL operations.

DetachResultSet(SqlResultSet)

Internal method called by SqlResultSet when the result is disposed. It removes the disposed result from the connection's internal set of attached result sets. Application code should not call this method directly.

GetEngine()

Returns the native SQL engine handle. This is intended for advanced integration or internal helper code rather than normal application use.

Result Set Lifetime

A local SQL connection can keep multiple active SqlResultSet objects at the same time. All attached results are disposed automatically when the connection is disconnected.

Thread Safety

Each thread working with the database should use its own local SQL connection. The local SQL engine maintains thread-associated state, and Grab() is provided to rebind the engine to the current thread when needed. It does not make concurrent use of the same connection object safe.

Parameter Binding

SQL parameters are passed as params Object[] values and bound to ? placeholders by position.

String Encoding

The local SQL engine uses the database object's defaultStringEncoding when converting .NET strings to the representation expected by the SQL runtime.