mirror of
https://github.com/github/awesome-copilot.git
synced 2026-07-14 01:51:02 +00:00
Enhance Oracle-to-PostgreSQL migration skills and documentation (#2284)
- Update migration agent guidelines to prioritize extension tool usage for code migration. - Refine migration phases with detailed steps for pre-migration review and schema migration. - Add new reviewing skill references for PostgreSQL materialized view refresh and UNION ALL planner risks. - Ensure consistency in collation handling and testing strategies across skills. Co-authored-by: TCPrimedPaul <paul.delannoy@tc.gc.ca>
This commit is contained in:
Paul Delannoy
GitHub
@@ -15,6 +15,7 @@ You are an expert **Oracle-to-PostgreSQL migration agent** with deep knowledge i
|
||||
- **Suggest, don't assume.** Present recommended next steps as options. Explain the purpose and expected outcome of each step. Do not chain tasks automatically.
|
||||
- **Confirm before invoking extension tools.** Before invoking any extension tool, ask the user if they want to proceed. Use `vscode/askQuestions` for structured confirmation when appropriate.
|
||||
- **One step at a time.** After completing a step, summarize what was produced and suggest the logical next step. Do not auto-advance to the next task.
|
||||
- **Extension tool first for code migration.** When the user asks to migrate application code, always recommend `pgsql_migration_oracle_app` as the primary approach before doing manual code edits. If the extension is not installed, offer to install it. Only perform manual migration if the user explicitly declines the extension tool.
|
||||
- **Act directly.** Use `edit`, `runInTerminal`, `read`, and `search` tools to analyze the workspace, make code changes, and run commands. You perform migration tasks yourself rather than delegating to subagents.
|
||||
|
||||
## Guidelines
|
||||
@@ -23,6 +24,7 @@ You are an expert **Oracle-to-PostgreSQL migration agent** with deep knowledge i
|
||||
- Minimize changes — map Oracle behaviors to PostgreSQL equivalents carefully; prioritize well-tested libraries.
|
||||
- Preserve comments and application logic unless absolutely necessary to change.
|
||||
- PostgreSQL schema is immutable — no DDL alterations to tables, views, indexes, constraints, or sequences. The only permitted DDL changes are `CREATE OR REPLACE` of stored procedures and functions.
|
||||
- Never apply database changes directly on behalf of the user. Generate scripts and explicit run instructions so the user applies DB changes themselves.
|
||||
- Oracle is the source of truth for expected application behavior during validation.
|
||||
- Be concise and clear in your explanations. Use tables and lists to structure advice.
|
||||
- When reading reference files, synthesize the guidance for the user — don't just dump raw content.
|
||||
@@ -30,22 +32,44 @@ You are an expert **Oracle-to-PostgreSQL migration agent** with deep knowledge i
|
||||
|
||||
## Migration Phases
|
||||
|
||||
Present this as a guide — the user decides which steps to take and when.
|
||||
Present this as a guide — the user decides which steps to take and when. Each phase applies *per project* unless noted.
|
||||
|
||||
1. **Discovery & Planning** — Discover projects in the solution, classify migration eligibility, set up DDL artifacts under `.github/oracle-to-postgres-migration/DDL/`.
|
||||
2. **Code Migration** *(per project)* — Convert application code Oracle data access patterns to PostgreSQL equivalents; translate stored procedures from PL/SQL to PL/pgSQL.
|
||||
3. **Validation** *(per project)* — Plan integration testing, scaffold test infrastructure, create and run tests, document defects.
|
||||
4. **Reporting** — Generate a final migration summary report per project.
|
||||
1. **Discovery & Planning** *(solution-wide)* — Discover all projects in the solution, classify migration eligibility, and produce the master migration plan. Set up DDL artifacts under `.github/oracle-to-postgres-migration/DDL/`.
|
||||
|
||||
2. **Pre-Migration Review** *(per project)* — Before touching any code, establish the Oracle baseline:
|
||||
- Confirm the existing Oracle-targeting tests compile and pass (Oracle is the source of truth — a failing baseline means defects exist *before* migration starts).
|
||||
- Cross-reference code against known Oracle/PostgreSQL behavioral differences and produce a risk inventory.
|
||||
- Do not proceed to code migration until the baseline is green and risks are documented.
|
||||
|
||||
3. **Schema & DDL Migration** *(per project)* — Migrate the Oracle schema to PostgreSQL. Output all artifacts to `DDL/Postgres/`:
|
||||
- Migrate tables, sequences, views, and other schema objects.
|
||||
- Migrate stored procedures (PL/SQL to PL/pgSQL). Tools like `ora2pg` can assist with initial translation, but automated output is imperfect and requires manual review and correction against expected Oracle behavior.
|
||||
|
||||
4. **Code Migration** *(per project)* — Migrate the application or library project to target PostgreSQL:
|
||||
- Use `pgsql_migration_oracle_app` as the primary tool (see **Extension Tools**). If not installed, offer to install it first.
|
||||
- Only perform manual application code migration if the user explicitly declines the extension tool.
|
||||
- After migration, validate that all risks identified in Phase 2 were addressed.
|
||||
|
||||
5. **PostgreSQL Test Project Creation & Validation** *(per project)* — Create a *new, separate* test project targeting PostgreSQL. **Do not modify the Oracle-targeting test project** — it must remain pure so Oracle behavior continues to be proven independently.
|
||||
- Scaffold the new test project, plan test coverage, and write integration tests.
|
||||
- Use a distinct local PostgreSQL port and project namespace (e.g., `{OriginalProject}.Postgres`) to avoid collisions with Oracle-era components.
|
||||
- Document any behavioral discrepancies found during test runs as structured bug reports. Stored procedure defects identified here are corrected in Phase 3 and retested.
|
||||
|
||||
6. **Reporting** — Generate a final migration summary report per project.
|
||||
|
||||
## Extension Tools
|
||||
|
||||
Two workflow steps can be performed by the `ms-ossdata.vscode-pgsql` extension:
|
||||
|
||||
- `pgsql_migration_oracle_app` — Scans application code and converts Oracle data access patterns to PostgreSQL equivalents.
|
||||
- `pgsql_migration_oracle_app` — **Primary tool for code migration.** Scans application code and converts Oracle data access patterns to PostgreSQL equivalents. Always recommend this before performing manual code migration.
|
||||
- `pgsql_migration_show_report` — Produces a final migration summary report.
|
||||
|
||||
Before invoking either tool: explain what it does, verify the extension is installed, and confirm with the user.
|
||||
|
||||
After running `pgsql_migration_oracle_app`, recommend an isolation setup before testing:
|
||||
- Use a distinct local PostgreSQL port for the migrated test run (do not share the Oracle-era/default local port).
|
||||
- Use a distinct project namespace for migrated artifacts (for example `{OriginalProject}.Postgres`) to avoid collisions with Oracle-targeted components.
|
||||
|
||||
## Working Directory
|
||||
|
||||
Migration artifacts should be stored under `.github/oracle-to-postgres-migration/`, if not, ask the user where to find what you need to be of help:
|
||||
|
||||
@@ -249,7 +249,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-skills) for guidelines on how to
|
||||
| [microsoft-code-reference](../skills/microsoft-code-reference/SKILL.md)<br />`gh skills install github/awesome-copilot microsoft-code-reference` | Look up Microsoft API references, find working code samples, and verify SDK code is correct. Use when working with Azure SDKs, .NET libraries, or Microsoft APIs—to find the right method, check parameters, get working examples, or troubleshoot errors. Catches hallucinated methods, wrong signatures, and deprecated patterns by querying official docs. | None |
|
||||
| [microsoft-docs](../skills/microsoft-docs/SKILL.md)<br />`gh skills install github/awesome-copilot microsoft-docs` | Query official Microsoft documentation to find concepts, tutorials, and code examples across Azure, .NET, Agent Framework, Aspire, VS Code, GitHub, and more. Uses Microsoft Learn MCP as the default, with Context7 and Aspire MCP for content that lives outside learn.microsoft.com. | None |
|
||||
| [microsoft-skill-creator](../skills/microsoft-skill-creator/SKILL.md)<br />`gh skills install github/awesome-copilot microsoft-skill-creator` | Create agent skills for Microsoft technologies using Learn MCP tools. Use when users want to create a skill that teaches agents about any Microsoft technology, library, framework, or service (Azure, .NET, M365, VS Code, Bicep, etc.). Investigates topics deeply, then generates a hybrid skill storing essential knowledge locally while enabling dynamic deeper investigation. | `references/skill-templates.md` |
|
||||
| [migrating-oracle-to-postgres-stored-procedures](../skills/migrating-oracle-to-postgres-stored-procedures/SKILL.md)<br />`gh skills install github/awesome-copilot migrating-oracle-to-postgres-stored-procedures` | Migrates Oracle PL/SQL stored procedures to PostgreSQL PL/pgSQL. Translates Oracle-specific syntax, preserves method signatures and type-anchored parameters, leverages orafce where appropriate, and applies COLLATE "C" for Oracle-compatible text sorting. Use when converting Oracle stored procedures or functions to PostgreSQL equivalents during a database migration. | None |
|
||||
| [migrating-oracle-to-postgres-stored-procedures](../skills/migrating-oracle-to-postgres-stored-procedures/SKILL.md)<br />`gh skills install github/awesome-copilot migrating-oracle-to-postgres-stored-procedures` | Migrates Oracle PL/SQL stored procedures to PostgreSQL PL/pgSQL. Translates Oracle-specific syntax, preserves method signatures and type-anchored parameters, leverages orafce where appropriate, and applies explicit collation mapping (`COLLATE "C"` only when appropriate, locale collations when required). Use when converting Oracle stored procedures or functions to PostgreSQL equivalents during a database migration. | None |
|
||||
| [minecraft-plugin-development](../skills/minecraft-plugin-development/SKILL.md)<br />`gh skills install github/awesome-copilot minecraft-plugin-development` | Use this skill when building or modifying Minecraft server plugins for Paper, Spigot, or Bukkit, including plugin.yml setup, commands, listeners, schedulers, player state, team or arena systems, persistent progression, economy or profile data, configuration files, Adventure text, and version-safe API usage. Trigger for requests like "build a Minecraft plugin", "add a Paper command", "fix a Bukkit listener", "create plugin.yml", "implement a minigame mechanic", "add a perk or quest system", or "debug server plugin behavior". | `references/bootstrap-registration.md`<br />`references/build-test-and-runtime-validation.md`<br />`references/config-data-and-async.md`<br />`references/maps-heroes-and-feature-modules.md`<br />`references/minigame-instance-flow.md`<br />`references/persistent-progression-and-events.md`<br />`references/project-patterns.md`<br />`references/state-sessions-and-phases.md` |
|
||||
| [mini-context-graph](../skills/mini-context-graph/SKILL.md)<br />`gh skills install github/awesome-copilot mini-context-graph` | A persistent, compounding knowledge base combining Karpathy's LLM Wiki pattern<br />with a structured knowledge graph. Ingest documents once — the LLM writes wiki<br />pages, extracts entities/relations into the graph, and stores raw content for<br />evidence retrieval. Knowledge accumulates and cross-references; it is never<br />re-derived from scratch. | `references/ingestion.md`<br />`references/lint.md`<br />`references/ontology.md`<br />`references/retrieval.md`<br />`scripts/config.py`<br />`scripts/contextgraph.py`<br />`scripts/template_agent_workflow.py`<br />`scripts/tools` |
|
||||
| [mkdocs-translations](../skills/mkdocs-translations/SKILL.md)<br />`gh skills install github/awesome-copilot mkdocs-translations` | Generate a language translation for a mkdocs documentation stack. | None |
|
||||
@@ -335,7 +335,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-skills) for guidelines on how to
|
||||
| [repo-story-time](../skills/repo-story-time/SKILL.md)<br />`gh skills install github/awesome-copilot repo-story-time` | Generate a comprehensive repository summary and narrative story from commit history | None |
|
||||
| [resemble-detect](../skills/resemble-detect/SKILL.md)<br />`gh skills install github/awesome-copilot resemble-detect` | Deepfake detection and media safety — detect AI-generated audio, images, video, and text, trace synthesis sources, apply watermarks, verify speaker identity, and analyze media intelligence using Resemble AI | `LICENSE`<br />`references/api-reference.md` |
|
||||
| [review-and-refactor](../skills/review-and-refactor/SKILL.md)<br />`gh skills install github/awesome-copilot review-and-refactor` | Review and refactor code in your project according to defined instructions | None |
|
||||
| [reviewing-oracle-to-postgres-migration](../skills/reviewing-oracle-to-postgres-migration/SKILL.md)<br />`gh skills install github/awesome-copilot reviewing-oracle-to-postgres-migration` | 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. | `references/REFERENCE.md`<br />`references/empty-strings-handling.md`<br />`references/no-data-found-exceptions.md`<br />`references/oracle-parentheses-from-clause.md`<br />`references/oracle-to-postgres-sorting.md`<br />`references/oracle-to-postgres-timestamp-timezone.md`<br />`references/oracle-to-postgres-to-char-numeric.md`<br />`references/oracle-to-postgres-type-coercion.md`<br />`references/postgres-concurrent-transactions.md`<br />`references/postgres-refcursor-handling.md` |
|
||||
| [reviewing-oracle-to-postgres-migration](../skills/reviewing-oracle-to-postgres-migration/SKILL.md)<br />`gh skills install github/awesome-copilot reviewing-oracle-to-postgres-migration` | Identifies Oracle-to-PostgreSQL migration risks by cross-referencing code against known behavioral differences (empty strings, refcursors, type coercion, sorting/collations, UNION ALL planner risks, materialized-view refresh requirements, timestamps, concurrent transactions, etc.). Use when planning a database migration, reviewing migration artifacts, or validating that integration tests cover Oracle/PostgreSQL differences. | `references/REFERENCE.md`<br />`references/empty-strings-handling.md`<br />`references/no-data-found-exceptions.md`<br />`references/oracle-parentheses-from-clause.md`<br />`references/oracle-to-postgres-sorting.md`<br />`references/oracle-to-postgres-timestamp-timezone.md`<br />`references/oracle-to-postgres-to-char-numeric.md`<br />`references/oracle-to-postgres-type-coercion.md`<br />`references/postgres-concurrent-transactions.md`<br />`references/postgres-materialized-view-refresh.md`<br />`references/postgres-refcursor-handling.md`<br />`references/postgres-union-all-planner.md` |
|
||||
| [rhino3d-scripts](../skills/rhino3d-scripts/SKILL.md)<br />`gh skills install github/awesome-copilot rhino3d-scripts` | Authoring and debugging scripts for Rhinoceros 3D (Rhino 8 and later). Use when asked to write RhinoScript (VBScript / .rvb / .vbs), RhinoPython, or RhinoCommon-based scripts; automate Rhino modeling tasks; build command macros; manipulate Rhino geometry, layers, blocks, or document objects; pick objects from the viewport; control redraw and undo; or load and run scripts from the Rhino Script Editor. Covers `rhinoscriptsyntax`, `scriptcontext`, the `Rhino.*` RhinoCommon namespaces (`Rhino.Geometry`, `Rhino.DocObjects`, `Rhino.Input`, `Rhino.UI`, `Rhino.Display`, `Rhino.FileIO`), and the Rhino 8 unified Script Editor. | `references/macros-and-loading.md`<br />`references/rhinocommon-map.md`<br />`references/rhinoscriptsyntax-cheatsheet.md`<br />`references/vbscript-quirks.md` |
|
||||
| [roundup](../skills/roundup/SKILL.md)<br />`gh skills install github/awesome-copilot roundup` | Generate personalized status briefings on demand. Pulls from your configured data sources (GitHub, email, Teams, Slack, and more), synthesizes across them, and drafts updates in your own communication style for any audience you define. | None |
|
||||
| [roundup-setup](../skills/roundup-setup/SKILL.md)<br />`gh skills install github/awesome-copilot roundup-setup` | Interactive onboarding that learns your communication style, audiences, and data sources to configure personalized status briefings. Paste in examples of updates you already write, answer a few questions, and roundup calibrates itself to your workflow. | `references/config-template.md` |
|
||||
|
||||
@@ -21,9 +21,9 @@ copilot plugin install oracle-to-postgres-migration-expert@awesome-copilot
|
||||
|
||||
| Skill | Description |
|
||||
|-------|-------------|
|
||||
| `reviewing-oracle-to-postgres-migration` | Identifies Oracle-to-PostgreSQL migration risks by cross-referencing code against known behavioral differences (empty strings, refcursors, type coercion, sorting, timestamps, concurrent transactions, etc.). |
|
||||
| `reviewing-oracle-to-postgres-migration` | Identifies Oracle-to-PostgreSQL migration risks by cross-referencing code against known behavioral differences (empty strings, refcursors, type coercion, sorting/collations, UNION ALL planning risks, materialized-view refresh behavior, timestamps, concurrent transactions, etc.). |
|
||||
| `creating-oracle-to-postgres-master-migration-plan` | Discovers all projects in a .NET solution, classifies each for Oracle-to-PostgreSQL migration eligibility, and produces a persistent master migration plan. |
|
||||
| `migrating-oracle-to-postgres-stored-procedures` | Migrates Oracle PL/SQL stored procedures to PostgreSQL PL/pgSQL. Translates Oracle-specific syntax, preserves method signatures and type-anchored parameters, and applies `COLLATE "C"` for Oracle-compatible text sorting. |
|
||||
| `migrating-oracle-to-postgres-stored-procedures` | Migrates Oracle PL/SQL stored procedures to PostgreSQL PL/pgSQL. Translates Oracle-specific syntax, preserves method signatures and type-anchored parameters, and applies explicit collation rules (`"C"` only when appropriate, locale-specific collations when required). |
|
||||
| `planning-oracle-to-postgres-migration-integration-testing` | Creates an integration testing plan for .NET data access artifacts, identifying repositories, DAOs, and service layers that need validation coverage. |
|
||||
| `scaffolding-oracle-to-postgres-migration-test-project` | Scaffolds an xUnit integration test project with a transaction-rollback base class and seed data manager for Oracle-to-PostgreSQL migration validation. |
|
||||
| `creating-oracle-to-postgres-migration-integration-tests` | Generates DB-agnostic xUnit integration tests with deterministic seed data that validate behavior consistency across both database systems. |
|
||||
@@ -35,7 +35,7 @@ copilot plugin install oracle-to-postgres-migration-expert@awesome-copilot
|
||||
|
||||
The expert agent educates users throughout the migration journey:
|
||||
|
||||
- **Migration Concepts**: Explains Oracle→PostgreSQL differences (empty strings vs NULL, NO_DATA_FOUND exceptions, sort order, TO_CHAR conversions, type coercion strictness, REF CURSOR handling, concurrent transactions, timestamp/timezone behavior)
|
||||
- **Migration Concepts**: Explains Oracle→PostgreSQL differences (empty strings vs NULL, NO_DATA_FOUND exceptions, sort/collation behavior, TO_CHAR conversions, type coercion strictness, REF CURSOR handling, UNION ALL planning caveats, materialized-view refresh needs, concurrent transactions, timestamp/timezone behavior)
|
||||
- **Pitfall Reference**: Surfaces insights from migration knowledge so users understand why changes are needed
|
||||
- **Best Practices**: Advises on minimizing changes, preserving logic, and ensuring schema immutability
|
||||
- **Workflow Guidance**: Presents a four-phase migration workflow as a guide users can follow at their own pace
|
||||
@@ -52,6 +52,8 @@ The expert suggests actionable next steps and only proceeds with user confirmati
|
||||
|
||||
No autonomous chaining — the user controls the pace and sequence.
|
||||
|
||||
For database-changing actions, the expert provides scripts and explicit run instructions; the user applies DB changes.
|
||||
|
||||
## Migration Workflow
|
||||
|
||||
The expert guides users through a four-phase workflow:
|
||||
|
||||
@@ -36,17 +36,22 @@ Scope to the target project only. List data access methods that interact with th
|
||||
- Follow seed file location and naming conventions from the existing project.
|
||||
- Reuse existing seed files when possible.
|
||||
- Avoid `TRUNCATE TABLE` — keep existing database data intact.
|
||||
- Assume existing business rows and lookup rows are already present; add only minimal, collision-safe seed records needed for the scenario.
|
||||
- Do not commit seed data; tests run in transactions that roll back.
|
||||
- Ensure seed data does not conflict with other tests.
|
||||
- Load and verify seed data before assertions depend on it.
|
||||
- Create or reuse a test `LookupConstants` class for stable lookup IDs/codes used across seed builders and assertions.
|
||||
|
||||
**Step 4: Write test cases**
|
||||
|
||||
- Inherit from the base test class to get automatic transaction create/rollback.
|
||||
- Ensure each database-touching method in scope has at least one integration test (or multiple tests for higher-risk behavior branches).
|
||||
- Assert logical outputs (rows, columns, counts, error types), not platform-specific messages.
|
||||
- Assert specific expected values — never assert that a value is merely non-null or non-empty when a concrete value is available from seed data.
|
||||
- Avoid testing code paths that do not exist or asserting behavior that cannot occur.
|
||||
- Avoid redundant assertions across tests targeting the same method.
|
||||
- For text parameters, include both empty-string and `NULL`/missing input coverage where applicable.
|
||||
- For datetime behavior, include explicit timezone-sensitive assertions when methods write/read `timestamp without time zone` or `timestamp(0)` targets.
|
||||
|
||||
**Step 5: Review determinism**
|
||||
|
||||
@@ -58,3 +63,4 @@ Re-examine every assertion against non-null values. Confirm each is deterministi
|
||||
- **DB-agnostic assertions** — no platform-specific error messages or syntax in assertions.
|
||||
- **Seed only against Oracle** — test project will be migrated to PostgreSQL later.
|
||||
- **Scoped to one project** — do not create tests for artifacts outside the target project.
|
||||
- **Preserve existing data** — never rewrite or wipe pre-existing business or lookup rows.
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: migrating-oracle-to-postgres-stored-procedures
|
||||
description: 'Migrates Oracle PL/SQL stored procedures to PostgreSQL PL/pgSQL. Translates Oracle-specific syntax, preserves method signatures and type-anchored parameters, leverages orafce where appropriate, and applies COLLATE "C" for Oracle-compatible text sorting. Use when converting Oracle stored procedures or functions to PostgreSQL equivalents during a database migration.'
|
||||
description: 'Migrates Oracle PL/SQL stored procedures to PostgreSQL PL/pgSQL. Translates Oracle-specific syntax, preserves method signatures and type-anchored parameters, leverages orafce where appropriate, and applies explicit collation mapping (`COLLATE "C"` only when appropriate, locale collations when required). Use when converting Oracle stored procedures or functions to PostgreSQL equivalents during a database migration.'
|
||||
---
|
||||
|
||||
# Migrating Stored Procedures from Oracle to PostgreSQL
|
||||
@@ -32,7 +32,11 @@ Apply these translation rules:
|
||||
- Do not prefix object names with schema names unless already present in the Oracle source.
|
||||
- Leave exception handling and rollback logic unchanged.
|
||||
- Do not generate `COMMENT` or `GRANT` statements.
|
||||
- Use `COLLATE "C"` when ordering by text fields for Oracle-compatible sorting.
|
||||
- Apply collation intentionally when ordering text:
|
||||
- Use `COLLATE "C"` only when Oracle-compatible binary ordering is required and no other sort order is specified.
|
||||
- If Oracle used explicit linguistic sorting (for example `NLS_SORT = French`), map to an explicit PostgreSQL locale collation instead of `"C"`.
|
||||
- Use `SELECT collname, collprovider, collcollate, collctype FROM pg_collation ORDER BY collname;` to discover collations in the target environment.
|
||||
- Treat `UNION ALL` as a review checkpoint. Validate plan quality per branch and restructure if combined-branch planning causes regressions (for example, unexpected sequential scans on large tables).
|
||||
- Leverage the `orafce` extension when it improves clarity or fidelity.
|
||||
|
||||
Consult the PostgreSQL table/view definitions at `.github/oracle-to-postgres-migration/DDL/Postgres/Tables and Views/` for target schema details.
|
||||
|
||||
@@ -31,6 +31,12 @@ Write a markdown plan covering:
|
||||
- Recommended test cases per artifact
|
||||
- Seed data requirements
|
||||
- Known Oracle→PostgreSQL behavioral differences to validate
|
||||
- Coverage mapping that ensures every database touchpoint has at least one test case (or a justified set of cases for high-risk methods)
|
||||
|
||||
When defining recommended test cases, explicitly include:
|
||||
- Text parameter behavior for both empty string and `NULL`/missing values.
|
||||
- Datetime/timezone assertions, including round-trip and comparison behavior.
|
||||
- Cases where destination columns use `timestamp without time zone` or `timestamp(0)`, with explicit timezone-application expectations.
|
||||
|
||||
## Output
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
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.'
|
||||
description: 'Identifies Oracle-to-PostgreSQL migration risks by cross-referencing code against known behavioral differences (empty strings, refcursors, type coercion, sorting/collations, UNION ALL planner risks, materialized-view refresh requirements, 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
|
||||
@@ -60,7 +60,7 @@ For each reference in [references/REFERENCE.md](references/REFERENCE.md), confir
|
||||
|
||||
**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.).
|
||||
Confirm tests exercise both the happy path and the failure scenarios highlighted in applicable insights (exceptions, sorting, `UNION ALL` behavior/performance risks, refcursor consumption, concurrent transactions, timestamps, materialized-view freshness, etc.).
|
||||
|
||||
**Step 4: Gate the result**
|
||||
|
||||
|
||||
@@ -8,6 +8,8 @@
|
||||
| [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-union-all-planner.md](postgres-union-all-planner.md) | UNION ALL branches can produce poor plans when predicate pushdown is limited—review plans and split or reshape queries when needed. |
|
||||
| [postgres-materialized-view-refresh.md](postgres-materialized-view-refresh.md) | Materialized views are not auto-refreshed after base-table changes—application or jobs must explicitly refresh them. |
|
||||
| [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. |
|
||||
|
||||
+25
-6
@@ -3,13 +3,14 @@
|
||||
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.
|
||||
- Oracle and PostgreSQL default collations can differ significantly.
|
||||
- Use `COLLATE "C"` only when you explicitly need Oracle-like binary ordering and no different sort rule is requested.
|
||||
- If Oracle uses explicit linguistic ordering (for example `NLS_SORT = French`), map to an explicit PostgreSQL locale collation instead of forcing `"C"`.
|
||||
|
||||
## 1) Standard `SELECT … ORDER BY`
|
||||
**Goal:** Keep Oracle-style ordering.
|
||||
|
||||
**Pattern:**
|
||||
**Pattern (only when Oracle-compatible binary ordering is required):**
|
||||
```sql
|
||||
SELECT col1
|
||||
FROM your_table
|
||||
@@ -17,9 +18,27 @@ ORDER BY col1 COLLATE "C";
|
||||
```
|
||||
|
||||
**Notes:**
|
||||
- Apply `COLLATE "C"` to each sort expression that must mimic Oracle.
|
||||
- Apply `COLLATE "C"` only to sort expressions that must mimic Oracle binary ordering.
|
||||
- Works with ascending/descending and multi-column sorts, e.g. `ORDER BY col1 COLLATE "C", col2 COLLATE "C" DESC`.
|
||||
|
||||
## 1b) Locale-aware ordering (when Oracle used NLS_SORT)
|
||||
|
||||
If Oracle used locale-specific sorting such as:
|
||||
```sql
|
||||
ORDER BY nlssort(Externalusers.UserID, 'NLS_SORT = French')
|
||||
```
|
||||
map to an explicit PostgreSQL collation, for example:
|
||||
```sql
|
||||
ORDER BY Externalusers.UserID COLLATE "ca_FR.utf-8"
|
||||
```
|
||||
|
||||
Use a collation that exists in the target environment. Discover available collations with:
|
||||
```sql
|
||||
SELECT collname, collprovider, collcollate, collctype
|
||||
FROM pg_collation
|
||||
ORDER BY collname;
|
||||
```
|
||||
|
||||
## 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`
|
||||
@@ -38,14 +57,14 @@ 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.
|
||||
- The outer query safely orders the result set and adds an explicit collation where needed 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.
|
||||
- [ ] Applied explicit collation only where required (`"C"` for Oracle-style binary ordering, locale collation for linguistic ordering).
|
||||
- [ ] 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.
|
||||
|
||||
+35
@@ -0,0 +1,35 @@
|
||||
# PostgreSQL Materialized View Refresh Guide
|
||||
|
||||
Purpose: Ensure migrated applications keep materialized views current after base-table changes.
|
||||
|
||||
## Problem
|
||||
|
||||
PostgreSQL materialized views are static snapshots. Updates to source tables do **not** automatically refresh dependent materialized views.
|
||||
|
||||
## Migration risk
|
||||
|
||||
- Oracle-era assumptions that derived data updates immediately may no longer hold.
|
||||
- Read paths can return stale rows unless refresh timing is explicitly managed.
|
||||
- Integration tests may pass once and then fail intermittently if refresh sequencing is not deterministic.
|
||||
|
||||
## Required review item
|
||||
|
||||
For every migrated path that writes to tables feeding a materialized view, verify the application workflow includes an explicit refresh strategy.
|
||||
|
||||
## Refresh patterns
|
||||
|
||||
- Immediate refresh in the write workflow when freshness is required:
|
||||
```sql
|
||||
REFRESH MATERIALIZED VIEW my_view;
|
||||
```
|
||||
- Concurrent refresh (when supported and indexed) to reduce read blocking:
|
||||
```sql
|
||||
REFRESH MATERIALIZED VIEW CONCURRENTLY my_view;
|
||||
```
|
||||
- Scheduled/batch refresh when stale windows are acceptable.
|
||||
|
||||
## Integration-test expectations
|
||||
|
||||
- [ ] Tests that modify source tables assert materialized-view contents only after the intended refresh action.
|
||||
- [ ] Tests assert stale behavior before refresh when applicable.
|
||||
- [ ] Tests document whether freshness is immediate or eventual for each affected feature.
|
||||
+31
@@ -0,0 +1,31 @@
|
||||
# PostgreSQL UNION ALL Planner Risk Guide
|
||||
|
||||
Purpose: Avoid regressions where migrated `UNION ALL` queries run much slower in PostgreSQL than expected.
|
||||
|
||||
## Problem
|
||||
|
||||
`UNION ALL` keeps duplicate rows and combines branch outputs directly, but PostgreSQL does not always optimize each branch as aggressively as isolated queries. In large datasets this can produce poor plans (for example full scans where index-based plans are expected).
|
||||
|
||||
## Why it happens
|
||||
|
||||
- Predicate pushdown through `UNION ALL` branches can be limited depending on query shape.
|
||||
- Cardinality estimates across branches can be skewed.
|
||||
- Branch-local indexes may not be chosen when the optimizer evaluates the combined query.
|
||||
|
||||
## Review checklist
|
||||
|
||||
- [ ] Compare `EXPLAIN (ANALYZE, BUFFERS)` plans for the combined `UNION ALL` query and branch-isolated variants.
|
||||
- [ ] Confirm branch predicates are explicit and not hidden inside non-sargable expressions.
|
||||
- [ ] Check for unexpected sequential scans on large tables in either branch.
|
||||
- [ ] Verify indexes exist for each branch's filter and join predicates.
|
||||
|
||||
## Mitigation patterns
|
||||
|
||||
1. Test each branch independently to verify expected index usage.
|
||||
2. Push filters down into each branch instead of only filtering in the outer query.
|
||||
3. If plan quality remains poor, split the query into two separately executed statements and combine results in application code.
|
||||
4. Consider materializing branch results in temporary/intermediate structures only when measurement confirms benefit.
|
||||
|
||||
## Validation note
|
||||
|
||||
Treat `UNION ALL` performance behavior as a migration review item even when functional test results match Oracle.
|
||||
Reference in New Issue
Block a user