Add IsUniqueKey support for columns and enhance TVP handling

Introduces IsUniqueKey property to column models, metadata, and snapshot logic to track single-column unique keys. Enhances TVP parameter binding to treat empty collections as null, improves error messaging for missing SQL parameters, and updates related queries, writers, and analyzers to propagate the new property throughout the codebase.

Author: 7schmiede

AGENTS.md

@@ -0,0 +1,3 @@
+# AGENTS
+
+See `.github/copilot-instructions.md` for repository guidance.

docs/content/2.cli/commands/5.version.md

@@ -13,7 +13,7 @@ xtraq version [options]
 Typical output during the RC cycle:
 
 ```text
-Version: 1.0.8
+Version: 1.0.9
 ```
 
 ## Options

src/Data/Models/Column.cs

@@ -28,6 +28,9 @@ internal class Column
     [SqlFieldName("is_identity")]
     public int? IsIdentityRaw { get; set; }
 
+    [SqlFieldName("is_unique_key")]
+    public bool IsUniqueKey { get; set; }
+
     [SqlFieldName("user_type_name")]
     public string? UserTypeName { get; set; }
 

src/Data/Queries/TableQueries.cs

@@ -282,6 +282,19 @@ CASE WHEN @catalogName IS NULL OR LTRIM(RTRIM(@catalogName)) = '' THEN CAST(NULL
     t.name AS system_type_name,
     IIF(t.name LIKE 'nvarchar%', c.max_length / 2, c.max_length) AS max_length,
     COLUMNPROPERTY(c.object_id, c.name, 'IsIdentity') AS is_identity,
+    CASE WHEN EXISTS (
+        SELECT 1
+        FROM {sysCatalogPrefix}.indexes AS ix
+        INNER JOIN {sysCatalogPrefix}.index_columns AS ic ON ic.object_id = ix.object_id AND ic.index_id = ix.index_id
+        WHERE ix.object_id = c.object_id
+          AND ix.is_unique = 1
+          AND ix.is_hypothetical = 0
+          AND ix.is_disabled = 0
+          AND ic.column_id = c.column_id
+          AND ic.key_ordinal > 0
+        GROUP BY ix.index_id
+        HAVING COUNT(*) = 1
+    ) THEN CAST(1 AS bit) ELSE CAST(0 AS bit) END AS is_unique_key,
     CASE WHEN c.is_computed = 1 THEN NULL ELSE t1.name END AS user_type_name,
     CASE WHEN c.is_computed = 1 THEN NULL ELSE s1.name END AS user_type_schema_name,
     t.name AS base_type_name,

src/Generators/ProceduresGenerator.cs

@@ -1700,10 +1700,10 @@ bool GroupPathIsNullable(string? path)
                             var typeNameLiteral = (ip.SqlTypeName ?? ip.Name).Replace("\"", "\\\"", StringComparison.Ordinal);
                             if (ip.IsNullable)
                             {
-                                return $"{{ var prm = cmd.Parameters[\"@{ip.Name}\"]; var source = input.{ip.PropertyName}; if (source != null) {{ var tvp = TvpHelper.BuildRecords(source) ?? Array.Empty<Microsoft.Data.SqlClient.Server.SqlDataRecord>(); prm.Value = tvp; }} else {{ prm.Value = DBNull.Value; }} if (prm is Microsoft.Data.SqlClient.SqlParameter sp) {{ sp.SqlDbType = System.Data.SqlDbType.Structured; sp.TypeName ??= \"{typeNameLiteral}\"; }} }}";
+                                return $"{{ var prm = cmd.Parameters[\"@{ip.Name}\"]; var source = input.{ip.PropertyName}; if (source != null) {{ var tvp = TvpHelper.BuildRecords(source); prm.Value = tvp; }} else {{ prm.Value = null; }} if (prm is Microsoft.Data.SqlClient.SqlParameter sp) {{ sp.SqlDbType = System.Data.SqlDbType.Structured; sp.TypeName ??= \"{typeNameLiteral}\"; }} }}";
                             }
 
-                            return $"{{ var prm = cmd.Parameters[\"@{ip.Name}\"]; var source = input.{ip.PropertyName}; var tvp = TvpHelper.BuildRecords(source) ?? Array.Empty<Microsoft.Data.SqlClient.Server.SqlDataRecord>(); prm.Value = tvp; if (prm is Microsoft.Data.SqlClient.SqlParameter sp) {{ sp.SqlDbType = System.Data.SqlDbType.Structured; sp.TypeName ??= \"{typeNameLiteral}\"; }} }}";
+                            return $"{{ var prm = cmd.Parameters[\"@{ip.Name}\"]; var source = input.{ip.PropertyName}; var tvp = TvpHelper.BuildRecords(source); prm.Value = tvp; if (prm is Microsoft.Data.SqlClient.SqlParameter sp) {{ sp.SqlDbType = System.Data.SqlDbType.Structured; sp.TypeName ??= \"{typeNameLiteral}\"; }} }}";
                         }
                         var valueExpr = ip.IsNullable ? $"(object?)input.{ip.PropertyName} ?? DBNull.Value" : $"input.{ip.PropertyName}";
                         return $"cmd.Parameters[\"@{ip.Name}\"].Value = {valueExpr};";

src/Metadata/TableMetadataCache.cs

@@ -203,7 +203,8 @@ private CacheSnapshot Load(DateTime utcNow)
                     MaxLength = resolved?.MaxLength ?? maxLen,
                     Precision = resolved?.Precision ?? precision,
                     Scale = resolved?.Scale ?? scale,
-                    IsIdentity = column.GetPropertyOrDefaultBool("IsIdentity")
+                    IsIdentity = column.GetPropertyOrDefaultBool("IsIdentity"),
+                    IsUniqueKey = column.GetPropertyOrDefaultBool("IsUniqueKey")
                 });
             }
         }

src/Metadata/TableTypeMetadataProvider.cs

@@ -68,6 +68,9 @@ public sealed class ColumnInfo
     /// <summary>
     /// Gets or sets a value indicating whether the column is an identity column.</summary>
     public bool IsIdentity { get; init; }
+    /// <summary>
+    /// Gets or sets a value indicating whether the column is uniquely keyed.</summary>
+    public bool IsUniqueKey { get; init; }
 }
 
 /// <summary>
@@ -159,7 +162,8 @@ public IReadOnlyList<TableTypeInfo> GetAll()
                                     MaxLength = resolved?.MaxLength ?? maxLen,
                                     Precision = resolved?.Precision ?? prec,
                                     Scale = resolved?.Scale ?? scale,
-                                    IsIdentity = c.GetPropertyOrDefaultBool("IsIdentity")
+                                    IsIdentity = c.GetPropertyOrDefaultBool("IsIdentity"),
+                                    IsUniqueKey = c.GetPropertyOrDefaultBool("IsUniqueKey")
                                 });
                             }
                         }
@@ -243,7 +247,8 @@ public IReadOnlyList<TableTypeInfo> GetAll()
                         MaxLength = resolved?.MaxLength ?? maxLen,
                         Precision = resolved?.Precision ?? prec,
                         Scale = resolved?.Scale ?? scale,
-                        IsIdentity = c.GetPropertyOrDefaultBool("IsIdentity")
+                        IsIdentity = c.GetPropertyOrDefaultBool("IsIdentity"),
+                        IsUniqueKey = c.GetPropertyOrDefaultBool("IsUniqueKey")
                     });
                 }
             }

src/Schema/EnhancedSchemaMetadataProvider.cs

@@ -62,6 +62,7 @@ internal sealed class ColumnMetadata
     public bool IsColumnSet { get; init; }
     public string? GeneratedAlwaysType { get; init; }
     public bool? IsIdentity { get; init; }
+    public bool? IsUniqueKey { get; init; }
 }
 
 /// <summary>
@@ -139,7 +140,8 @@ public EnhancedSchemaMetadataProvider(
             if (indexColumn != null)
             {
                 _console.Verbose($"[enhanced-schema] Resolved {schema}.{tableName}.{columnName} from snapshot index");
-                return MapIndexColumn(indexColumn, columnName);
+                var mapped = MapIndexColumn(indexColumn, columnName);
+                return await EnrichIndexColumnWithLiveAsync(mapped, schema, tableName, columnName, catalog, cancellationToken).ConfigureAwait(false);
             }
 
             var indexColumns = await _snapshotIndexProvider.GetTableColumnsMetadataAsync(schema, tableName, cancellationToken).ConfigureAwait(false);
@@ -152,7 +154,8 @@ public EnhancedSchemaMetadataProvider(
             if (fallback != null)
             {
                 _console.Verbose($"[enhanced-schema] Resolved {schema}.{tableName}.{columnName} from snapshot index (table scan)");
-                return MapIndexColumn(fallback, columnName);
+                var mapped = MapIndexColumn(fallback, columnName);
+                return await EnrichIndexColumnWithLiveAsync(mapped, schema, tableName, columnName, catalog, cancellationToken).ConfigureAwait(false);
             }
         }
         catch (Exception ex)
@@ -197,7 +200,7 @@ public async Task<IReadOnlyList<ColumnMetadata>> GetTableColumnsAsync(string sch
         var indexColumns = await LoadColumnsFromSnapshotIndexAsync(schema, tableName, catalog, cancellationToken).ConfigureAwait(false);
         if (indexColumns.Count > 0)
         {
-            return indexColumns;
+            return await EnrichIndexColumnsWithLiveAsync(indexColumns, schema, tableName, catalog, cancellationToken).ConfigureAwait(false);
         }
 
         return await LoadColumnsFromLiveFallbacksAsync(schema, tableName, catalog, cancellationToken).ConfigureAwait(false);
@@ -244,6 +247,129 @@ private async Task<IReadOnlyList<ColumnMetadata>> LoadColumnsFromSnapshotIndexAs
         return Array.Empty<ColumnMetadata>();
     }
 
+    private async Task<ColumnMetadata> EnrichIndexColumnWithLiveAsync(
+        ColumnMetadata indexColumn,
+        string schema,
+        string tableName,
+        string columnName,
+        string? catalog,
+        CancellationToken cancellationToken)
+    {
+        if (_dbContext == null)
+        {
+            return indexColumn;
+        }
+
+        var liveColumn = await ResolveFromDatabaseAsync(schema, tableName, columnName, catalog, cancellationToken).ConfigureAwait(false);
+        if (liveColumn == null)
+        {
+            return indexColumn;
+        }
+
+        return MergeIndexAndLive(indexColumn, liveColumn);
+    }
+
+    private async Task<IReadOnlyList<ColumnMetadata>> EnrichIndexColumnsWithLiveAsync(
+        IReadOnlyList<ColumnMetadata> indexColumns,
+        string schema,
+        string tableName,
+        string? catalog,
+        CancellationToken cancellationToken)
+    {
+        if (_dbContext == null)
+        {
+            return indexColumns;
+        }
+
+        var liveColumns = await GetTableColumnsFromLiveSourcesAsync(schema, tableName, catalog, cancellationToken).ConfigureAwait(false);
+        if (liveColumns.Count == 0)
+        {
+            return indexColumns;
+        }
+
+        var liveMap = new Dictionary<string, ColumnMetadata>(StringComparer.OrdinalIgnoreCase);
+        foreach (var live in liveColumns)
+        {
+            if (live != null && !string.IsNullOrWhiteSpace(live.Name))
+            {
+                liveMap[live.Name] = live;
+            }
+        }
+
+        var merged = new List<ColumnMetadata>(Math.Max(indexColumns.Count, liveMap.Count));
+        var seen = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
+
+        foreach (var indexColumn in indexColumns)
+        {
+            if (indexColumn == null || string.IsNullOrWhiteSpace(indexColumn.Name))
+            {
+                continue;
+            }
+
+            if (liveMap.TryGetValue(indexColumn.Name, out var live))
+            {
+                merged.Add(MergeIndexAndLive(indexColumn, live));
+            }
+            else
+            {
+                merged.Add(indexColumn);
+            }
+
+            seen.Add(indexColumn.Name);
+        }
+
+        foreach (var live in liveMap.Values)
+        {
+            if (live == null || string.IsNullOrWhiteSpace(live.Name) || seen.Contains(live.Name))
+            {
+                continue;
+            }
+
+            merged.Add(live);
+        }
+
+        _console.Verbose($"[enhanced-schema] Merged {indexColumns.Count} snapshot index column(s) with {liveMap.Count} live column(s) for {schema}.{tableName}");
+        return merged;
+    }
+
+    private static ColumnMetadata MergeIndexAndLive(ColumnMetadata indexColumn, ColumnMetadata liveColumn)
+    {
+        var name = !string.IsNullOrWhiteSpace(indexColumn.Name) ? indexColumn.Name : liveColumn.Name;
+        var sqlTypeName = !string.IsNullOrWhiteSpace(indexColumn.SqlTypeName) ? indexColumn.SqlTypeName : liveColumn.SqlTypeName;
+        var maxLength = indexColumn.MaxLength ?? liveColumn.MaxLength;
+        var precision = indexColumn.Precision ?? liveColumn.Precision;
+        var scale = indexColumn.Scale ?? liveColumn.Scale;
+        var userTypeSchema = indexColumn.UserTypeSchema ?? liveColumn.UserTypeSchema;
+        var userTypeName = indexColumn.UserTypeName ?? liveColumn.UserTypeName;
+
+        return new ColumnMetadata
+        {
+            Name = name ?? string.Empty,
+            Catalog = liveColumn.Catalog ?? indexColumn.Catalog,
+            SqlTypeName = sqlTypeName ?? string.Empty,
+            IsNullable = liveColumn.IsNullable,
+            MaxLength = maxLength,
+            Precision = precision,
+            Scale = scale,
+            UserTypeSchema = userTypeSchema,
+            UserTypeName = userTypeName,
+            IsFromSnapshot = false,
+            HasDefaultValue = liveColumn.HasDefaultValue,
+            DefaultDefinition = liveColumn.DefaultDefinition,
+            DefaultConstraintName = liveColumn.DefaultConstraintName,
+            IsComputed = liveColumn.IsComputed,
+            ComputedDefinition = liveColumn.ComputedDefinition,
+            IsComputedPersisted = liveColumn.IsComputedPersisted,
+            IsRowGuid = liveColumn.IsRowGuid,
+            IsSparse = liveColumn.IsSparse,
+            IsHidden = liveColumn.IsHidden,
+            IsColumnSet = liveColumn.IsColumnSet,
+            GeneratedAlwaysType = liveColumn.GeneratedAlwaysType,
+            IsIdentity = liveColumn.IsIdentity ?? indexColumn.IsIdentity,
+            IsUniqueKey = liveColumn.IsUniqueKey ?? indexColumn.IsUniqueKey
+        };
+    }
+
     private async Task<IReadOnlyList<ColumnMetadata>> LoadColumnsFromLiveFallbacksAsync(string schema, string tableName, string? catalog, CancellationToken cancellationToken)
     {
         if (_dbContext == null)
@@ -403,7 +529,8 @@ private static ColumnMetadata MapSnapshotColumn(SnapshotTableColumn column, stri
             IsHidden = column.IsHidden == true,
             IsColumnSet = column.IsColumnSet == true,
             GeneratedAlwaysType = NormalizeGeneratedAlwaysType(column.GeneratedAlwaysType),
-            IsIdentity = column.IsIdentity == true
+            IsIdentity = column.IsIdentity == true,
+            IsUniqueKey = column.IsUniqueKey == true
         };
     }
 
@@ -463,7 +590,8 @@ private static ColumnMetadata MapDatabaseColumn(Column column, string? fallbackC
             IsHidden = column.IsHidden,
             IsColumnSet = column.IsColumnSet,
             GeneratedAlwaysType = NormalizeGeneratedAlwaysType(column.GeneratedAlwaysType),
-            IsIdentity = isIdentity
+            IsIdentity = isIdentity,
+            IsUniqueKey = column.IsUniqueKey
         };
     }
 
@@ -485,7 +613,8 @@ private static ColumnMetadata MapIndexColumn(IndexColumnEntry column, string fal
             UserTypeSchema = userTypeSchema,
             UserTypeName = userTypeName,
             IsFromSnapshot = true,
-            IsIdentity = column.IsIdentity
+            IsIdentity = column.IsIdentity,
+            IsUniqueKey = column.IsUniqueKey
         };
     }
 

src/Services/SchemaSnapshotFileLayoutService.cs

@@ -393,6 +393,7 @@ void PruneFnColumns(List<SnapshotFunctionColumn> cols)
                 }
                 if (c.IsNullable == false) c.IsNullable = null;
                 if (c.IsIdentity == false) c.IsIdentity = null;
+                if (c.IsUniqueKey == false) c.IsUniqueKey = null;
                 if (c.MaxLength.HasValue && c.MaxLength.Value == 0) c.MaxLength = null;
                 if (c.Precision.HasValue && c.Precision.Value == 0) c.Precision = null;
                 if (c.Scale.HasValue && c.Scale.Value == 0) c.Scale = null;

src/Services/SchemaSnapshotService.cs

@@ -407,6 +407,7 @@ private static string ComputeTableColumnsHash(IReadOnlyList<SnapshotTableColumn>
                 FormatNumeric(column.Precision),
                 FormatNumeric(column.Scale),
                 FormatBool(column.IsIdentity),
+                FormatBool(column.IsUniqueKey),
                 FormatBool(column.HasDefaultValue),
                 NormalizeExpression(column.DefaultDefinition),
                 NormalizeDescriptor(column.DefaultConstraintName),
@@ -722,6 +723,7 @@ internal sealed class SnapshotTableColumn
     public bool? IsNullable { get; set; } // false values are pruned during persistence to match other models (writer implementation pending)
     public int? MaxLength { get; set; } // null when the length is zero or not applicable
     public bool? IsIdentity { get; set; } // persist true only
+    public bool? IsUniqueKey { get; set; } // persist true only
     public int? Precision { get; set; }
     public int? Scale { get; set; }
     public bool? HasDefaultValue { get; set; }