devskill 2.0.6 → 2.0.8

package/skills/reviewing-oracle-to-postgres-migration/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: reviewing-oracle-to-postgres-migration
+description: 'Identifies Oracle-to-PostgreSQL migration risks by cross-referencing code against known behavioral differences (empty strings, refcursors, type coercion, sorting, timestamps, concurrent transactions, etc.). Use when planning a database migration, reviewing migration artifacts, or validating that integration tests cover Oracle/PostgreSQL differences.'
+---
+
+# Oracle-to-PostgreSQL Database Migration
+
+Surfaces migration risks and validates migration work against known Oracle/PostgreSQL behavioral differences documented in the `references/` folder.
+
+## When to use
+
+1. **Planning** — Before starting migration work on a procedure, trigger, query, or refcursor client. Identify which reference insights apply so risks are addressed up front.
+2. **Validating** — After migration work is done, confirm every applicable insight was addressed and integration tests cover the new PostgreSQL semantics.
+
+## Workflow
+
+Determine the task type:
+
+**Planning a migration?** Follow the risk assessment workflow.
+**Validating completed work?** Follow the validation workflow.
+
+### Risk assessment workflow (planning)
+
+```
+Risk Assessment:
+- [ ] Step 1: Identify the migration scope
+- [ ] Step 2: Screen each insight for applicability
+- [ ] Step 3: Document risks and recommended actions
+```
+
+**Step 1: Identify the migration scope**
+
+List the affected database objects (procedures, triggers, queries, views) and the application code that calls them.
+
+**Step 2: Screen each insight for applicability**
+
+Review the reference index in [references/REFERENCE.md](references/REFERENCE.md). For each entry, determine whether the migration scope contains patterns affected by that insight. Read the full reference file only when the insight is potentially relevant.
+
+**Step 3: Document risks and recommended actions**
+
+For each applicable insight, note the specific risk and the recommended fix pattern from the reference file. Flag any insight that requires a design decision (e.g., whether to preserve Oracle empty-string-as-NULL semantics or adopt PostgreSQL behavior).
+
+### Validation workflow (post-migration)
+
+```
+Validation:
+- [ ] Step 1: Map the migration artifact
+- [ ] Step 2: Cross-check applicable insights
+- [ ] Step 3: Verify integration test coverage
+- [ ] Step 4: Gate the result
+```
+
+**Step 1: Map the migration artifact**
+
+Identify the migrated object and summarize the change set.
+
+**Step 2: Cross-check applicable insights**
+
+For each reference in [references/REFERENCE.md](references/REFERENCE.md), confirm the behavior or test requirement is acknowledged and addressed in the migration work.
+
+**Step 3: Verify integration test coverage**
+
+Confirm tests exercise both the happy path and the failure scenarios highlighted in applicable insights (exceptions, sorting, refcursor consumption, concurrent transactions, timestamps, etc.).
+
+**Step 4: Gate the result**
+
+Return a checklist asserting each applicable insight was addressed, migration scripts run, and integration tests pass.

package/skills/reviewing-oracle-to-postgres-migration/SYNC.md

@@ -0,0 +1,5 @@
+# Sync Info
+
+- **Source:** `vendor/awesome-copilot/skills/reviewing-oracle-to-postgres-migration`
+- **Git SHA:** `23fb7006c132a0bba75b0e5af7a35cab11272812`
+- **Synced:** 2026-03-24

package/skills/reviewing-oracle-to-postgres-migration/references/REFERENCE.md

@@ -0,0 +1,13 @@
+# Reference Index
+
+| File | Brief description |
+| --- | --- |
+| [empty-strings-handling.md](empty-strings-handling.md) | Oracle treats '' as NULL; PostgreSQL keeps empty strings distinct—patterns to align behavior in code, tests, and migrations. |
+| [no-data-found-exceptions.md](no-data-found-exceptions.md) | Oracle SELECT INTO raises "no data found"; PostgreSQL doesn’t—add explicit NOT FOUND handling to mirror Oracle behavior. |
+| [oracle-parentheses-from-clause.md](oracle-parentheses-from-clause.md) | Oracle allows `FROM(TABLE_NAME)` syntax; PostgreSQL requires `FROM TABLE_NAME`—remove unnecessary parentheses around table names. |
+| [oracle-to-postgres-sorting.md](oracle-to-postgres-sorting.md) | How to preserve Oracle-like ordering in PostgreSQL using COLLATE "C" and DISTINCT wrapper patterns. |
+| [oracle-to-postgres-to-char-numeric.md](oracle-to-postgres-to-char-numeric.md) | Oracle allows TO_CHAR(numeric) without format; PostgreSQL requires format string—use CAST(numeric AS TEXT) instead. |
+| [oracle-to-postgres-type-coercion.md](oracle-to-postgres-type-coercion.md) | PostgreSQL strict type checks vs. Oracle implicit coercion—fix comparison errors by quoting or casting literals. |
+| [postgres-concurrent-transactions.md](postgres-concurrent-transactions.md) | PostgreSQL allows only one active command per connection—materialize results or use separate connections to avoid concurrent operation errors. |
+| [postgres-refcursor-handling.md](postgres-refcursor-handling.md) | Differences in refcursor handling; PostgreSQL requires fetching by cursor name—C# patterns to unwrap and read results. |
+| [oracle-to-postgres-timestamp-timezone.md](oracle-to-postgres-timestamp-timezone.md) | CURRENT_TIMESTAMP / NOW() return UTC-normalised timestamptz in PostgreSQL; Npgsql surfaces DateTime.Kind=Unspecified—force UTC at connection open and in application code. |

package/skills/reviewing-oracle-to-postgres-migration/references/empty-strings-handling.md

@@ -0,0 +1,69 @@
+# Oracle to PostgreSQL: Empty String Handling Differences
+
+## Problem
+
+Oracle automatically converts empty strings (`''`) to `NULL` in VARCHAR2 columns. PostgreSQL preserves empty strings as distinct from `NULL`. This difference can cause application logic errors and test failures during migration.
+
+## Behavior Comparison
+
+**Oracle:**
+- Empty string (`''`) is **always** treated as `NULL` in VARCHAR2 columns
+- `WHERE column = ''` never matches rows; use `WHERE column IS NULL`
+- Cannot distinguish between explicit empty string and `NULL`
+
+**PostgreSQL:**
+- Empty string (`''`) and `NULL` are **distinct** values
+- `WHERE column = ''` matches empty strings
+- `WHERE column IS NULL` matches `NULL` values
+
+## Code Example
+
+```sql
+-- Oracle behavior
+INSERT INTO table (varchar_column) VALUES ('');
+SELECT * FROM table WHERE varchar_column IS NULL;  -- Returns the row
+
+-- PostgreSQL behavior  
+INSERT INTO table (varchar_column) VALUES ('');
+SELECT * FROM table WHERE varchar_column IS NULL;  -- Returns nothing
+SELECT * FROM table WHERE varchar_column = '';     -- Returns the row
+```
+
+## Migration Actions
+
+### 1. Stored Procedures
+Update logic that assumes empty strings convert to `NULL`:
+
+```sql
+-- Preserve Oracle behavior (convert empty to NULL):
+column = NULLIF(param, '')
+
+-- Or accept PostgreSQL behavior (preserve empty string):
+column = param
+```
+
+### 2. Application Code
+Review code that checks for `NULL` and ensure it handles empty strings appropriately:
+
+```csharp
+// Before (Oracle-specific)
+if (value == null) { }
+
+// After (PostgreSQL-compatible)
+if (string.IsNullOrEmpty(value)) { }
+```
+
+### 3. Tests
+Update assertions to be compatible with both behaviors:
+
+```csharp
+// Migration-compatible test pattern
+var value = reader.IsDBNull(columnIndex) ? null : reader.GetString(columnIndex);
+Assert.IsTrue(string.IsNullOrEmpty(value));
+```
+
+### 4. Data Migration
+Decide whether to:
+- Convert existing `NULL` values to empty strings
+- Convert empty strings to `NULL` using `NULLIF(column, '')`
+- Leave values as-is and update application logic

package/skills/reviewing-oracle-to-postgres-migration/references/no-data-found-exceptions.md

@@ -0,0 +1,99 @@
+# PostgreSQL Exception Handling: SELECT INTO No Data Found
+
+## Overview
+
+A common issue when migrating from Oracle to PostgreSQL involves `SELECT INTO` statements that expect to raise an exception when no rows are found. This pattern difference can cause integration tests to fail and application logic to behave incorrectly if not properly handled.
+
+---
+
+## Problem Description
+
+### Scenario
+
+A stored procedure performs a lookup operation using `SELECT INTO` to retrieve a required value:
+
+```sql
+SELECT column_name
+INTO variable_name
+FROM table1, table2 
+WHERE table1.id = table2.id AND table1.id = parameter_value;
+```
+
+### Oracle Behavior
+
+When a `SELECT INTO` statement in Oracle does **not find any rows**, it automatically raises:
+
+```
+ORA-01403: no data found
+```
+
+This exception is caught by the procedure's exception handler and re-raised to the calling application.
+
+### PostgreSQL Behavior (Pre-Fix)
+
+When a `SELECT INTO` statement in PostgreSQL does **not find any rows**, it:
+
+- Sets the `FOUND` variable to `false`
+- **Silently continues** execution without raising an exception
+
+This fundamental difference can cause tests to fail silently and logic errors in production code.
+
+---
+
+## Root Cause Analysis
+
+The PostgreSQL version was missing explicit error handling for the `NOT FOUND` condition after the `SELECT INTO` statement.
+
+**Original Code (Problematic):**
+
+```plpgsql
+SELECT column_name
+INTO variable_name
+FROM table1, table2 
+WHERE table1.id = table2.id AND table1.id = parameter_value;
+
+IF variable_name = 'X' THEN
+ result_variable := 1;
+ELSE
+ result_variable := 2;
+END IF;
+```
+
+**Problem:** No check for `NOT FOUND` condition. When an invalid parameter is passed, the SELECT returns no rows, `FOUND` becomes `false`, and execution continues with an uninitialized variable.
+
+---
+
+## Key Differences: Oracle vs PostgreSQL
+
+Add explicit `NOT FOUND` error handling to match Oracle behavior.
+
+**Fixed Code:**
+
+```plpgsql
+SELECT column_name
+INTO variable_name
+FROM table1, table2 
+WHERE table1.id = table2.id AND table1.id = parameter_value;
+
+-- Explicitly raise exception if no data found (matching Oracle behavior)
+IF NOT FOUND THEN
+    RAISE EXCEPTION 'no data found';
+END IF;
+
+IF variable_name = 'X' THEN
+ result_variable := 1;
+ELSE
+ result_variable := 2;
+END IF;
+```
+
+---
+
+## Migration Notes for Similar Issues
+
+When fixing this issue, verify:
+
+1. **Success path tests** - Confirm valid parameters still work correctly
+2. **Exception tests** - Verify exceptions are raised with invalid parameters
+3. **Transaction rollback** - Ensure proper cleanup on errors
+4. **Data integrity** - Confirm all fields are populated correctly in success cases

package/skills/reviewing-oracle-to-postgres-migration/references/oracle-parentheses-from-clause.md

@@ -0,0 +1,190 @@
+# Oracle to PostgreSQL: Parentheses in FROM Clause
+
+## Contents
+
+- Problem
+- Root Cause
+- Solution Pattern
+- Examples
+- Migration Checklist
+- Common Locations
+- Application Code Examples
+- Error Messages to Watch For
+- Testing Recommendations
+
+## Problem
+
+Oracle allows optional parentheses around table names in the FROM clause:
+
+```sql
+-- Oracle: Both are valid
+SELECT * FROM (TABLE_NAME) WHERE id = 1;
+SELECT * FROM TABLE_NAME WHERE id = 1;
+```
+
+PostgreSQL does **not** allow extra parentheses around a single table name in the FROM clause without it being a derived table or subquery. Attempting to use this pattern results in:
+
+```
+Npgsql.PostgresException: 42601: syntax error at or near ")"
+```
+
+## Root Cause
+
+- **Oracle**: Treats `FROM(TABLE_NAME)` as equivalent to `FROM TABLE_NAME`
+- **PostgreSQL**: Parentheses in the FROM clause are only valid for:
+  - Subqueries: `FROM (SELECT * FROM table)`
+  - Explicit table references that are part of join syntax
+  - Common Table Expressions (CTEs)
+  - Without a valid SELECT or join context, PostgreSQL raises a syntax error
+
+## Solution Pattern
+
+Remove the unnecessary parentheses around the table name:
+
+```sql
+-- Oracle (problematic in PostgreSQL)
+SELECT col1, col2
+FROM (TABLE_NAME)
+WHERE id = 1;
+
+-- PostgreSQL (correct)
+SELECT col1, col2
+FROM TABLE_NAME
+WHERE id = 1;
+```
+
+## Examples
+
+### Example 1: Simple Table Reference
+
+```sql
+-- Oracle
+SELECT employee_id, employee_name
+FROM (EMPLOYEES)
+WHERE department_id = 10;
+
+-- PostgreSQL (fixed)
+SELECT employee_id, employee_name
+FROM EMPLOYEES
+WHERE department_id = 10;
+```
+
+### Example 2: Join with Parentheses
+
+```sql
+-- Oracle (problematic)
+SELECT e.employee_id, d.department_name
+FROM (EMPLOYEES) e
+JOIN (DEPARTMENTS) d ON e.department_id = d.department_id;
+
+-- PostgreSQL (fixed)
+SELECT e.employee_id, d.department_name
+FROM EMPLOYEES e
+JOIN DEPARTMENTS d ON e.department_id = d.department_id;
+```
+
+### Example 3: Valid Subquery Parentheses (Works in Both)
+
+```sql
+-- Both Oracle and PostgreSQL
+SELECT *
+FROM (SELECT employee_id, employee_name FROM EMPLOYEES WHERE department_id = 10) sub;
+```
+
+## Migration Checklist
+
+When fixing this issue, verify:
+
+1. **Identify all problematic FROM clauses**:
+   - Search for `FROM (` pattern in SQL
+   - Verify the opening parenthesis is immediately after `FROM` followed by a table name
+   - Confirm it's **not** a subquery (no SELECT keyword inside)
+
+2. **Distinguish valid parentheses**:
+   - ✅ `FROM (SELECT ...)` - Valid subquery
+   - ✅ `FROM (table_name` followed by a join - Check if JOIN keyword follows
+   - ❌ `FROM (TABLE_NAME)` - Invalid, remove parentheses
+
+3. **Apply the fix**:
+   - Remove the parentheses around the table name
+   - Keep parentheses for legitimate subqueries
+
+4. **Test thoroughly**:
+   - Execute the query in PostgreSQL
+   - Verify result set matches original Oracle query
+   - Include in integration tests
+
+## Common Locations
+
+Search for `FROM (` in:
+
+- ✅ Stored procedures and functions (DDL scripts)
+- ✅ Application data access layers (DAL classes)
+- ✅ Dynamic SQL builders
+- ✅ Reporting queries
+- ✅ Views and materialized views
+- ✅ Complex queries with multiple joins
+
+## Application Code Examples
+
+### VB.NET
+
+```vb
+' Before (Oracle)
+StrSQL = "SELECT employee_id, NAME " _
+       & "FROM (EMPLOYEES) e " _
+       & "WHERE e.department_id = 10"
+
+' After (PostgreSQL)
+StrSQL = "SELECT employee_id, NAME " _
+       & "FROM EMPLOYEES e " _
+       & "WHERE e.department_id = 10"
+```
+
+### C #
+
+```csharp
+// Before (Oracle)
+var sql = "SELECT id, name FROM (USERS) WHERE status = @status";
+
+// After (PostgreSQL)
+var sql = "SELECT id, name FROM USERS WHERE status = @status";
+```
+
+## Error Messages to Watch For
+
+```
+Npgsql.PostgresException: 42601: syntax error at or near ")"
+ERROR: syntax error at or near ")"
+LINE 1: SELECT * FROM (TABLE_NAME) WHERE ...
+                      ^
+```
+
+## Testing Recommendations
+
+1. **Syntax Verification**: Parse all migrated queries to ensure they run without syntax errors
+
+   ```csharp
+   [Fact]
+   public void GetEmployees_ExecutesWithoutSyntaxError()
+   {
+       // Should not throw PostgresException with error code 42601
+       var employees = dal.GetEmployees(departmentId: 10);
+       Assert.NotEmpty(employees);
+   }
+   ```
+
+2. **Result Comparison**: Verify that result sets are identical before and after migration
+3. **Regex-based Search**: Use pattern `FROM\s*\(\s*[A-Za-z_][A-Za-z0-9_]*\s*\)` to identify candidates
+
+## Related Files
+
+- Reference: [oracle-to-postgres-type-coercion.md](oracle-to-postgres-type-coercion.md) - Other syntax differences
+- PostgreSQL Documentation: [SELECT Statement](https://www.postgresql.org/docs/current/sql-select.html)
+
+## Migration Notes
+
+- This is a straightforward syntactic fix with no semantic implications
+- No data conversion required
+- Safe to apply automated find-and-replace, but manually verify complex queries
+- Update integration tests to exercise the migrated queries

package/skills/reviewing-oracle-to-postgres-migration/references/oracle-to-postgres-sorting.md

@@ -0,0 +1,51 @@
+# Oracle to PostgreSQL Sorting Migration Guide
+
+Purpose: Preserve Oracle-like sorting semantics when moving queries to PostgreSQL.
+
+## Key points
+- Oracle often treats plain `ORDER BY` as binary/byte-wise, giving case-insensitive ordering for ASCII.
+- PostgreSQL defaults differ; to match Oracle behavior, use `COLLATE "C"` on sort expressions.
+
+## 1) Standard `SELECT … ORDER BY`
+**Goal:** Keep Oracle-style ordering.
+
+**Pattern:**
+```sql
+SELECT col1
+FROM your_table
+ORDER BY col1 COLLATE "C";
+```
+
+**Notes:**
+- Apply `COLLATE "C"` to each sort expression that must mimic Oracle.
+- Works with ascending/descending and multi-column sorts, e.g. `ORDER BY col1 COLLATE "C", col2 COLLATE "C" DESC`.
+
+## 2) `SELECT DISTINCT … ORDER BY`
+**Issue:** PostgreSQL enforces that `ORDER BY` expressions appear in the `SELECT` list for `DISTINCT`, raising:
+`Npgsql.PostgresException: 42P10: for SELECT DISTINCT, ORDER BY expressions must appear in select list`
+
+**Oracle difference:** Oracle allowed ordering by expressions not projected when using `DISTINCT`.
+
+**Recommended pattern (wrap and sort):**
+```sql
+SELECT *
+FROM (
+  SELECT DISTINCT col1, col2
+  FROM your_table
+) AS distinct_results
+ORDER BY col2 COLLATE "C";
+```
+
+**Why:**
+- The inner query performs the `DISTINCT` projection.
+- The outer query safely orders the result set and adds `COLLATE "C"` to align with Oracle sorting.
+
+**Tips:**
+- Ensure any columns used in the outer `ORDER BY` are included in the inner projection.
+- For multi-column sorts, collate each relevant expression: `ORDER BY col2 COLLATE "C", col3 COLLATE "C" DESC`.
+
+## Validation checklist
+- [ ] Added `COLLATE "C"` to every `ORDER BY` that should follow Oracle sorting rules.
+- [ ] For `DISTINCT` queries, wrapped the projection and sorted in the outer query.
+- [ ] Confirmed ordered columns are present in the inner projection.
+- [ ] Re-ran tests or representative queries to verify ordering matches Oracle outputs.

package/skills/reviewing-oracle-to-postgres-migration/references/oracle-to-postgres-timestamp-timezone.md

@@ -0,0 +1,187 @@
+# Oracle to PostgreSQL: CURRENT_TIMESTAMP and NOW() Timezone Handling
+
+## Contents
+
+- Problem
+- Behavior Comparison
+- PostgreSQL Timezone Precedence
+- Common Error Symptoms
+- Migration Actions — Npgsql config, DateTime normalization, stored procedures, session timezone, application code
+- Integration Test Patterns
+- Checklist
+
+## Problem
+
+Oracle's `CURRENT_TIMESTAMP` returns a value in the **session timezone** and stores it in the column's declared precision. When .NET reads this value back via ODP.NET, it is surfaced as a `DateTime` with `Kind=Local`, reflecting the OS timezone of the client.
+
+PostgreSQL's `CURRENT_TIMESTAMP` and `NOW()` both return a `timestamptz` (timestamp with time zone) anchored to **UTC**, regardless of the session timezone setting. How Npgsql surfaces this value depends on the driver version and configuration:
+
+- **Npgsql < 6 / legacy mode (`EnableLegacyTimestampBehavior = true`):** `timestamptz` columns are returned as `DateTime` with `Kind=Unspecified`. This is the source of silent timezone bugs when migrating from Oracle.
+- **Npgsql 6+ with legacy mode disabled (the new default):** `timestamptz` columns are returned as `DateTime` with `Kind=Utc`, and writing a `Kind=Unspecified` value throws an exception at insertion time.
+
+Projects that have not yet upgraded to Npgsql 6+, or that explicitly opt back into legacy mode, remain vulnerable to the `Kind=Unspecified` issue. This mismatch — and the ease of accidentally re-enabling legacy mode — causes silent data corruption, incorrect comparisons, and off-by-N-hours bugs that are extremely difficult to trace.
+
+---
+
+## Behavior Comparison
+
+| Aspect | Oracle | PostgreSQL |
+|---|---|---|
+| `CURRENT_TIMESTAMP` type | `TIMESTAMP WITH LOCAL TIME ZONE` | `timestamptz` (UTC-normalised) |
+| Client `DateTime.Kind` via driver | `Local` | `Unspecified` (Npgsql < 6 / legacy mode); `Utc` (Npgsql 6+ default) |
+| Session timezone influence | Yes — affects stored/returned value | Affects *display* only; UTC stored internally |
+| NOW() equivalent | `SYSDATE` / `CURRENT_TIMESTAMP` | `NOW()` = `CURRENT_TIMESTAMP` (both return `timestamptz`) |
+| Implicit conversion on comparison | Oracle applies session TZ offset | PostgreSQL compares UTC; session TZ is display-only |
+
+---
+
+## PostgreSQL Timezone Precedence
+
+PostgreSQL resolves the effective session timezone using the following hierarchy (highest priority wins):
+
+| Level | How it is set |
+|---|---|
+| **Session** | `SET TimeZone = 'UTC'` sent at connection open |
+| **Role** | `ALTER ROLE app_user SET TimeZone = 'UTC'` |
+| **Database** | `ALTER DATABASE mydb SET TimeZone = 'UTC'` |
+| **Server** | `postgresql.conf` → `TimeZone = 'America/New_York'` |
+
+The session timezone does **not** affect the stored UTC value of a `timestamptz` column — it only controls how `SHOW timezone` and `::text` casts format a value for display. Application code that relies on `DateTime.Kind` or compares timestamps without an explicit timezone can produce incorrect results if the server's default timezone is not UTC.
+
+---
+
+## Common Error Symptoms
+
+- Timestamps read from PostgreSQL have `Kind=Unspecified`; comparisons with `DateTime.UtcNow` or `DateTime.Now` produce incorrect results.
+- Date-range queries return too few or too many rows because the WHERE clause comparison is evaluated in a timezone that differs from the stored UTC value.
+- Integration tests pass on a developer machine (UTC OS timezone) but fail in CI or production (non-UTC timezone).
+- Stored procedure output parameters carrying timestamps arrive with a session-offset applied by the server but are then compared to UTC values in the application.
+
+---
+
+## Migration Actions
+
+### 1. Configure Npgsql for UTC via Connection String or AppContext
+
+Npgsql 6+ ships with `EnableLegacyTimestampBehavior` set to `false` by default, which causes `timestamptz` values to be returned as `DateTime` with `Kind=Utc`. Explicitly setting the switch at startup is still recommended to guard against accidental opt-in to legacy mode (e.g., via a config file or a transitive dependency) and to make the intent visible to future maintainers:
+
+```csharp
+// Program.cs / Startup.cs — apply once at application start
+AppContext.SetSwitch("Npgsql.EnableLegacyTimestampBehavior", false);
+```
+
+With this switch disabled, Npgsql throws if you try to write a `DateTime` with `Kind=Unspecified` to a `timestamptz` column, making timezone bugs loud and detectable at insertion time rather than silently at query time.
+
+### 2. Normalise DateTime Values Before Persistence
+
+Replace any `DateTime.Now` with `DateTime.UtcNow` throughout the migrated codebase. For values that originate from external input (e.g., user-provided dates deserialized from JSON), ensure they are converted to UTC before being saved:
+
+```csharp
+// Before (Oracle-era code — relied on session/OS timezone)
+var timestamp = DateTime.Now;
+
+// After (PostgreSQL-compatible)
+var timestamp = DateTime.UtcNow;
+
+// For externally-supplied values
+var utcTimestamp = dateTimeInput.Kind == DateTimeKind.Utc
+    ? dateTimeInput
+    : dateTimeInput.ToUniversalTime();
+```
+
+### 3. Fix Stored Procedures Using CURRENT_TIMESTAMP / NOW()
+
+Stored procedures that assign `CURRENT_TIMESTAMP` or `NOW()` to a `timestamp without time zone` (`timestamp`) column must be reviewed. Prefer `timestamptz` columns or cast explicitly:
+
+```sql
+-- Ambiguous: server timezone influences interpretation
+INSERT INTO audit_log (created_at) VALUES (NOW()::timestamp);
+
+-- Safe: always UTC
+INSERT INTO audit_log (created_at) VALUES (NOW() AT TIME ZONE 'UTC');
+
+-- Or: use timestamptz column type and let PostgreSQL store UTC natively
+INSERT INTO audit_log (created_at) VALUES (CURRENT_TIMESTAMP);
+```
+
+### 4. Force Session Timezone on Connection Open (Defence-in-Depth)
+
+Regardless of role or database defaults, set the session timezone explicitly when opening a connection. This guarantees consistent behavior independent of server configuration:
+
+```csharp
+// Npgsql connection string approach
+var connString = "Host=localhost;Database=mydb;Username=app;Password=...;Timezone=UTC";
+
+// Or: apply via NpgsqlDataSourceBuilder
+var dataSource = new NpgsqlDataSourceBuilder(connString)
+    .Build();
+
+// Or: execute on every new connection
+await using var conn = new NpgsqlConnection(connString);
+await conn.OpenAsync();
+await using var cmd = new NpgsqlCommand("SET TimeZone = 'UTC'", conn);
+await cmd.ExecuteNonQueryAsync();
+```
+
+### 5. Application Code — Avoid DateTime.Kind=Unspecified
+
+Audit all repository and data-access code that reads timestamp columns. Where Npgsql returns `Unspecified`, either configure the data source globally (option 1 above) or wrap the read:
+
+```csharp
+// Safe reader helper — convert Unspecified to Utc at the boundary
+DateTime ReadUtcDateTime(NpgsqlDataReader reader, int ordinal)
+{
+    var dt = reader.GetDateTime(ordinal);
+    return dt.Kind == DateTimeKind.Unspecified
+        ? DateTime.SpecifyKind(dt, DateTimeKind.Utc)
+        : dt.ToUniversalTime();
+}
+```
+
+---
+
+## Integration Test Patterns
+
+### Test: Verify timestamps persist and return as UTC
+
+```csharp
+[Fact]
+public async Task InsertedTimestamp_ShouldRoundTripAsUtc()
+{
+    var before = DateTime.UtcNow;
+
+    await repository.InsertAuditEntryAsync(/* ... */);
+
+    var retrieved = await repository.GetLatestAuditEntryAsync();
+
+    Assert.Equal(DateTimeKind.Utc, retrieved.CreatedAt.Kind);
+    Assert.True(retrieved.CreatedAt >= before,
+        "Persisted CreatedAt should not be earlier than the pre-insert UTC timestamp.");
+}
+```
+
+### Test: Verify timestamp comparisons across Oracle and PostgreSQL baselines
+
+```csharp
+[Fact]
+public async Task TimestampComparison_ShouldReturnSameRowsAsOracle()
+{
+    var cutoff = DateTime.UtcNow.AddDays(-1);
+
+    var oracleResults = await oracleRepository.GetEntriesAfter(cutoff);
+    var postgresResults = await postgresRepository.GetEntriesAfter(cutoff);
+
+    Assert.Equal(oracleResults.Count, postgresResults.Count);
+}
+```
+
+---
+
+## Checklist
+
+- [ ] `AppContext.SetSwitch("Npgsql.EnableLegacyTimestampBehavior", false)` applied at application startup.
+- [ ] All `DateTime.Now` usages in data-access code replaced with `DateTime.UtcNow`.
+- [ ] Connection string or connection-open hook sets `Timezone=UTC` / `SET TimeZone = 'UTC'`.
+- [ ] Stored procedures that use `CURRENT_TIMESTAMP` or `NOW()` reviewed; `timestamp without time zone` columns explicitly cast or replaced with `timestamptz`.
+- [ ] Integration tests assert `DateTime.Kind == Utc` on retrieved timestamp values.
+- [ ] Tests cover date-range queries to confirm row counts match Oracle baseline.