Interface IAdbConnection

An Adb database connection, similar to a IDbConnection, including creating database commands, with extra information and functionality.

Note: The AdbConnection instance is not thread-safe, and must only be used in a single place (in a single worker) at any one time.

Note: Database specific drivers, e.g. SqlClient and MySqlClient, sets properties like DatabaseName from the ConnectionString, before the connection is open, and sets them again with values from the database server after the connection is open. Generic drivers like ODBC do not set these properties from the connection string, and only sets them after the connection is open.

The connection can be opened and closed multiple times as needed, and it must be disposed after use. Disposal should almost always be done by whoever created the connection, typically via DisposeOnFinished<TDisposable>(TDisposable) or UsingActionWorker<TDisposable> if used across multiple method calls, or by a using statement if created and disposed in a single method and thread, without being passed to any other workers. See Disposing Disposables for details.

Inherited Members

IDisposable.Dispose()

Namespace: actionETL.Adb

Assembly: actionETL.dll

Syntax

public interface IAdbConnection : IDisposable

Remarks

Do design database workers to take AdbConnectionString, IAdbConnectionBuilder, and AdbCommandBuilder instances as parameters, which allows them to support connections with different AdbConnectionMode. Conversely, avoid passing AdbConnection, AdbKeepOpenConnection, AdbCommand, or connection (text) strings to workers.

Properties

ConnectionString

Gets the string used to open the connection.

Note that setting the connection string is done via IAdbConnectionBuilder or AdbConnectionString.

Declaration

string ConnectionString { get; }

Property Value

Type	Description
String

ConnectionTimeout

Gets the time (in seconds) to wait while trying to establish a connection before terminating the attempt and generating an error.

The default value is 15 seconds.

Declaration

int ConnectionTimeout { get; }

Property Value

Type	Description
Int32

DatabaseName

Gets the unquoted name of the current database after a connection is opened.

Before the connection is open, depending on the driver, either gets the database name specified in the connection string (with whatever quoting it had there), or an empty string.

Declaration

string DatabaseName { get; }

Property Value

Type	Description
String

DataSourceName

Gets the name of the database server to which to connect.

Before the connection is open, depending on the driver, either gets the database server name specified in the connection string (with whatever quoting it had there), or an empty string.

Declaration

string DataSourceName { get; }

Property Value

Type	Description
String

Information

Provides and helps process the information about a data source behind a connection, such as what character to use for quoting, how to specify parameter markers etc. This is used to write provider-independent database code.

Note that when accessing this property the first time, the connection will if needed be opened before information is retrieved, and closed again if it was not open before the property was accessed, leaving it in the original state on return. After the first time, a cached instance will be returned.

Also see the TableInformation property.

Declaration

AdbDataSourceInformation Information { get; }

Property Value

Type	Description
AdbDataSourceInformation	The data source information.

Exceptions

Type	Condition
Exception	See the provider documentation for which specific exceptions Open() can throw, it typically includes DbException and InvalidOperationException.
InvalidOperationException	May throw if the connection is associated with a transaction.
NotImplementedException	Not implemented for provider.

NumberOfColumnIdentifierParts

Gets the number of column identifier parts. E.g., if column name, table name, schema name, and catalog name are all available, this property would return 4.

Declaration

int NumberOfColumnIdentifierParts { get; }

Property Value

Type	Description
Int32

NumberOfColumnRestrictions

Gets the number of column restrictions available when using GetSchema(String, String[]), see https://learn.microsoft.com/en-us/dotnet/framework/data/adonet/retrieving-database-schema-information for details.

Declaration

int NumberOfColumnRestrictions { get; }

Property Value

Type	Description
Int32

Provider

Gets the Adb provider that created this connection.

Declaration

AdbProvider Provider { get; }

Property Value

Type	Description
AdbProvider

SchemaInformationCollection

Gets the database provider meta-data schema collections, which can be used to retrieve a schema collection with GetSchema(String) or its overloads.

Note that when accessing this property the first time, the connection will if needed be opened before information is retrieved, and closed again if it was closed before the property was accessed. After the first time, a cached instance will be returned.

Declaration

IReadOnlyList<AdbSchemaInformation> SchemaInformationCollection { get; }

Property Value

Type	Description
IReadOnlyList<AdbSchemaInformation>

Exceptions

Type	Condition
Exception	See the provider documentation for which specific exceptions Open() can throw, it typically includes DbException and InvalidOperationException.
InvalidOperationException	May throw if the connection is associated with a transaction (this is provider-specific).

ServerVersion

On an open connection, gets a string that represents the version of the server to which the connection is connected to.

Declaration

string ServerVersion { get; }

Property Value

Type	Description
String

Exceptions

Type	Condition
InvalidOperationException	Connection was closed.

State

Gets a string that describes the state of the connection.

Declaration

ConnectionState State { get; }

Property Value

Type	Description
ConnectionState

TableCommand

An optional service that executes predefined database table commands (truncate, drop, delete all rows). Will be null for providers that don't support it; always check that the property is not null before using it (if you have a connection) or that HasTableCommandService is true (if checking before you have a connection).

Also see the TableInformation and Information properties.

Declaration

AdbTableCommand TableCommand { get; }

Property Value

Type	Description
AdbTableCommand

TableInformation

An optional service that manipulates table identifiers and provides information about tables, such as what tables and columns are present. Will be null for providers that don't support it; always check that the property is not null before using it (if you have a connection) or that HasTableInformationService is true (if checking before you have a connection).

Also see the TableCommand and Information properties.

Declaration

AdbTableInformation TableInformation { get; }

Property Value

Type	Description
AdbTableInformation

Transaction

The currently active AdbTransaction returned from the last BeginTransaction() call, or null if no transaction is currently active.

Declaration

AdbTransaction Transaction { get; }

Property Value

Type	Description
AdbTransaction

UnderlyingConnection

Gets the underlying .NET DbConnection.

Note: Always use the members on AdbConnection instead of this UnderlyingConnection wherever possible. In rare cases however, the underlying .NET DbConnection is needed, e.g. when accessing provider-specific functionality not covered by AdbConnection.

Declaration

DbConnection UnderlyingConnection { get; }

Property Value

Type	Description
DbConnection

Methods

BeginTransaction()

Starts a database transaction, using the default isolation level for the specific type of connection used. As long as it is active, any commands created from this connection will automatically use this transaction, which (when the command is created after the transaction is created) removes the need to explicitly set the AdbCommand.Transaction property.

You must ensure that the transaction is later either committed or rolled back by using the transaction Commit() or Rollback() methods, or by closing or disposing the connection, which will roll back the transaction.

Do consider if the default isolation level is appropriate, in terms of performance and correctness.

Declaration

AdbTransaction BeginTransaction()

Returns

Type	Description
AdbTransaction	An object representing the new transaction.

Exceptions

Type	Condition
Exception	(See the provider documentation for specific exceptions.)

BeginTransaction(IsolationLevel)

Starts a database transaction. As long as it is active, any commands created from this connection will automatically use this transaction, which (when the command is created after the transaction is created) removes the need to explicitly set the AdbCommand.Transaction property.

You must ensure that the transaction is later either committed or rolled back by using the transaction Commit() or Rollback() methods, or by closing or disposing the connection, which will roll back the transaction.

Declaration

AdbTransaction BeginTransaction(IsolationLevel isolationLevel)

Parameters

Type	Name	Description
IsolationLevel	isolationLevel	Specifies the isolation level for the transaction. Do consider what to set it to, since this can affect both performance and correctness.

Returns

Type	Description
AdbTransaction	An object representing the new transaction.

Exceptions

Type	Condition
Exception	(See the provider documentation for specific exceptions.)

Close()

Closes the connection to the database, which will also roll back any active transaction. This is the preferred method of closing any open connection.

An application can call this method multiple times, without generating any exception.

Declaration

void Close()

Exceptions

Type	Condition
DbException	The connection-level error that occurred while opening the connection.

CreateCommand()

Creates an Adb database command with CommandType set to Text, initialized with the connection.

Note that the command query must be set separately.

Declaration

AdbCommand CreateCommand()

Returns

Type	Description
AdbCommand	A database command, initialized with the connection. The command must be disposed after its use; the associated connection will not be automatically disposed at the same time.

CreateCommand(String)

Creates an Adb database command with CommandType set to Text, initialized with the connection.

Declaration

AdbCommand CreateCommand(string queryText)

Parameters

Type	Name	Description
String	queryText	The query text.

Returns

Type	Description
AdbCommand	A database command, initialized with the connection. The command must be disposed after its use; the associated connection will not be automatically disposed at the same time.

CreateCommand(String, CommandType)

Creates an Adb database command, initialized with the connection.

Declaration

AdbCommand CreateCommand(string queryText, CommandType commandType)

Parameters

Type	Name	Description
String	queryText	The query text.
CommandType	commandType	Type of the command.

Returns

Type	Description
AdbCommand	A database command, initialized with the connection. The command must be disposed after its use; the associated connection will not be automatically disposed at the same time.

GetSchema()

Returns metadata schema information for the data source of this connection. Also see Retrieving Database Schema Information.

Note that some of these schemas are already available in an easily digestible format in this class (e.g. the meta-data schema collection SchemaInformationCollection, and columns in table-like objects via one of the GetTableColumnsAsync(IAdbTableIdentifier) overloads), and in Information.

Some providers may throw an exception if the connection is associated with a transaction. Therefore avoid calling this method on a connection that has an associated transaction, or for the MySqlConnector provider, add IgnoreCommandTransaction=true to the connection string.

Declaration

DataTable GetSchema()

Returns

Type	Description
DataTable	A DataTable that contains schema information.

Exceptions

Type	Condition
InvalidOperationException	May throw if the connection is associated with a transaction (this is provider-specific).

GetSchema(String)

Returns metadata schema information for the data source of this connection using the specified string for the schema name. Also see Retrieving Database Schema Information.

Note that some of these schemas are already available in an easily digestible format in this class (e.g. the meta-data schema collection SchemaInformationCollection, and columns in table-like objects via one of the GetTableColumnsAsync(IAdbTableIdentifier) overloads), and in Information.

Note that this method does not log errors. Instead the caller should normally log any returned failure status.

Some providers may throw an exception if the connection is associated with a transaction. Therefore avoid calling this method on a connection that has an associated transaction, or for the MySqlConnector provider, add IgnoreCommandTransaction=true to the connection string.

Declaration

DataTable GetSchema(string collectionName)

Parameters

Type	Name	Description
String	collectionName	Specifies the name of the schema to return. Must not be null.

Returns

Type	Description
DataTable	A DataTable that contains schema information.

Exceptions

Type	Condition
ArgumentException	collectionName is specified as null.
InvalidOperationException	May throw if the connection is associated with a transaction (this is provider-specific).

GetSchema(String, String[])

Returns metadata schema information for the data source of this connection using the specified string for the schema name and the specified string array for the restriction values. Also see Retrieving Database Schema Information.

Note that some of these schemas are already available in an easily digestible format in this class (e.g. the meta-data schema collection SchemaInformationCollection, and columns in table-like objects via one of the GetTableColumnsAsync(IAdbTableIdentifier) overloads), and in Information.

Some providers may throw an exception if the connection is associated with a transaction. Therefore avoid calling this method on a connection that has an associated transaction, or for the MySqlConnector provider, add IgnoreCommandTransaction=true to the connection string.

Note that the MySqlConnector provider does not support the this overload. Instead use the GetSchema(String) overload and filter the return values yourself.

Declaration

DataTable GetSchema(string collectionName, string[] restrictionValues)

Parameters

Type	Name	Description
String	collectionName	Specifies the name of the schema to return. Must not be null.
String[]	restrictionValues	Specifies a set of restriction values for the requested schema.

Returns

Type	Description
DataTable	A DataTable that contains schema information.

Exceptions

Type	Condition
ArgumentException	collectionName is specified as null.
InvalidOperationException	May throw if the connection is associated with a transaction (this is provider-specific).

Open()

Opens a database connection with the settings specified by the connection string.

Declaration

void Open()

Exceptions

Type	Condition
Exception	(See the provider documentation for specific exceptions.)

OpenAsync()

Opens the connection asynchronously if the provider supports it, otherwise it calls Open() and returns a completed task. Any exceptions thrown by Open() will be communicated via the returned task Exception property. Do not invoke other methods and properties of the connection object until the returned task is complete.

Declaration

Task OpenAsync()

Returns

Type	Description
Task	A task representing the asynchronous operation. The task will contain any exceptions raised (see the provider documentation for specific exceptions).

OpenAsync(CancellationToken)

Opens the connection asynchronously if the provider supports it, otherwise it calls Open() and returns a completed task (or a canceled task if cancellationToken is canceled). Any exceptions thrown by Open() will be communicated via the returned task Exception property. Do not invoke other methods and properties of the connection object until the returned task is complete.

Declaration

Task OpenAsync(CancellationToken cancellationToken)

Parameters

Type	Name	Description
CancellationToken	cancellationToken	The cancellation token.

Returns

Type	Description
Task	A task representing the asynchronous operation. The task will contain any exceptions raised (see the provider documentation for specific exceptions).

OpenCloseIfRequired(Action<IAdbConnection>)

Synchronously opens the connection only if it's closed, then runs an action that uses the open connection, and then only closes the connection if it was initially closed, leaving the connection in the same state as before the method call. The action itself should not open or close the connection.

This allows running database commands on a connection without having to check if the connection needs to be opened beforehand, and closed afterwards.

Declaration

void OpenCloseIfRequired(Action<IAdbConnection> action)

Parameters

Type	Name	Description
Action<IAdbConnection>	action	The action that uses the open connection.

Exceptions

Type	Condition
ArgumentNullException	action
Exception	See the provider documentation for which specific exceptions Open() can throw, it typically includes DbException and InvalidOperationException.

OpenCloseIfRequired<TResult>(Func<IAdbConnection, TResult>)

Synchronously opens the connection only if it's closed, then runs a function that uses the open connection, and then only closes the connection if it was initially closed, leaving the connection in the same state as before the method call. The function itself should not open or close the connection.

This allows running database commands on a connection without having to check if the connection needs to be opened beforehand, and closed afterwards.

Declaration

TResult OpenCloseIfRequired<TResult>(Func<IAdbConnection, TResult> func)

Parameters

Type	Name	Description
Func<IAdbConnection, TResult>	func	The action that uses the open connection.

Returns

Type	Description
TResult

Type Parameters

Name	Description
TResult	The type of the function result.

Exceptions

Type	Condition
ArgumentNullException	func
Exception	See the provider documentation for which specific exceptions Open() can throw, it typically includes DbException and InvalidOperationException.

OpenCloseIfRequiredAsync(Func<IAdbConnection, Task>)

Asynchronously opens the connection only if it's closed, then runs an asynchronous action that uses the open connection, and then only closes the connection if it was initially closed, leaving the connection in the same state as before the method call. The action itself should not open or close the connection.

This allows running database commands on a connection without having to check if the connection needs to be opened beforehand, and closed afterwards.

Declaration

Task OpenCloseIfRequiredAsync(Func<IAdbConnection, Task> actionAsync)

Parameters

Type	Name	Description
Func<IAdbConnection, Task>	actionAsync	The asynchronous action that uses the open connection.

Returns

Type	Description
Task

Exceptions

Type	Condition
ArgumentNullException	actionAsync
Exception	See the provider documentation for which specific exceptions Open() can throw, it typically includes DbException and InvalidOperationException.

OpenCloseIfRequiredAsync<TResult>(Func<IAdbConnection, Task<TResult>>)

Asynchronously opens the connection only if it's closed, then runs an asynchronous function that uses the open connection, and then only closes the connection if it was initially closed, leaving the connection in the same state as before the method call. The function itself should not open or close the connection.

This allows running database commands on a connection without having to check if the connection needs to be opened beforehand, and closed afterwards.

Declaration

Task<TResult> OpenCloseIfRequiredAsync<TResult>(Func<IAdbConnection, Task<TResult>> funcAsync)

Parameters

Type	Name	Description
Func<IAdbConnection, Task<TResult>>	funcAsync	The asynchronous action that uses the open connection.

Returns

Type	Description
Task<TResult>

Type Parameters

Name	Description
TResult	The type of the function result.

Exceptions

Type	Condition
ArgumentNullException	funcAsync
Exception	See the provider documentation for which specific exceptions Open() can throw, it typically includes DbException and InvalidOperationException.

Events

StateChange

Occurs when the state of the connection changes.

Declaration

event StateChangeEventHandler StateChange

Event Type

Type	Description
StateChangeEventHandler

See Also

AdbConnection

AdbKeepOpenConnection

IAdbConnectionBuilder

AdbConnectionBuilder

AdbKeepOpenConnectionBuilder

AdbCommand

DbConnection