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

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 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

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

Save bug reports to .github/oracle-to-postgres-migration/Reports/{ProjectName}/BUG_REPORT_<DescriptiveSlug>.md where:

{ProjectName} is the project's assembly/folder name with spaces normalized to - (e.g. MyApp.DataAccess)
<DescriptiveSlug> is a short PascalCase identifier describing the defect (e.g., EmptyStringNullHandling, RefCursorUnwrapFailure)