🚀 Getting Started

Namespace Imports

// Main QueryBuilding Namespace - Required for advanced operations
using Unleasharp.DB.Base.QueryBuilding;

// Specific database engine implementation
using Unleasharp.DB.SQLite;         // For SQLite
// using Unleasharp.DB.MySQL;       // For MySQL  
// using Unleasharp.DB.PostgreSQL;  // For PostgreSQL
// using Unleasharp.DB.MSSQL;       // For Microsoft SQL

📝 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

// Initialize database connection
ConnectorManager dbConnector = new ConnectorManager("Data Source=unleasharp.db;Version=3;");

Using ConnectionStringBuilder

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

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

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

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}");
    })
;

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.