Creating Oracle To Postgres Migration Bug Report

Creating Bug Reports for Oracle-to-PostgreSQL Migration

When to Use

• Documenting a defect caused by behavioral differences between Oracle and PostgreSQL
• Writing or reviewing a bug report for an Oracle-to-PostgreSQL migration project

Bug Report Format

Use the template in references/BUG-REPORT-TEMPLATE.md. Each report must include:

• Status: ✅ RESOLVED, ⛔ UNRESOLVED, or ⏳ IN PROGRESS
• Component: Affected endpoint, repository, or stored procedure
• Test: Related automated test names
• Severity: Low / Medium / High / Critical — based on impact scope
• Problem: Expected Oracle behavior vs. observed PostgreSQL behavior
• Scenario: Ordered reproduction steps with seed data, operation, expected result, and actual result
• Root Cause: The specific Oracle/PostgreSQL behavioral difference causing the defect
• Solution: Changes made or required, with explicit file paths
• Validation: Steps to confirm the fix on both databases

Oracle-to-PostgreSQL Guidance

• Oracle is the source of truth — frame expected behavior from the Oracle baseline
• Call out data layer nuances explicitly: empty string vs. NULL, type coercion strictness, collation, sequence values, time zones, padding, constraints
• Client code changes should be avoided unless required for correct behavior; when proposed, document and justify them clearly

Writing Style

• Plain language, short sentences, clear next actions
• Present or past tense consistently
• Bullets and numbered lists for steps and validations
• Minimal SQL excerpts and logs as evidence; omit sensitive data and keep snippets reproducible
• Stick to existing runtime/language versions; avoid speculative fixes

Filename Convention

Save bug reports as BUG_REPORT_<DescriptiveSlug>.md where <DescriptiveSlug> is a short PascalCase identifier (e.g., EmptyStringNullHandling, RefCursorUnwrapFailure).

Bug Report Template

Use this template when creating bug reports for Oracle-to-PostgreSQL migration defects.

Filename Format

BUG_REPORT_<DescriptiveSlug>.md

Template Structure

# Bug Report: <Title>

**Status:** ✅ RESOLVED | ⛔ UNRESOLVED | ⏳ IN PROGRESS
**Component:** <High-level component/endpoint and key method(s)>
**Test:** <Related automated test names>
**Severity:** Low | Medium | High | Critical

---

## Problem

<Observable incorrect behavior. State expected behavior (Oracle baseline)
versus actual behavior (PostgreSQL). Be specific and factual.>

## Scenario

<Ordered steps to reproduce the defect. Include:
1. Prerequisites and seed data
2. Exact operation or API call
3. Expected result (Oracle)
4. Actual result (PostgreSQL)>

## Root Cause

<Minimal, concrete technical cause. Reference the specific Oracle/PostgreSQL
behavioral difference (e.g., empty string vs NULL, type coercion strictness).>

## Solution

<Changes made or required. Be explicit about data access layer changes,
tracking flags, and any client code modifications. Note whether changes
are already applied or still needed.>

## Validation

<Bullet list of passing tests or manual checks that confirm the fix:
- Re-run reproduction steps on both Oracle and PostgreSQL
- Compare row/column outputs
- Check error handling parity>

## Files Modified

<Bullet list with relative file paths and short purpose for each change:
- `src/DataAccess/FooRepository.cs` — Added explicit NULL check for empty string parameter>

## Notes / Next Steps

<Follow-ups, environment caveats, risks, or dependencies on other fixes.>

Status Values

Style Rules

• Keep wording concise and factual
• Use present or past tense consistently
• Prefer bullets and numbered lists for steps and validation
• Call out data layer nuances (tracking, padding, constraints) explicitly
• Keep to existing runtime/language versions; avoid speculative fixes
• Include minimal SQL excerpts and logs as evidence; omit sensitive data