Add provider metadata discovery

.github/workflows/test-powershell.yml

@@ -146,6 +146,7 @@ jobs:
               shell: pwsh
               env:
                   RefreshPSD1Only: 'false'
+                  SignModule: 'false'
               run: ./Module/Build/Build-Module.ps1
 
             - name: Run packaged ALC smoke test

DbaClientX.Core/DatabaseClientBase.cs

@@ -612,6 +612,62 @@ protected static bool TryGetDictionaryValue<TValue>(IDictionary<string, TValue>?
         });
     }
 
+    /// <summary>
+    /// Executes a query and maps each row with a caller-provided mapper.
+    /// </summary>
+    /// <typeparam name="T">The row result type produced by <paramref name="map"/>.</typeparam>
+    /// <param name="connection">The open database connection.</param>
+    /// <param name="transaction">The transaction to enlist in, if any.</param>
+    /// <param name="query">The query to execute.</param>
+    /// <param name="map">A mapper that converts the current data record into a result value.</param>
+    /// <param name="initialize">Optional callback invoked once after the reader opens and before the first row is read.</param>
+    /// <param name="parameters">Optional parameter values.</param>
+    /// <param name="parameterTypes">Optional parameter types.</param>
+    /// <param name="parameterDirections">Optional parameter directions.</param>
+    /// <returns>The mapped result rows.</returns>
+    protected virtual IReadOnlyList<T> ExecuteMappedQuery<T>(
+        DbConnection connection,
+        DbTransaction? transaction,
+        string query,
+        Func<IDataRecord, T> map,
+        Action<IDataRecord>? initialize = null,
+        IDictionary<string, object?>? parameters = null,
+        IDictionary<string, DbType>? parameterTypes = null,
+        IDictionary<string, ParameterDirection>? parameterDirections = null)
+    {
+        ValidateCommandText(query);
+        if (map == null)
+        {
+            throw new ArgumentNullException(nameof(map));
+        }
+
+        return ExecuteWithRetry<IReadOnlyList<T>>(() =>
+        {
+            using var command = connection.CreateCommand();
+            command.CommandText = query;
+            command.Transaction = transaction;
+            AddParameters(command, parameters, parameterTypes, parameterDirections);
+            var commandTimeout = CommandTimeout;
+            if (commandTimeout > 0)
+            {
+                command.CommandTimeout = commandTimeout;
+            }
+
+            var rows = new List<T>();
+            using (var reader = command.ExecuteReader(CommandBehavior.Default))
+            {
+                initialize?.Invoke(reader);
+                while (reader.Read())
+                {
+                    rows.Add(map(reader));
+                }
+            }
+
+            UpdateOutputParameters(command, parameters);
+            return rows;
+        });
+    }
+
     /// <summary>
     /// Executes a non-query command (INSERT/UPDATE/DELETE) with retry support.
     /// </summary>

DbaClientX.Core/Metadata/DbaColumnInfo.cs

@@ -0,0 +1,37 @@
+namespace DBAClientX.Metadata;
+
+/// <summary>
+/// Describes a column on a provider-neutral table or view result.
+/// </summary>
+public sealed record DbaColumnInfo(string Schema, string Table, string Name, string DataType)
+{
+    /// <summary>One-based ordinal position in the table or view.</summary>
+    public int Ordinal { get; init; }
+
+    /// <summary>Indicates whether the provider reports the column as nullable.</summary>
+    public bool? IsNullable { get; init; }
+
+    /// <summary>Maximum character or binary length when available.</summary>
+    public long? MaxLength { get; init; }
+
+    /// <summary>Numeric precision when available.</summary>
+    public int? Precision { get; init; }
+
+    /// <summary>Numeric scale when available.</summary>
+    public int? Scale { get; init; }
+
+    /// <summary>Provider-specific default expression when available.</summary>
+    public string? DefaultExpression { get; init; }
+
+    /// <summary>Indicates whether the provider reports the column as identity or auto-incrementing.</summary>
+    public bool? IsIdentity { get; init; }
+
+    /// <summary>Provider-specific identity generation strategy, such as IDENTITY, AUTO_INCREMENT, ALWAYS, or BY DEFAULT.</summary>
+    public string? IdentityGeneration { get; init; }
+
+    /// <summary>Provider-specific generated or computed column expression when available.</summary>
+    public string? GeneratedExpression { get; init; }
+
+    /// <summary>Provider-specific generated column kind, such as COMPUTED, STORED, or VIRTUAL.</summary>
+    public string? GeneratedKind { get; init; }
+}

DbaClientX.Core/Metadata/DbaDatabaseInfo.cs

@@ -0,0 +1,16 @@
+namespace DBAClientX.Metadata;
+
+/// <summary>
+/// Describes a database or catalog visible to a provider connection.
+/// </summary>
+public sealed record DbaDatabaseInfo(string Name)
+{
+    /// <summary>Provider-specific owner, schema owner, or current user when available.</summary>
+    public string? Owner { get; init; }
+
+    /// <summary>Provider-specific collation or encoding when available.</summary>
+    public string? Collation { get; init; }
+
+    /// <summary>Indicates whether the database is provider/system-owned when the provider exposes that information.</summary>
+    public bool? IsSystem { get; init; }
+}

DbaClientX.Core/Metadata/DbaForeignKeyInfo.cs

@@ -0,0 +1,29 @@
+namespace DBAClientX.Metadata;
+
+/// <summary>
+/// Describes one column mapping in a foreign key relationship.
+/// </summary>
+public sealed record DbaForeignKeyInfo(
+    string Schema,
+    string Table,
+    string Name,
+    string Column,
+    string ReferencedSchema,
+    string ReferencedTable,
+    string ReferencedColumn)
+{
+    /// <summary>One-based ordinal position of the column inside the foreign key.</summary>
+    public int Ordinal { get; init; }
+
+    /// <summary>Provider-specific update action when available.</summary>
+    public string? UpdateRule { get; init; }
+
+    /// <summary>Provider-specific delete action when available.</summary>
+    public string? DeleteRule { get; init; }
+
+    /// <summary>Indicates whether the provider reports the constraint as enabled.</summary>
+    public bool? IsEnabled { get; init; }
+
+    /// <summary>Indicates whether the provider reports the constraint as validated or trusted.</summary>
+    public bool? IsTrusted { get; init; }
+}

DbaClientX.Core/Metadata/DbaIndexInfo.cs

@@ -0,0 +1,40 @@
+namespace DBAClientX.Metadata;
+
+/// <summary>
+/// Describes an index column. Multi-column indexes return one row per indexed column.
+/// </summary>
+public sealed record DbaIndexInfo(string Schema, string Table, string Name)
+{
+    /// <summary>Provider-specific index type or access method when available.</summary>
+    public string? IndexType { get; init; }
+
+    /// <summary>Indicates whether the index is unique.</summary>
+    public bool IsUnique { get; init; }
+
+    /// <summary>Indicates whether the index backs a primary key.</summary>
+    public bool IsPrimaryKey { get; init; }
+
+    /// <summary>Indexed column name when the provider exposes a direct column mapping.</summary>
+    public string? Column { get; init; }
+
+    /// <summary>Indexed expression text when the index key is not a direct column reference.</summary>
+    public string? Expression { get; init; }
+
+    /// <summary>One-based ordinal position of the column inside the index.</summary>
+    public int Ordinal { get; init; }
+
+    /// <summary>Indicates descending sort order when the provider exposes it.</summary>
+    public bool? IsDescending { get; init; }
+
+    /// <summary>Indicates whether the column is included but not part of the index key.</summary>
+    public bool? IsIncluded { get; init; }
+
+    /// <summary>Indicates whether the provider reports the index as visible to query optimization.</summary>
+    public bool? IsVisible { get; init; }
+
+    /// <summary>Provider-specific prefix length for partial-width index keys.</summary>
+    public int? PrefixLength { get; init; }
+
+    /// <summary>Provider-specific filter or partial-index predicate when available.</summary>
+    public string? FilterDefinition { get; init; }
+}

DbaClientX.Core/Metadata/DbaMetadataReader.cs

@@ -0,0 +1,97 @@
+using System;
+using System.Data;
+using System.Globalization;
+
+namespace DBAClientX.Metadata;
+
+/// <summary>
+/// Provides small conversion helpers for provider metadata readers.
+/// </summary>
+public static class DbaMetadataReader
+{
+    /// <summary>Reads a required string field.</summary>
+    public static string GetString(IDataRecord record, string name)
+        => Convert.ToString(GetValue(record, name), CultureInfo.InvariantCulture) ?? string.Empty;
+
+    /// <summary>Reads an optional string field.</summary>
+    public static string? GetNullableString(IDataRecord record, string name)
+    {
+        var value = GetValue(record, name);
+        return value == null || value == DBNull.Value
+            ? null
+            : Convert.ToString(value, CultureInfo.InvariantCulture);
+    }
+
+    /// <summary>Reads a required integer field.</summary>
+    public static int GetInt32(IDataRecord record, string name)
+        => Convert.ToInt32(GetValue(record, name), CultureInfo.InvariantCulture);
+
+    /// <summary>Reads an optional integer field.</summary>
+    public static int? GetNullableInt32(IDataRecord record, string name)
+    {
+        var value = GetValue(record, name);
+        return value == null || value == DBNull.Value
+            ? null
+            : Convert.ToInt32(value, CultureInfo.InvariantCulture);
+    }
+
+    /// <summary>Reads an optional long field.</summary>
+    public static long? GetNullableInt64(IDataRecord record, string name)
+    {
+        var value = GetValue(record, name);
+        return value == null || value == DBNull.Value
+            ? null
+            : Convert.ToInt64(value, CultureInfo.InvariantCulture);
+    }
+
+    /// <summary>Reads a required Boolean field.</summary>
+    public static bool GetBoolean(IDataRecord record, string name)
+        => ConvertToBoolean(GetValue(record, name)) ?? false;
+
+    /// <summary>Reads an optional Boolean field.</summary>
+    public static bool? GetNullableBoolean(IDataRecord record, string name)
+        => ConvertToBoolean(GetValue(record, name));
+
+    private static object? GetValue(IDataRecord record, string name)
+    {
+        var ordinal = record.GetOrdinal(name);
+        return record.IsDBNull(ordinal) ? null : record.GetValue(ordinal);
+    }
+
+    private static bool? ConvertToBoolean(object? value)
+    {
+        if (value == null || value == DBNull.Value)
+        {
+            return null;
+        }
+
+        if (value is bool boolean)
+        {
+            return boolean;
+        }
+
+        if (value is string text)
+        {
+            if (bool.TryParse(text, out var parsed))
+            {
+                return parsed;
+            }
+
+            if (string.Equals(text, "YES", StringComparison.OrdinalIgnoreCase) ||
+                string.Equals(text, "Y", StringComparison.OrdinalIgnoreCase) ||
+                string.Equals(text, "1", StringComparison.OrdinalIgnoreCase))
+            {
+                return true;
+            }
+
+            if (string.Equals(text, "NO", StringComparison.OrdinalIgnoreCase) ||
+                string.Equals(text, "N", StringComparison.OrdinalIgnoreCase) ||
+                string.Equals(text, "0", StringComparison.OrdinalIgnoreCase))
+            {
+                return false;
+            }
+        }
+
+        return Convert.ToInt32(value, CultureInfo.InvariantCulture) != 0;
+    }
+}

DbaClientX.Core/Metadata/DbaRoutineInfo.cs

@@ -0,0 +1,22 @@
+namespace DBAClientX.Metadata;
+
+/// <summary>
+/// Describes a provider-neutral stored routine such as a procedure or function.
+/// </summary>
+public sealed record DbaRoutineInfo(string Schema, string Name, DbaRoutineKind Kind)
+{
+    /// <summary>Provider-specific result data type when available.</summary>
+    public string? DataType { get; init; }
+
+    /// <summary>Provider-specific overload-safe routine identifier when available.</summary>
+    public string? SpecificName { get; init; }
+
+    /// <summary>Provider-specific argument signature when available.</summary>
+    public string? Signature { get; init; }
+
+    /// <summary>Routine definition text when the provider exposes it to the current principal.</summary>
+    public string? Definition { get; init; }
+
+    /// <summary>Indicates whether the provider marks the routine as system-owned.</summary>
+    public bool? IsSystem { get; init; }
+}

DbaClientX.Core/Metadata/DbaRoutineKind.cs

@@ -0,0 +1,19 @@
+namespace DBAClientX.Metadata;
+
+/// <summary>
+/// Classifies a stored routine.
+/// </summary>
+public enum DbaRoutineKind
+{
+    /// <summary>Routine type is not known or does not fit the provider-neutral categories.</summary>
+    Unknown,
+
+    /// <summary>Stored procedure routine.</summary>
+    Procedure,
+
+    /// <summary>Function routine.</summary>
+    Function,
+
+    /// <summary>Oracle package or another package-style routine container.</summary>
+    Package
+}

DbaClientX.Core/Metadata/DbaTableInfo.cs

@@ -0,0 +1,10 @@
+namespace DBAClientX.Metadata;
+
+/// <summary>
+/// Identifies a tabular database object such as a table or view.
+/// </summary>
+public sealed record DbaTableInfo(string Schema, string Name, DbaTableKind Kind)
+{
+    /// <summary>Provider-specific object owner when different from <see cref="Schema"/>.</summary>
+    public string? Owner { get; init; }
+}

DbaClientX.Core/Metadata/DbaTableKind.cs

@@ -0,0 +1,13 @@
+namespace DBAClientX.Metadata;
+
+/// <summary>
+/// Classifies provider-neutral tabular objects returned by metadata discovery.
+/// </summary>
+public enum DbaTableKind
+{
+    /// <summary>A regular table.</summary>
+    Table,
+
+    /// <summary>A view or virtual table-like object.</summary>
+    View
+}