using System.Data.Common;

namespace ScadaLink.Commons.Interfaces.Services;

/// <summary>
/// Interface for database access from scripts.
/// Implemented by ExternalSystemGateway, consumed by ScriptRuntimeContext.
/// </summary>
public interface IDatabaseGateway
{
    /// <summary>
    /// Returns an ADO.NET DbConnection (typically SqlConnection) from the named connection.
    /// Connection pooling is managed by the underlying provider.
    /// Caller is responsible for disposing.
    /// </summary>
    Task<DbConnection> GetConnectionAsync(
        string connectionName,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Submits a SQL write to the store-and-forward engine for reliable delivery.
    /// </summary>
    Task CachedWriteAsync(
        string connectionName,
        string sql,
        IReadOnlyDictionary<string, object?>? parameters = null,
        string? originInstanceName = null,
        CancellationToken cancellationToken = default);
}