🚀 Getting Started

Namespace Imports

MySQL

// Main QueryBuilding Namespace - Required for advanced operations
using Unleasharp.DB.Base.QueryBuilding;
// Database engine Query Builder Namespace
using Unleasharp.DB.MySQL;

SQLite

// Main QueryBuilding Namespace - Required for advanced operations
using Unleasharp.DB.Base.QueryBuilding;
// Database engine Query Builder Namespace
using Unleasharp.DB.SQLite;

PostgreSQL

// Main QueryBuilding Namespace - Required for advanced operations
using Unleasharp.DB.Base.QueryBuilding;
// Database engine Query Builder Namespace
using Unleasharp.DB.PostgreSQL;

MSSQL

// Main QueryBuilding Namespace - Required for advanced operations
using Unleasharp.DB.Base.QueryBuilding;
// Database engine Query Builder Namespace
using Unleasharp.DB.MSSQL;

DuckDB

// Main QueryBuilding Namespace - Required for advanced operations
using Unleasharp.DB.Base.QueryBuilding;
// Database engine Query Builder Namespace
using Unleasharp.DB.DuckDB;

📝 Note: The QueryBuilding namespace is only required for advanced operations. Basic functionality works without it.

Connection Setup

There are multiple ways to initialize the ConnectorManager.

Basic Setup

MySQL

ConnectorManager dbConnector = new ConnectorManager(
    "Server=localhost;Database=unleasharp;Uid=unleasharp;Pwd=unleasharp;"
);

SQLite

ConnectorManager dbConnector = new ConnectorManager(
    "Data Source=unleasharp.db;Version=3;"
);

PostgreSQL

ConnectorManager dbConnector = new ConnectorManager(
    "Host=localhost;Port=5432;Database=unleasharp;Username=unleasharp;Password=unleasharp;"
);

MSSQL

ConnectorManager dbConnector = new ConnectorManager(
    "Data Source=localhost;Database=unleasharp;User ID=unleasharp;Password=unleasharp;Integrated Security=false;Encrypt=True;TrustServerCertificate=True"
);

DuckDB

ConnectorManager dbConnector = new ConnectorManager(
    "Data Source=unleasharp.duckdb"
);

Using ConnectionStringBuilder

Each database implementation has its own ConnectionStringBuilder. You can provide an engine-specific ConnectionStringBuilder object to the ConnectorManager constructor.

MySQL

ConnectorManager dbConnector = new ConnectorManager(new MySqlConnectionStringBuilder(
    "Server=localhost;Database=unleasharp;Uid=unleasharp;Pwd=unleasharp;"
));

SQLite

ConnectorManager dbConnector = new ConnectorManager(new SQLiteConnectionStringBuilder(
    "Data Source=unleasharp.db;Version=3;"
));

PostgreSQL

ConnectorManager dbConnector = new ConnectorManager(new NpgsqlConnectionStringBuilder(
    "Host=localhost;Port=5432;Database=unleasharp;Username=unleasharp;Password=unleasharp;"
));

MSSQL

ConnectorManager dbConnector = new ConnectorManager(new SqlConnectionStringBuilder(
    "Data Source=localhost;Database=unleasharp;User ID=unleasharp;Password=unleasharp;Integrated Security=false;Encrypt=True;TrustServerCertificate=True"
));

DuckDB

// DuckDB does not allow to initialize a DuckDBConnectionStringBuilder with a Connection String

Fluent Configuration

The ConnectorManager follows the same Fluent principles as the QueryBuilder and the Query classes.

ConnectorManager dbConnector = new ConnectorManager("Data Source=unleasharp.db;Version=3;")
    // Automatic connection recycling, recommended for long-running applications (default: true)
    .WithAutomaticConnectionRenewal(true)
    
    // Set automatic connection renewal interval (default: 900 seconds)
    .WithAutomaticConnectionRenewalInterval(TimeSpan.FromHours(1))
    
    // Exception handling callback
    .WithOnQueryExceptionAction((query, ex) => {
        Console.WriteLine($"Exception executing query: {query.QueryRenderedString}");
        Console.WriteLine($"Exception message: {ex.Message}");
        // Log to your preferred logging framework
    })
    
    // Pre-execution callback
    .WithBeforeQueryExecutionAction((query) => {
        Console.WriteLine($"Preparing query for execution: {query.Render()}");
    })
    
    // Post-execution callback (even on exceptions)
    .WithAfterQueryExecutionAction((query) => {
        Console.WriteLine($"Executed query: {query.QueryRenderedString}");
    })
;

Logging

Unleasharp.DB includes built-in debug logging that helps trace query rendering, query builder operations, and connector lifecycle events. The default minimum level is ERROR to reduce noise in production.

Configure logging during startup to suit development or production needs.

Set Minimum Logging Level

using Unleasharp.DB.Base;

Logging.SetMinimumLogLevel(Microsoft.Extensions.Logging.LogLevel.Debug);

Setup Default ILoggerFactory

Logging.SetLoggingOptions(options => {
    options.SingleLine      = true;
    options.TimestampFormat = "[yyyy-MM-dd HH:mm:ss.fff] "; // Custom format
    options.UseUtcTimestamp = false;
    options.IncludeScopes   = true;
});

Setup Custom ILoggerFactory

To integrate with your application's logging stack (Microsoft.Extensions.Logging), provide a custom ILoggerFactory:

Logging.SetLoggerFactory(
    LoggerFactory.Create(loggingBuilder => loggingBuilder
        .SetMinimumLevel(Microsoft.Extensions.Logging.LogLevel.Trace)
        .AddConsole()
    )
);

📝 Note: Set trace or debug levels only in development or when diagnosing issues — verbose logging can impact performance and generate large logs.

Engine-Specific

PostgreSQL

PostgreSQL requires special configuration when performing operations with Enums. In PostgreSQL, Enums can be defined as a specific type. This requires creating the Enum type first in PostgreSQL, which can be done with Unleasharp.DB, but also requires to Map first the C# Enum to the PostgreSQL Enum before creating the database connection.

// Custom PostgreSQL constructor
ConnectorManager dbConnector = new ConnectorManager(new NpgsqlDataSourceBuilder(
        "Host=localhost;Port=5432;Database=unleasharp;Username=unleasharp;Password=unleasharp;Include Error Detail=true"
    ))
    // Built-in way to map C# Enum types to PostgreSQL Enums. It does automatically name the Enum the same way as the C# Enum, but lowercase
    .WithMappedEnum<EnumExample>()
    // Use PostgreSQL DataSourceBuilder to add the C# Enum using MapEnum<T>()
    .WithDataSourceBuilderSetup(sourceBuilder => {
        sourceBuilder.MapEnum<EnumExample>("enumexample");
    })
;

// Create the PostgreSQL Enum type based on the C# Enum type if it doesn't exist already
dbConnector.QueryBuilder().Build(query => query.CreateEnumType<EnumExample>()).Execute();

⚠️ Note: When creating the Enum type using the previous method, given Enum will not be mapped to PostgreSQL Enum in the ConnectorManager, it will require re-instantiating it or resetting the application. A future workaround should improve this behaviour.

DuckDB

DuckDB can also define Enums as specific types, but they don't require to be maped to C# Enum types.

// Create the DuckDB Enum type based on the C# Enum type if it doesn't exist already
dbConnector.QueryBuilder().Build(query => query.CreateEnumType<EnumExample>()).Execute();