The C# Connection Class

Connection provides the main interface for thread-bound work with an opened Database object. Each thread working with the database should use its own connection.

For an overview see page C# Classes

Class Definition


    public class Connection : IDisposable
    {
        /* Constructors */
        public Connection(Database db)
        public Connection(Connection con)
        public Connection(Database db, byte[] context)

        /* Methods */
        public void StartTransaction(Database.TransactionType type)
        public virtual void StartTransaction(Database.TransactionType type, Database.TransactionPriority pri, Database.IsolationLevel level)
        public virtual bool CommitTransaction()
        public bool CommitTransaction(int phase)
        public virtual bool CheckpointTransaction()
        public void SetCommitPolicy(Database.CommitPolicy policy)
        public void DiskFlush()
        public virtual void RollbackTransaction()
        public long Insert(Object obj)
        public T Create<T>() where T : class
        public T Create<T>(out long autoid) where T : class
        public long Count(Type cls)
        public void RemoveAll(Type cls)
        public virtual void Disconnect()
        public virtual void Dispose()
        public bool SaveSnapshot(String databaseSnapshotFilePath)
        public void SaveMetadata(String metadataFile, bool saveDefaults)
        public void SaveDictionary(String dictionaryFile)
        public bool SaveClass(String filePath, Type cls)
        public bool LoadClass(String filePath, Type cls, bool doMerge)
        public bool LoadClass(String filePath)
        public void SetCipherKeySnapshotTL(String cipherKey)
        public void IgnoreTtl(bool ignore)
        public bool IsTtlIgnored()
        public ClassStat GetClassStat(int ClassCode)
        public IndexStat GetIndexStat(Int16 index)
        public DiskInfo GetDiskInfo()
        public void WaitEvent(string name)
        public void StartEventListeners(string[] eventNames)
        public void ReleaseEvent(string name)
        public void ReleaseAllEvents()
        public virtual void CreateBackup(String fileName, String label, Database.BackupType type)
        public virtual void CreateBackup(String fileName, String label, Database.BackupType type, int compressionLevel, String cipher)
        public virtual void RestoreBackup(String fileName, String label)
        public void RestoreBackup(String fileName, String label, String cipher)
        public virtual Database.BackupInfo[] ListBackup(String fileName)
        public Table<T> GetTable<T>() where T : class
        public IEnumerable<T> Select<T>(Expression<Func<T,bool>> predicate) where T : class

        /* XML Export/Import */
        public bool ExportXML(String filePath)
        public bool ImportXML(String filePath, int transactionSize)
        public bool ImportXML(String filePath)

        /* Properties */
        public ICursor CurrentCursor { get; }
        public Int32 FreePages { get; }
        public Int32 TotalPages { get; }
        public Int16 DbPageSize { get; }
        public Int32 DiskPageSize { get; }
        public Int16 IndexStatCount { get; }
        public int NumberOfSequentialSearches { get; }

        /* Events */
        public event AsyncEventHandler AsyncEvent
        public event AsyncEventErrorHandler AsyncEventError
    }

Public Interface

Constructors

Connection(Database db)
Creates a connection for an opened database.
Connection(Connection con)
Creates a copy of an existing connection.
Connection(Database db, byte[] context)
Creates a connection for an opened database with user-defined context.

Connection Management

Disconnect()
Closes the connection and stops active event listeners.
Dispose()
Closes the connection. Same as Disconnect(); provided for IDisposable.

Transaction Methods

StartTransaction(TransactionType type)
Starts a transaction with default priority and isolation level (nested transactions supported).
StartTransaction(TransactionType type, TransactionPriority pri, IsolationLevel level)
Starts a transaction with the specified priority and isolation level.
CommitTransaction()
Commits the transaction. Returns false on MVCC conflict.
CommitTransaction(int phase)
Performs phase 1 or 2 of a two-phase transaction commit. phase must be 1 or 2.
CheckpointTransaction()
Checkpoints the current transaction: inserts all updated objects into indexes.
SetCommitPolicy(CommitPolicy policy)
Sets the transaction commit policy for this connection.
DiskFlush()
Flushes all committed transaction changes to disk when the connection uses Database.CommitPolicy.Buffered.
RollbackTransaction()
Rolls back the transaction. All nested transactions are also cancelled.

Object Methods

Insert(Object obj)
Inserts a new object into the DB. Returns AUTOID if set, else 0.
Create<T>()
Creates a new implementation of the specified interface or abstract class.
Create<T>(out long autoid)
Creates an implementation of an interface or abstract class and returns its AUTOID.
Count(Type cls)
Returns the number of instances of the specified class in the DB.
RemoveAll(Type cls)
Deletes all instances of the specified class (inheritance not considered).

Snapshots and Export/Import

SaveSnapshot(String path)
Saves a DB snapshot to the specified file for later loading via Database.Open.
SaveMetadata(String file, bool saveDefaults)
Saves DB metadata in JSON format (compatible with the xSQL utility).
SaveDictionary(String file)
Saves the database dictionary to a file.
SaveClass(String filePath, Type cls)
Saves table (class) content to a file.
LoadClass(String filePath, Type cls, bool doMerge)
Loads table content from a file. If doMerge=false, the table is cleared before loading.
LoadClass(String filePath)
Loads table content from a file (simplified version, doMerge=false).
SetCipherKeySnapshotTL(String cipherKey)
Sets the encryption key for DB snapshots and transaction logs.

XML Export/Import Methods

ExportXML(String filePath)
Exports database content to an XML file.
ImportXML(String filePath, int transactionSize)
Imports database content from an XML file with the specified transaction size.
ImportXML(String filePath)
Imports database content from an XML file (simplified version).

TTL and Statistics

IgnoreTtl(bool ignore)
Configures TTL ignore mode.
IsTtlIgnored()
Returns the current TTL ignore mode.
GetClassStat(int ClassCode)
Returns runtime statistics for a class by class code.
GetIndexStat(Int16 index)
Returns index statistics by zero-based index number.
GetDiskInfo()
Returns DB state information: log size, DB file size, and used space.

Statistics Properties

FreePages
Returns the total number of free pages in the DB.
TotalPages
Returns the total number of allocated pages in the DB.
DbPageSize
Returns the current DB page size for this connection.
DiskPageSize
Returns the current disk page size for this connection.
IndexStatCount
Returns the number of indexes in the database. Call this property in a read-only transaction; it is often used with GetIndexStat().

Async Events

WaitEvent(string name)
Waits for an asynchronous event. This blocking call should run in a separate thread.
StartEventListeners(string[] eventNames)
Starts listener threads for the specified asynchronous events.
ReleaseEvent(string name)
Signals an asynchronous event.
ReleaseAllEvents()
Signals all asynchronous events.

Backup

CreateBackup(...)
Creates a DB backup (overloads with compression and encryption parameters).
RestoreBackup(...)
Restores the DB from a backup.
ListBackup(String fileName)
Returns a list of backup metadata in a file.

LINQ

GetTable<T>()
[LINQ] Returns the Table<T> query root associated with class T.
Select<T>(Expression<Func<T,bool>> predicate)
[LINQ] Selects records using a LINQ predicate. This is a short form over the Table<T> adapter.
NumberOfSequentialSearches
[LINQ] Returns the number of sequential searches performed by the LINQ adapter since the connection opened.

Access Properties

CurrentCursor
Returns the current active cursor. If several cursors are active, the most recently used cursor is returned.

Events

AsyncEvent
Raised when an asynchronous event is signaled.
AsyncEventError
Raised when asynchronous event processing fails.