Creating Oracle-to-PostgreSQL migration bug reports
Turn a migration defect into a reproducible report that compares Oracle baseline behavior with PostgreSQL behavior and names the exact remediation and validation path while preserving runtime/language context.
When to invoke
- "Create a bug report for this Oracle-to-PostgreSQL migration defect."
- "Document this PostgreSQL behavior difference from Oracle."
- "Write a migration bug report with severity and root cause."
- "Save a BUG_REPORT file for this stored procedure issue."
Prerequisites and context
- Use
references/BUG-REPORT-TEMPLATE.md as the report template.
- Oracle is the source of truth for expected behavior.
- Save reports to
.github/oracle-to-postgres-migration/Reports/{ProjectName}/BUG_REPORT_<DescriptiveSlug>.md.
{ProjectName} is the project assembly or folder name with spaces normalized to -, for example MyApp.DataAccess.<DescriptiveSlug> is a short PascalCase defect identifier such as EmptyStringNullHandling or RefCursorUnwrapFailure.- Preserve search compatibility with legacy migration notes that used
assembly/folder and (e.g. wording.
Bug report fields
| Field |
Required content |
| Status |
RESOLVED, UNRESOLVED, or IN PROGRESS. |
| Component |
Affected endpoint, repository, stored procedure, function, package, query, or migration file. |
| Test |
Related automated test names or the missing test that should be added. |
| Severity |
Low, Medium, High, or Critical based on impact scope. |
| Problem |
Expected Oracle behavior versus observed PostgreSQL behavior. |
| Scenario |
Ordered reproduction 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, including explicit file paths. |
| Validation |
Steps to confirm the fix on both Oracle and PostgreSQL. |
Oracle-to-PostgreSQL defect taxonomy
| Difference |
Evidence to capture |
Typical remediation direction |
| Empty string vs. NULL |
Input value, stored value, comparison result. |
Normalize at data boundary or adjust SQL predicates deliberately. |
| Type coercion strictness |
Oracle accepted implicit conversion but PostgreSQL rejected or compared differently. |
Add explicit casts or correct parameter types. |
| Collation and sorting |
Ordered result differs. |
Specify intended PostgreSQL collation or query order. |
| Sequence values |
Generated IDs diverge or sequence starts incorrectly. |
Align sequence ownership, start value, and next value. |
| Time zones |
Timestamp comparison or display differs. |
Use the correct timestamp type and explicit timezone handling. |
| Padding |
CHAR/VARCHAR comparisons or trailing spaces differ. |
Trim, change type, or preserve Oracle semantics intentionally. |
| Constraints |
PostgreSQL rejects data Oracle allowed, or missing constraints allow bad data. |
Add, relax, or migrate constraints with justification. |
Client code changes should be avoided unless required for correct behavior; when proposed, document and justify them clearly.
Writing rules
- Use plain language, short sentences, and clear next actions.
- Use present or past tense consistently.
- Use bullets and numbered lists for reproduction steps and validations.
- Include minimal SQL excerpts and logs as evidence; omit sensitive data and keep snippets reproducible.
- Stick to existing runtime and language versions; avoid speculative fixes.
Progressive disclosure and bundled resources
references/BUG-REPORT-TEMPLATE.md: canonical report structure to copy before filling evidence.
Output template
## Oracle-to-PostgreSQL migration bug report
**Status:** created | draft | blocked
**File:** `.github/oracle-to-postgres-migration/Reports/<ProjectName>/BUG_REPORT_<DescriptiveSlug>.md`
### Report fields
| Field | Value |
| --- | --- |
| Status | `RESOLVED` / `UNRESOLVED` / `IN PROGRESS` |
| Component | `<endpoint, repository, stored procedure, or file>` |
| Test | `<test names>` |
| Severity | `Low` / `Medium` / `High` / `Critical` |
| Root Cause | `<Oracle/PostgreSQL behavioral difference>` |
### Validation
- Oracle baseline reproduced: <yes/no>
- PostgreSQL divergence reproduced: <yes/no>
- Fix verified on both databases: <yes/no or pending>
Quality gate
1---2name: creating-oracle-to-postgres-migration-bug-report-23description: Create structured bug reports for Oracle-to-PostgreSQL migration defects with source-of-truth Oracle behavior, PostgreSQL divergence, severity, root cause, remediation, validation, and filename convention. Use when documenting behavioral differences, failed migration tests, or data-layer defects during an Oracle-to-PostgreSQL migration.4---56# Creating Oracle-to-PostgreSQL migration bug reports78Turn a migration defect into a reproducible report that compares Oracle baseline behavior with PostgreSQL behavior and names the exact remediation and validation path while preserving runtime/language context.910## When to invoke1112- "Create a bug report for this Oracle-to-PostgreSQL migration defect."13- "Document this PostgreSQL behavior difference from Oracle."14- "Write a migration bug report with severity and root cause."15- "Save a BUG_REPORT file for this stored procedure issue."1617## Prerequisites and context1819- Use `references/BUG-REPORT-TEMPLATE.md` as the report template.20- Oracle is the source of truth for expected behavior.21- Save reports to `.github/oracle-to-postgres-migration/Reports/{ProjectName}/BUG_REPORT_<DescriptiveSlug>.md`.22- `{ProjectName}` is the project assembly or folder name with spaces normalized to `-`, for example `MyApp.DataAccess`.23- `<DescriptiveSlug>` is a short PascalCase defect identifier such as `EmptyStringNullHandling` or `RefCursorUnwrapFailure`.24- Preserve search compatibility with legacy migration notes that used `assembly/folder` and ` (e.g. ` wording.2526## Bug report fields2728| Field | Required content |29| --- | --- |30| Status | `RESOLVED`, `UNRESOLVED`, or `IN PROGRESS`. |31| Component | Affected endpoint, repository, stored procedure, function, package, query, or migration file. |32| Test | Related automated test names or the missing test that should be added. |33| Severity | Low, Medium, High, or Critical based on impact scope. |34| Problem | Expected Oracle behavior versus observed PostgreSQL behavior. |35| Scenario | Ordered reproduction with seed data, operation, expected result, and actual result. |36| Root Cause | The specific Oracle/PostgreSQL behavioral difference causing the defect. |37| Solution | Changes made or required, including explicit file paths. |38| Validation | Steps to confirm the fix on both Oracle and PostgreSQL. |3940## Oracle-to-PostgreSQL defect taxonomy4142| Difference | Evidence to capture | Typical remediation direction |43| --- | --- | --- |44| Empty string vs. NULL | Input value, stored value, comparison result. | Normalize at data boundary or adjust SQL predicates deliberately. |45| Type coercion strictness | Oracle accepted implicit conversion but PostgreSQL rejected or compared differently. | Add explicit casts or correct parameter types. |46| Collation and sorting | Ordered result differs. | Specify intended PostgreSQL collation or query order. |47| Sequence values | Generated IDs diverge or sequence starts incorrectly. | Align sequence ownership, start value, and next value. |48| Time zones | Timestamp comparison or display differs. | Use the correct timestamp type and explicit timezone handling. |49| Padding | `CHAR`/`VARCHAR` comparisons or trailing spaces differ. | Trim, change type, or preserve Oracle semantics intentionally. |50| Constraints | PostgreSQL rejects data Oracle allowed, or missing constraints allow bad data. | Add, relax, or migrate constraints with justification. |5152Client code changes should be avoided unless required for correct behavior; when proposed, document and justify them clearly.5354## Writing rules5556- Use plain language, short sentences, and clear next actions.57- Use present or past tense consistently.58- Use bullets and numbered lists for reproduction steps and validations.59- Include minimal SQL excerpts and logs as evidence; omit sensitive data and keep snippets reproducible.60- Stick to existing runtime and language versions; avoid speculative fixes.6162## Progressive disclosure and bundled resources6364- `references/BUG-REPORT-TEMPLATE.md`: canonical report structure to copy before filling evidence.6566## Output template6768```markdown69## Oracle-to-PostgreSQL migration bug report7071**Status:** created | draft | blocked72**File:** `.github/oracle-to-postgres-migration/Reports/<ProjectName>/BUG_REPORT_<DescriptiveSlug>.md`7374### Report fields75| Field | Value |76| --- | --- |77| Status | `RESOLVED` / `UNRESOLVED` / `IN PROGRESS` |78| Component | `<endpoint, repository, stored procedure, or file>` |79| Test | `<test names>` |80| Severity | `Low` / `Medium` / `High` / `Critical` |81| Root Cause | `<Oracle/PostgreSQL behavioral difference>` |8283### Validation84- Oracle baseline reproduced: <yes/no>85- PostgreSQL divergence reproduced: <yes/no>86- Fix verified on both databases: <yes/no or pending>87```8889## Quality gate9091- [ ] The report uses `references/BUG-REPORT-TEMPLATE.md`.92- [ ] Oracle behavior is stated as expected behavior and PostgreSQL behavior is stated as observed behavior.93- [ ] Severity is justified by impact scope.94- [ ] Root cause names a concrete Oracle/PostgreSQL behavioral difference, not a vague migration failure.95- [ ] Scenario includes seed data, operation, expected result, and actual result.96- [ ] Solution names explicit file paths and avoids client changes unless justified.97- [ ] Validation covers both Oracle and PostgreSQL.98- [ ] Filename follows `.github/oracle-to-postgres-migration/Reports/{ProjectName}/BUG_REPORT_<DescriptiveSlug>.md`.
paulasilvatech