Clarify T-SQL column naming, column ordering, and TVP size guidance (#810)

- Add datetime column naming rule: columns must end with `Date`, not `At`
- Add warning to always append new columns at the end of the column list
- Expand IN clauses section to recommend INNER JOIN over IN subquery for
  large/unbounded TVP recordsets, with updated stored procedure examples

Author: mkincaid-bw

custom-words.txt

@@ -64,6 +64,8 @@ POSIX
 precompiler
 proxied
 recompositions
+recordset
+recordsets
 Redis
 refactorings
 roadmap

docs/contributing/code-style/sql.md

@@ -149,15 +149,27 @@ WHERE
 
 #### `IN` clauses
 
-- For bulk operations, prefer table-valued parameters (TVPs) using the `IN (SELECT [Id] FROM @Ids)`
-  pattern
-- For direct value lists, use no spaces after commas: `IN (0,1,2)`
+- For bulk operations with a small, bounded number of IDs, use the TVP `IN` pattern:
 
 ```sql
 WHERE
     [Id] IN (SELECT [Id] FROM @Ids)
 ```
 
+- For bulk operations where the recordset may be large (e.g., all users in an organization), prefer
+  an `INNER JOIN` on the TVP — this gives the query optimizer full flexibility to choose an
+  efficient join strategy (hash join, merge join) rather than defaulting to nested loops, which is
+  the typical result of an `IN` subquery:
+
+```sql
+FROM
+    [dbo].[EntityNameView] E
+INNER JOIN
+    @Ids I ON E.[Id] = I.[Id]
+```
+
+- For direct value lists, use no spaces after commas: `IN (0,1,2)`
+
 #### Subqueries
 
 - Use `EXISTS` (not `IN`) for correlated subqueries -- `EXISTS` short-circuits on the first match,
@@ -323,7 +335,7 @@ BEGIN
 END
 ```
 
-**Read many by IDs** -- bulk read using a table-valued parameter:
+**Read many by IDs (small/bounded recordset)** -- bulk read using a table-valued parameter:
 
 ```sql
 CREATE PROCEDURE [dbo].[EntityName_ReadManyByIds]
@@ -341,6 +353,25 @@ BEGIN
 END
 ```
 
+**Read many by IDs (large/unbounded recordset)** -- JOIN pattern for better optimizer plan selection
+when the TVP may contain many rows:
+
+```sql
+CREATE PROCEDURE [dbo].[EntityName_ReadManyByIds]
+    @Ids AS [dbo].[GuidIdArray] READONLY
+AS
+BEGIN
+    SET NOCOUNT ON
+
+    SELECT
+        *
+    FROM
+        [dbo].[EntityNameView] E
+    INNER JOIN
+        @Ids I ON E.[Id] = I.[Id]
+END
+```
+
 **Read many with filter** -- multiple `AND` conditions with an inline status code comment:
 
 :::warning Do not use `And` between parameter names in procedure names
@@ -446,6 +477,8 @@ WHERE
 - **Data type modifiers**: No space between the type name and its size or precision modifier (e.g.,
   `NVARCHAR(50)` not `NVARCHAR (50)`, `DATETIME2(7)` not `DATETIME2 (7)`)
 - **Nullability**: Explicitly specify `NOT NULL` or `NULL`
+- **Datetime column naming**: Datetime columns must end with `Date` (e.g., `CreationDate`,
+  `RevisionDate`, `ExpirationDate`) — do not use `At` suffixes (e.g., `CreatedAt`, `UpdatedAt`)
 - **Standard Columns**: Most tables include:
   - `[Id] UNIQUEIDENTIFIER NOT NULL` - Primary key
   - `[CreationDate] DATETIME2(7) NOT NULL` - Record creation timestamp
@@ -666,8 +699,17 @@ BEGIN
         ADD [{column_name}] {DATATYPE} {NULL|NOT NULL};
 END
 GO
+
 ```
 
+:::warning Always add new columns at the end of the column list
+
+`ALTER TABLE ... ADD` always appends columns to the end of the table. Place new columns after the
+last existing column in the table definition so the schema file stays in sync with the deployed
+table structure.
+
+:::
+
 When adding a new `NOT NULL` column to an existing table, please re-evaluate the need for it to
 truly be required. Do not be afraid of using Nullable\<T\> primitives in C# and in the application
 layer, which is almost always going to be better than taking up unnecessary space in the DB per row