feat: add QueryStreamAsync to ISqlDatabase + ToDataTableAsync / QueryDataTableAsync extensions

- Add QueryStreamAsync(sql, params, ct) to ISqlDatabase interface
- Implement QueryStreamAsync on SqliteConnection (yields rows via DbDataReader)
- Implement QueryStreamAsync on SqliteConnectionPool (acquire/yield/release)
- Add ToDataTableAsync() extension on IAsyncEnumerable<SqlRow> — streams rows
  into System.Data.DataTable one at a time, never holding full result in memory
- Add QueryDataTableAsync() shorthand on ISqlDatabase — single call for
  DataGridView binding without going through SqlDataTable first

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: vkuttyp

src/SqlDotnetty.Core/ISqlDatabase.cs

@@ -12,6 +12,9 @@ public interface ISqlDatabase : IAsyncDisposable
     Task<IReadOnlyList<SqlRow>> QueryAsync(string sql, IReadOnlyList<SqlParameter>? parameters = null, CancellationToken ct = default);
     Task<IReadOnlyList<T>>      QueryAsync<T>(string sql, IReadOnlyList<SqlParameter>? parameters = null, CancellationToken ct = default) where T : new();
 
+    // ── Streaming (row by row — never buffers the full result set) ────────────
+    IAsyncEnumerable<SqlRow> QueryStreamAsync(string sql, IReadOnlyList<SqlParameter>? parameters = null, CancellationToken ct = default);
+
     // ── Execute (INSERT/UPDATE/DELETE) returns rows affected ──────────────────
     Task<int> ExecuteAsync(string sql, IReadOnlyList<SqlParameter>? parameters = null, CancellationToken ct = default);
 
@@ -50,4 +53,81 @@ public static async Task<SqlValue> ScalarAsync(
         var rows = await db.QueryAsync(sql, parameters, ct).ConfigureAwait(false);
         return rows.Count > 0 && rows[0].ColumnCount > 0 ? rows[0][0] : SqlValue.Null_;
     }
+
+    /// <summary>
+    /// Streams query results directly into a <see cref="System.Data.DataTable"/> one row
+    /// at a time — equivalent to <c>DataTable.Load(IDataReader)</c> but fully async.
+    /// Rows appear in the DataTable as they arrive from the server; the full result set
+    /// is never held in memory simultaneously.
+    /// </summary>
+    /// <example>
+    /// <code>
+    /// // Bind a large table to DataGridView without buffering all rows first
+    /// var dt = await conn.QueryStreamAsync("SELECT * FROM Employees")
+    ///                    .ToDataTableAsync("Employees");
+    /// dataGridView1.DataSource = dt;
+    ///
+    /// // Or use the shorthand on ISqlDatabase directly:
+    /// dataGridView1.DataSource = await conn.QueryDataTableAsync("SELECT * FROM Employees");
+    /// </code>
+    /// </example>
+    public static async Task<System.Data.DataTable> ToDataTableAsync(
+        this IAsyncEnumerable<SqlRow> rows,
+        string tableName = "",
+        CancellationToken ct = default)
+    {
+        var dt = new System.Data.DataTable(tableName);
+        bool columnsAdded = false;
+
+        await foreach (var row in rows.WithCancellation(ct).ConfigureAwait(false))
+        {
+            // Build columns from the first row's metadata
+            if (!columnsAdded)
+            {
+                foreach (var col in row.Columns)
+                    dt.Columns.Add(col.Name, typeof(object));
+                columnsAdded = true;
+            }
+
+            var dataRow = dt.NewRow();
+            for (int i = 0; i < row.ColumnCount; i++)
+                dataRow[i] = SqlValueToClr(row[i]);
+            dt.Rows.Add(dataRow);
+        }
+
+        return dt;
+    }
+
+    /// <summary>
+    /// Convenience shorthand — streams SQL results directly into a
+    /// <see cref="System.Data.DataTable"/> ready for DataGridView binding.
+    /// </summary>
+    public static Task<System.Data.DataTable> QueryDataTableAsync(
+        this ISqlDatabase db,
+        string sql,
+        IReadOnlyList<SqlParameter>? parameters = null,
+        CancellationToken ct = default)
+        => db.QueryStreamAsync(sql, parameters, ct).ToDataTableAsync(tableName: "", ct);
+
+    public static Task<System.Data.DataTable> QueryDataTableAsync(
+        this ISqlDatabase db, string sql, params SqlParameter[] parameters)
+        => db.QueryStreamAsync(sql, parameters).ToDataTableAsync();
+
+    private static object SqlValueToClr(SqlValue v) => v switch
+    {
+        SqlValue.Null      => DBNull.Value,
+        SqlValue.Bool b    => b.Value,
+        SqlValue.Int8 b    => b.Value,
+        SqlValue.Int16 s   => s.Value,
+        SqlValue.Int32 i   => i.Value,
+        SqlValue.Int64 l   => l.Value,
+        SqlValue.Float f   => f.Value,
+        SqlValue.Double d  => d.Value,
+        SqlValue.Decimal d => d.Value,
+        SqlValue.Text t    => t.Value,
+        SqlValue.Bytes b   => b.Value,
+        SqlValue.Uuid u    => u.Value,
+        SqlValue.Date d    => d.Value,
+        _                  => DBNull.Value,
+    };
 }

src/SqlDotnetty.Sqlite/SqliteConnection.cs

@@ -105,6 +105,32 @@ public async Task<IReadOnlyList<T>> QueryAsync<T>(
         return rows.Select(r => decoder.Decode<T>(r)).ToList();
     }
 
+    public async IAsyncEnumerable<SqlRow> QueryStreamAsync(
+        string sql,
+        IReadOnlyList<SqlParameter>? parameters = null,
+        [System.Runtime.CompilerServices.EnumeratorCancellation] CancellationToken ct = default)
+    {
+        await _lock.WaitAsync(ct).ConfigureAwait(false);
+        try
+        {
+            using var cmd    = CreateCommand(sql, parameters);
+            using var reader = await cmd.ExecuteReaderAsync(ct).ConfigureAwait(false);
+
+            var sqlColumns = new List<SqlColumn>();
+            for (int i = 0; i < reader.FieldCount; i++)
+                sqlColumns.Add(new SqlColumn(reader.GetName(i), reader.GetDataTypeName(i)));
+
+            while (await reader.ReadAsync(ct).ConfigureAwait(false))
+            {
+                var values = new SqlValue[reader.FieldCount];
+                for (int i = 0; i < reader.FieldCount; i++)
+                    values[i] = ConvertValue(reader, i);
+                yield return new SqlRow(sqlColumns, values);
+            }
+        }
+        finally { _lock.Release(); }
+    }
+
     public async Task<int> ExecuteAsync(
         string sql, IReadOnlyList<SqlParameter>? parameters = null, CancellationToken ct = default)
     {

src/SqlDotnetty.Sqlite/SqliteConnectionPool.cs

@@ -117,6 +117,20 @@ public async Task<IReadOnlyList<T>> QueryAsync<T>(
         finally { await ReleaseAsync(conn).ConfigureAwait(false); }
     }
 
+    public async IAsyncEnumerable<SqlRow> QueryStreamAsync(
+        string sql,
+        IReadOnlyList<SqlParameter>? parameters = null,
+        [System.Runtime.CompilerServices.EnumeratorCancellation] CancellationToken ct = default)
+    {
+        var conn = await AcquireAsync(ct).ConfigureAwait(false);
+        try
+        {
+            await foreach (var row in conn.QueryStreamAsync(sql, parameters, ct).ConfigureAwait(false))
+                yield return row;
+        }
+        finally { await ReleaseAsync(conn).ConfigureAwait(false); }
+    }
+
     public async Task<int> ExecuteAsync(
         string sql, IReadOnlyList<SqlParameter>? parameters = null, CancellationToken ct = default)
     {