devskill 2.0.7 → 2.0.8

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

@@ -0,0 +1,145 @@
+# Oracle to PostgreSQL: TO_CHAR() Numeric Conversions
+
+## Contents
+
+- Problem
+- Root Cause
+- Solution Patterns — CAST, format string, concatenation
+- Migration Checklist
+- Application Code Review
+- Testing Recommendations
+- Common Locations
+- Error Messages to Watch For
+
+## Problem
+
+Oracle allows `TO_CHAR()` to convert numeric types to strings without a format specifier:
+
+```sql
+-- Oracle: Works fine
+SELECT TO_CHAR(vessel_id) FROM vessels;
+SELECT TO_CHAR(fiscal_year) FROM certificates;
+```
+
+PostgreSQL requires a format string when using `TO_CHAR()` with numeric types, otherwise it raises:
+
+```
+42883: function to_char(numeric) does not exist
+```
+
+## Root Cause
+
+- **Oracle**: `TO_CHAR(number)` without a format mask implicitly converts the number to a string using default formatting
+- **PostgreSQL**: `TO_CHAR()` always requires an explicit format string for numeric types (e.g., `'999999'`, `'FM999999'`)
+
+## Solution Patterns
+
+### Pattern 1: Use CAST (Recommended)
+
+The cleanest migration approach is to replace `TO_CHAR(numeric_column)` with `CAST(numeric_column AS TEXT)`:
+
+```sql
+-- Oracle
+SELECT TO_CHAR(vessel_id) AS vessel_item FROM vessels;
+
+-- PostgreSQL (preferred)
+SELECT CAST(vessel_id AS TEXT) AS vessel_item FROM vessels;
+```
+
+**Advantages:**
+
+- More idiomatic in PostgreSQL
+- Clearer intent
+- No format string needed
+
+### Pattern 2: Provide Format String
+
+If you need specific numeric formatting, use an explicit format mask:
+
+```sql
+-- PostgreSQL with format
+SELECT TO_CHAR(vessel_id, 'FM999999') AS vessel_item FROM vessels;
+SELECT TO_CHAR(amount, 'FM999999.00') AS amount_text FROM payments;
+```
+
+**Format masks:**
+
+- `'FM999999'`: Fixed-width integer (FM = Fill Mode, removes leading spaces)
+- `'FM999999.00'`: Decimal with 2 places
+- `'999,999.00'`: With thousand separators
+
+### Pattern 3: String Concatenation
+
+For simple concatenation where numeric conversion is implicit:
+
+```sql
+-- Oracle
+WHERE TO_CHAR(fiscal_year) = '2024'
+
+-- PostgreSQL (using concatenation)
+WHERE fiscal_year::TEXT = '2024'
+-- or
+WHERE CAST(fiscal_year AS TEXT) = '2024'
+```
+
+## Migration Checklist
+
+When migrating SQL containing `TO_CHAR()`:
+
+1. **Identify all TO_CHAR() calls**: Search for `TO_CHAR\(` in SQL strings, stored procedures, and application queries
+2. **Check the argument type**:
+   - **DATE/TIMESTAMP**: Keep `TO_CHAR()` with format string (e.g., `TO_CHAR(date_col, 'YYYY-MM-DD')`)
+   - **NUMERIC/INTEGER**: Replace with `CAST(... AS TEXT)` or add format string
+3. **Test the output**: Verify that the string representation matches expectations (no unexpected spaces, decimals, etc.)
+4. **Update comparison logic**: If comparing numeric-to-string, ensure consistent types on both sides
+
+## Application Code Review
+
+### C# Example
+
+```csharp
+// Before (Oracle)
+var sql = "SELECT TO_CHAR(id) AS id_text FROM entities WHERE TO_CHAR(status) = @status";
+
+// After (PostgreSQL)
+var sql = "SELECT CAST(id AS TEXT) AS id_text FROM entities WHERE CAST(status AS TEXT) = @status";
+```
+
+## Testing Recommendations
+
+1. **Unit Tests**: Verify numeric-to-string conversions return expected values
+
+   ```csharp
+   [Fact]
+   public void GetVesselNumbers_ReturnsVesselIdsAsStrings()
+   {
+       var results = dal.GetVesselNumbers(certificateType);
+       Assert.All(results, item => Assert.True(int.TryParse(item.DISPLAY_MEMBER, out _)));
+   }
+   ```
+
+2. **Integration Tests**: Ensure queries with `CAST()` execute without errors
+3. **Comparison Tests**: Verify WHERE clauses with numeric-to-string comparisons filter correctly
+
+## Common Locations
+
+Search for `TO_CHAR` in:
+
+- ✅ Stored procedures and functions (DDL scripts)
+- ✅ Application data access layers (DAL classes)
+- ✅ Dynamic SQL builders
+- ✅ Reporting queries
+- ✅ ORM/Entity Framework raw SQL
+
+## Error Messages to Watch For
+
+```
+Npgsql.PostgresException: 42883: function to_char(numeric) does not exist
+Npgsql.PostgresException: 42883: function to_char(integer) does not exist
+Npgsql.PostgresException: 42883: function to_char(bigint) does not exist
+```
+
+## See Also
+
+- [oracle-to-postgres-type-coercion.md](oracle-to-postgres-type-coercion.md) - Related type conversion issues
+- PostgreSQL Documentation: [Data Type Formatting Functions](https://www.postgresql.org/docs/current/functions-formatting.html)

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

@@ -0,0 +1,182 @@
+# Oracle to PostgreSQL Type Coercion Issues
+
+## Contents
+
+- Overview
+- The Problem — symptom, root cause, example
+- The Solution — string literals, explicit casting
+- Common Comparison Operators Affected
+- Detection Strategy
+- Real-World Example
+- Prevention Best Practices
+
+## Overview
+
+This document describes a common migration issue encountered when porting SQL code from Oracle to PostgreSQL. The issue stems from fundamental differences in how these databases handle implicit type conversions in comparison operators.
+
+## The Problem
+
+### Symptom
+
+When migrating SQL queries from Oracle to PostgreSQL, you may encounter the following error:
+
+```
+Npgsql.PostgresException: 42883: operator does not exist: character varying <> integer
+POSITION: [line_number]
+```
+
+### Root Cause
+
+PostgreSQL has **strict type enforcement** and does not perform implicit type coercion in comparison operators. Oracle, by contrast, automatically converts operands to compatible types during comparison operations.
+
+#### Example Mismatch
+
+**Oracle SQL (works fine):**
+
+```sql
+AND physical_address.pcountry_cd <> 124
+```
+
+- `pcountry_cd` is a `VARCHAR2`
+- `124` is an integer literal
+- Oracle silently converts `124` to a string for comparison
+
+**PostgreSQL (fails):**
+
+```sql
+AND physical_address.pcountry_cd <> 124
+```
+
+```
+42883: operator does not exist: character varying <> integer
+```
+
+- `pcountry_cd` is a `character varying`
+- `124` is an integer literal
+- PostgreSQL rejects the comparison because the types don't match
+
+## The Solution
+
+### Approach 1: Use String Literals (Recommended)
+
+Convert integer literals to string literals:
+
+```sql
+AND physical_address.pcountry_cd <> '124'
+```
+
+**Pros:**
+
+- Semantically correct (country codes are typically stored as strings)
+- Most efficient
+- Clearest intent
+
+**Cons:**
+
+- None
+
+### Approach 2: Explicit Type Casting
+
+Explicitly cast the integer to a string type:
+
+```sql
+AND physical_address.pcountry_cd <> CAST(124 AS VARCHAR)
+```
+
+**Pros:**
+
+- Makes the conversion explicit and visible
+- Useful if the value is a parameter or complex expression
+
+**Cons:**
+
+- Slightly less efficient
+- More verbose
+
+## Common Comparison Operators Affected
+
+All comparison operators can trigger this issue:
+
+- `<>` (not equal)
+- `=` (equal)
+- `<` (less than)
+- `>` (greater than)
+- `<=` (less than or equal)
+- `>=` (greater than or equal)
+
+## Detection Strategy
+
+When migrating from Oracle to PostgreSQL:
+
+1. **Search for numeric literals in WHERE clauses** comparing against string/varchar columns
+2. **Look for patterns like:**
+   - `column_name <> 123` (where column is VARCHAR/CHAR)
+   - `column_name = 456` (where column is VARCHAR/CHAR)
+   - `column_name IN (1, 2, 3)` (where column is VARCHAR/CHAR)
+
+3. **Code review checklist:**
+   - Are all comparison values correctly typed?
+   - Do string columns always use string literals?
+   - Are numeric columns always compared against numeric values?
+
+## Real-World Example
+
+**Original Oracle Query:**
+
+```sql
+SELECT ac040.stakeholder_id,
+       ac006.organization_etxt
+  FROM ac040_stakeholder ac040
+  INNER JOIN ac006_organization ac006 ON ac040.stakeholder_id = ac006.organization_id
+ WHERE physical_address.pcountry_cd <> 124
+   AND LOWER(ac006.organization_etxt) LIKE '%' || @orgtxt || '%'
+ ORDER BY UPPER(ac006.organization_etxt)
+```
+
+**Fixed PostgreSQL Query:**
+
+```sql
+SELECT ac040.stakeholder_id,
+       ac006.organization_etxt
+  FROM ac040_stakeholder ac040
+  INNER JOIN ac006_organization ac006 ON ac040.stakeholder_id = ac006.organization_id
+ WHERE physical_address.pcountry_cd <> '124'
+   AND LOWER(ac006.organization_etxt) LIKE '%' || @orgtxt || '%'
+ ORDER BY UPPER(ac006.organization_etxt)
+```
+
+**Change:** `124` → `'124'`
+
+## Prevention Best Practices
+
+1. **Use Type-Consistent Literals:**
+   - For string columns: Always use string literals (`'value'`)
+   - For numeric columns: Always use numeric literals (`123`)
+   - For dates: Always use date literals (`DATE '2024-01-01'`)
+
+2. **Leverage Database Tools:**
+   - Use your IDE's SQL linter to catch type mismatches
+   - Run PostgreSQL syntax validation during code review
+
+3. **Test Early:**
+   - Execute migration queries against PostgreSQL before deployment
+   - Include integration tests that exercise all comparison operators
+
+4. **Documentation:**
+   - Document any type coercions in comments
+   - Mark migrated code with revision history
+
+## References
+
+- [PostgreSQL Type Casting Documentation](https://www.postgresql.org/docs/current/sql-syntax.html)
+- [Oracle Type Conversion Documentation](https://docs.oracle.com/database/121/SQLRF/sql_elements003.htm)
+- [Npgsql Exception: Operator Does Not Exist](https://www.npgsql.org/doc/api/NpgsqlException.html)
+
+## Related Issues
+
+This issue is part of broader Oracle → PostgreSQL migration challenges:
+
+- Implicit function conversions (e.g., `TO_CHAR`, `TO_DATE`)
+- String concatenation operator differences (`||` works in both, but behavior differs)
+- Numeric precision and rounding differences
+- NULL handling in comparisons

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

@@ -0,0 +1,259 @@
+# Oracle to PostgreSQL: Concurrent Transaction Handling
+
+## Contents
+
+- Overview
+- The Core Difference
+- Common Error Symptoms
+- Problem Scenarios
+- Solutions — materialize results, separate connections, single query
+- Detection Strategy
+- Error Messages to Watch For
+- Comparison Table
+- Best Practices
+- Migration Checklist
+
+## Overview
+
+When migrating from Oracle to PostgreSQL, a critical difference exists in how **concurrent operations on a single database connection** are handled. Oracle's ODP.NET driver allows multiple active commands and result sets on the same connection simultaneously, while PostgreSQL's Npgsql driver enforces a strict **one active command per connection** rule. Code that worked seamlessly in Oracle will throw runtime exceptions in PostgreSQL if concurrent operations share a connection.
+
+## The Core Difference
+
+**Oracle Behavior:**
+
+- A single connection can have multiple active commands executing concurrently
+- Opening a second `DataReader` while another is still open is permitted
+- Nested or overlapping database calls on the same connection work transparently
+
+**PostgreSQL Behavior:**
+
+- A connection supports only **one active command at a time**
+- Attempting to execute a second command while a `DataReader` is open throws an exception
+- Lazy-loaded navigation properties or callback-driven reads that trigger additional queries on the same connection will fail
+
+## Common Error Symptoms
+
+When migrating Oracle code without accounting for this difference:
+
+```
+System.InvalidOperationException: An operation is already in progress.
+```
+
+```
+Npgsql.NpgsqlOperationInProgressException: A command is already in progress: <SQL text>
+```
+
+These occur when application code attempts to execute a new command on a connection that already has an active `DataReader` or uncommitted command in flight.
+
+---
+
+## Problem Scenarios
+
+### Scenario 1: Iterating a DataReader While Executing Another Command
+
+```csharp
+using (var reader = command1.ExecuteReader())
+{
+    while (reader.Read())
+    {
+        // PROBLEM: executing a second command on the same connection
+        // while the reader is still open
+        using (var command2 = new NpgsqlCommand("SELECT ...", connection))
+        {
+            var value = command2.ExecuteScalar(); // FAILS
+        }
+    }
+}
+```
+
+### Scenario 2: Lazy Loading / Deferred Execution in Data Access Layers
+
+```csharp
+// Oracle: works because ODP.NET supports concurrent readers
+var items = repository.GetItems(); // returns IEnumerable backed by open DataReader
+foreach (var item in items)
+{
+    // PROBLEM: triggers a second query on the same connection
+    var details = repository.GetDetails(item.Id); // FAILS on PostgreSQL
+}
+```
+
+### Scenario 3: Nested Stored Procedure Calls via Application Code
+
+```csharp
+// Oracle: ODP.NET handles multiple active commands
+command1.ExecuteNonQuery(); // starts a long-running operation
+command2.ExecuteScalar();   // FAILS on PostgreSQL — command1 still in progress
+```
+
+---
+
+## Solutions
+
+### Solution 1: Materialize Results Before Issuing New Commands (Recommended)
+
+Close the first result set by loading it into memory before executing subsequent commands on the same connection.
+
+```csharp
+// Load all results into a list first
+var items = new List<Item>();
+using (var reader = command1.ExecuteReader())
+{
+    while (reader.Read())
+    {
+        items.Add(MapItem(reader));
+    }
+} // reader is closed and disposed here
+
+// Now safe to execute another command on the same connection
+foreach (var item in items)
+{
+    using (var command2 = new NpgsqlCommand("SELECT ...", connection))
+    {
+        command2.Parameters.AddWithValue("id", item.Id);
+        var value = command2.ExecuteScalar(); // Works
+    }
+}
+```
+
+For LINQ / EF Core scenarios, force materialization with `.ToList()`:
+
+```csharp
+// Before (fails on PostgreSQL — deferred execution keeps connection busy)
+var items = dbContext.Items.Where(i => i.Active);
+foreach (var item in items)
+{
+    var details = dbContext.Details.FirstOrDefault(d => d.ItemId == item.Id);
+}
+
+// After (materializes first query before issuing second)
+var items = dbContext.Items.Where(i => i.Active).ToList();
+foreach (var item in items)
+{
+    var details = dbContext.Details.FirstOrDefault(d => d.ItemId == item.Id);
+}
+```
+
+### Solution 2: Use Separate Connections for Concurrent Operations
+
+When operations genuinely need to run concurrently, open a dedicated connection for each.
+
+```csharp
+using (var reader = command1.ExecuteReader())
+{
+    while (reader.Read())
+    {
+        // Use a separate connection for the nested query
+        using (var connection2 = new NpgsqlConnection(connectionString))
+        {
+            connection2.Open();
+            using (var command2 = new NpgsqlCommand("SELECT ...", connection2))
+            {
+                var value = command2.ExecuteScalar(); // Works — different connection
+            }
+        }
+    }
+}
+```
+
+### Solution 3: Restructure to a Single Query
+
+Where possible, combine nested lookups into a single query using JOINs or subqueries to eliminate the need for concurrent commands entirely.
+
+```csharp
+// Before: two sequential queries on the same connection
+var order = GetOrder(orderId);          // query 1
+var details = GetOrderDetails(orderId); // query 2 (fails if query 1 reader still open)
+
+// After: single query with JOIN
+using (var command = new NpgsqlCommand(
+    "SELECT o.*, d.* FROM orders o JOIN order_details d ON o.id = d.order_id WHERE o.id = @id",
+    connection))
+{
+    command.Parameters.AddWithValue("id", orderId);
+    using (var reader = command.ExecuteReader())
+    {
+        // Process combined result set
+    }
+}
+```
+
+---
+
+## Detection Strategy
+
+### Code Review Checklist
+
+- [ ] Search for methods that open a `DataReader` and call other database methods before closing it
+- [ ] Look for `IEnumerable` return types from data access methods that defer execution (indicate open readers)
+- [ ] Identify EF Core queries without `.ToList()` / `.ToArray()` that are iterated while issuing further queries
+- [ ] Check for nested stored procedure calls in application code that share a connection
+
+### Common Locations to Search
+
+- Data access layers and repository classes
+- Service methods that orchestrate multiple repository calls
+- Code paths that iterate query results and perform lookups per row
+- Event handlers or callbacks triggered during data iteration
+
+### Search Patterns
+
+```regex
+ExecuteReader\(.*\)[\s\S]*?Execute(Scalar|NonQuery|Reader)\(
+```
+
+```regex
+\.Where\(.*\)[\s\S]*?foreach[\s\S]*?dbContext\.
+```
+
+---
+
+## Error Messages to Watch For
+
+| Error Message | Likely Cause |
+|---------------|--------------|
+| `An operation is already in progress` | Second command executed while a `DataReader` is open on the same connection |
+| `A command is already in progress: <SQL>` | Npgsql detected overlapping command execution on a single connection |
+| `The connection is already in state 'Executing'` | Connection state conflict from concurrent usage |
+
+---
+
+## Comparison Table: Oracle vs. PostgreSQL
+
+| Aspect | Oracle (ODP.NET) | PostgreSQL (Npgsql) |
+|--------|------------------|---------------------|
+| **Concurrent commands** | Multiple active commands per connection | One active command per connection |
+| **Multiple open DataReaders** | Supported | Not supported — must close/materialize first |
+| **Nested DB calls during iteration** | Transparent | Throws `InvalidOperationException` |
+| **Deferred execution safety** | Safe to iterate and query | Must materialize (`.ToList()`) before issuing new queries |
+| **Connection pooling impact** | Lower connection demand | May need more pooled connections if using Solution 2 |
+
+---
+
+## Best Practices
+
+1. **Materialize early** — Call `.ToList()` or `.ToArray()` on query results before iterating and issuing further database calls. This is the simplest and most reliable fix.
+
+2. **Audit data access patterns** — Review all repository and data access methods for deferred-execution return types (`IEnumerable`, `IQueryable`) that callers iterate while issuing additional queries.
+
+3. **Prefer single queries** — Where feasible, combine nested lookups into JOINs or subqueries to eliminate the concurrent-command pattern entirely.
+
+4. **Isolate connections when necessary** — If concurrent operations are genuinely required, use separate connections rather than attempting to share one.
+
+5. **Test iterative workflows** — Integration tests should cover scenarios where code iterates result sets and performs additional database operations per row, as these are the most common failure points.
+
+## Migration Checklist
+
+- [ ] Identify all code paths that execute multiple commands on a single connection concurrently
+- [ ] Locate `IEnumerable`-backed data access methods that defer execution with open readers
+- [ ] Add `.ToList()` / `.ToArray()` materialization where deferred results are iterated alongside further queries
+- [ ] Refactor nested database calls to use separate connections or combined queries where appropriate
+- [ ] Verify EF Core navigation properties and lazy loading do not trigger concurrent connection usage
+- [ ] Update integration tests to cover iterative data access patterns
+- [ ] Load-test connection pool sizing if Solution 2 (separate connections) is used extensively
+
+## References
+
+- [Npgsql Documentation: Basic Usage](https://www.npgsql.org/doc/basic-usage.html)
+- [PostgreSQL Documentation: Concurrency Control](https://www.postgresql.org/docs/current/mvcc.html)
+- [Npgsql GitHub: Multiple Active Result Sets Discussion](https://github.com/npgsql/npgsql/issues/462)