mirror of
https://github.com/github/awesome-copilot.git
synced 2026-08-14 21:26:54 +00:00
Paul Delannoy
f7e8aaa2d8
* Enhance Oracle-to-PostgreSQL migration skills and documentation
- 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.
* - Review migration phases to ensure correct order of execution
- Add exit criteria to each migration phase
- Remove invocation of `ms-ossdata.vscode-pgsql` extension due to dependency on VSCode
- Update README.md to reflect changes in migration phases and exit criteria
- Update broken reference to custom agent in plugin.json
* Enhance downstream migration skills and following custom agent improvements
- Added new skill for migrating .NET data access code from Oracle to PostgreSQL.
- Updated README to include new migration skill.
- Improved existing skills with clearer file naming conventions and migration actions.
- Added reference documents for handling Oracle-specific functions and pagination.
- Created detailed guides for NVL, DECODE, ROWNUM, SYSDATE, and DUAL replacements.
* Clarify PostgreSQL schema immutability and stored procedure migration risks
* Update target schema path in migration documentation for clarity
* fix(skills): clarify Phase 3-only scope for Oracle test skills
Both Oracle test skills were ambiguously worded in ways that could
cause a model to invoke them during Phase 6 (PostgreSQL test migration)
instead of using them exclusively in Phase 3.
Key changes:
- Rewrite descriptions to explicitly state Phase 3-only usage and
warn against invoking during Phase 6
- Replace "scaffold for Oracle first" with "Oracle only" to remove
the false implication of a second PostgreSQL scaffolding step
- Replace "Tests validate behavior consistency when running against
Oracle or PostgreSQL" with clear Oracle-only framing
- Rename "DB-agnostic assertions" → "Assertion portability" and
explain the why (survive Phase 6 migration without rewrites)
- Fix datetime bullet in integration tests skill to use generic
Oracle column precision language instead of PostgreSQL type syntax
- Name Oracle NuGet package explicitly (Oracle.ManagedDataAccess.Core)
* feat(oracle-to-postgres): gate Phase 1 on DDL presence; add DDL scan to Phase 2 risk analysis
- Phase 1 success criteria now requires Oracle DDL artifacts to be
confirmed present at the recorded location before proceeding.
If missing, the agent stops and prompts the user to provide them.
- Phase 2 risk analysis now explicitly scans DDL/Oracle/{ProjectName}/
as supplemental context, summarising procedure complexity indicators
(dynamic SQL, DBMS_* / UTL_* references, autonomous transactions,
pipelined functions, BULK COLLECT/FORALL, REF CURSOR, TYPE bodies)
rather than ingesting DDL files wholesale. This ensures schema-level
migration risk is captured even when it isn't visible in application
code alone.
* - Merge in latest 'main' changes
- Update custom agent plugin (eg resolve conflict and add new skill)
- Validate skills
- Run build
* chore(plugin.json): update version to 1.1.0
* feat(oracle-to-postgres): update version to 1.1.0 for migration expert plugin
* fix: add INOUT to ignore-words-list for PostgreSQL migration
---------
Co-authored-by: TCPrimedPaul <paul.delannoy@tc.gc.ca>
140 lines
8.0 KiB
Markdown
140 lines
8.0 KiB
Markdown
# Oracle-to-PostgreSQL Migration Expert Plugin
|
|
|
|
Expert agent for Oracle-to-PostgreSQL application migrations in .NET solutions. Performs code edits, runs commands, and guides users through a structured, gated migration workflow.
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
# Using Copilot CLI
|
|
copilot plugin install oracle-to-postgres-migration-expert@awesome-copilot
|
|
```
|
|
|
|
## What's Included
|
|
|
|
### Agents
|
|
|
|
| Agent | Description |
|
|
|-------|-------------|
|
|
| `Oracle-to-PostgreSQL Migration Expert` | Expert agent for Oracle→PostgreSQL migrations. Makes code edits and runs commands directly, educates users on migration concepts and pitfalls. |
|
|
|
|
### Skills
|
|
|
|
| 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/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 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. |
|
|
| `creating-oracle-to-postgres-migration-bug-report` | Creates structured bug reports for defects discovered during Oracle-to-PostgreSQL migration validation, with severity, root cause, and remediation steps. |
|
|
| `migrating-oracle-to-postgres-data-access-code` | Migrates .NET/C# data access code from Oracle to PostgreSQL (Npgsql). Replaces Oracle NuGet packages, rewrites ADO.NET type references, fixes DbType mappings, updates stored procedure invocation patterns, and adapts connection string configuration. |
|
|
|
|
## Features
|
|
|
|
### Educational Guidance
|
|
|
|
The expert agent educates users throughout the migration journey:
|
|
|
|
- **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 six-phase, gated migration workflow with explicit success criteria at each gate
|
|
|
|
### Suggest-Then-Act Pattern
|
|
|
|
The expert suggests actionable next steps and only proceeds with user confirmation:
|
|
|
|
1. **Educate** on the migration topic and why it matters
|
|
2. **Suggest** a recommended action with expected outcomes
|
|
3. **Confirm** the user wants to proceed
|
|
4. **Act** — make edits and run commands directly
|
|
5. **Summarize** what was produced and suggest the next step
|
|
|
|
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 six-phase, gated workflow. Each phase must satisfy its success criteria before advancing.
|
|
|
|
**Phase 1 — Discovery & Planning** *(solution-wide)*
|
|
|
|
- Discover all projects and classify migration eligibility
|
|
- Produce `Reports/MasterMigrationPlan.md` recording DDL artifact location and whether an external tool (e.g., `ora2pg`) was already used
|
|
|
|
**Phase 2 — Pre-Migration Planning & Risk Analysis** *(per project)*
|
|
|
|
- Identify the data-access layer (repositories, DAOs, service classes, SQL/procedure calls)
|
|
- Produce `Reports/{ProjectName}/OracleRiskAnalysis.md` — a stable analytical reference of Oracle/PostgreSQL behavioral differences found in the code
|
|
- Derive `Reports/{ProjectName}/MigrationChecklist.md` — a numbered, actionable checklist for Phase 5
|
|
|
|
**Phase 3 — Oracle Test Project Creation & Validation** *(per project)*
|
|
|
|
- Scaffold an Oracle-targeting xUnit test project and write integration tests
|
|
- Establish a passing Oracle baseline — a failing baseline means defects exist *before* migration starts
|
|
- Document any behavioral discrepancies as structured bug reports
|
|
|
|
**Phase 4 — Schema & DDL Migration** *(per project)*
|
|
|
|
- Skip if `MasterMigrationPlan.md` records an external tool already produced PostgreSQL DDL
|
|
- Migrate in dependency order: types/enums → tables/sequences → indexes/constraints → views → triggers → stored procedures (PL/SQL → PL/pgSQL)
|
|
- Output artifacts to `DDL/Postgres/{ProjectName}/`; user applies scripts and confirms clean apply
|
|
|
|
**Phase 5 — Code Migration** *(per project)*
|
|
|
|
- Copy the application project into a `.Postgres` sibling, add to the solution, and update namespace/assembly name
|
|
- Use the `migrating-oracle-to-postgres-data-access-code` skill to work through `MigrationChecklist.md` item by item
|
|
- Run `dotnet build` after each item; fix errors before moving on
|
|
- Cross-reference completed checklist against `OracleRiskAnalysis.md` to confirm every risk is addressed or deferred with justification
|
|
|
|
**Phase 6 — PostgreSQL Test Project Creation & Validation** *(per project)*
|
|
|
|
- Clone the Oracle test project into a `.Postgres`-namespaced test project targeting the Phase 5 application clone
|
|
- Migrate the test project, `dotnet build`-gating each change
|
|
- Iteratively fix failures reported by the user — stored procedure corrections are written back to `DDL/Postgres/{ProjectName}/`
|
|
- Oracle test project must remain unmodified throughout
|
|
|
|
## Prerequisites
|
|
|
|
- Visual Studio Code with GitHub Copilot
|
|
- .NET solution with Oracle dependencies to migrate
|
|
- Access to an Oracle instance (for baseline testing) and a PostgreSQL instance (for validation)
|
|
|
|
## Directory Structure
|
|
|
|
The agent expects and creates the following structure in your repository:
|
|
|
|
```
|
|
.github/
|
|
└── oracle-to-postgres-migration/
|
|
├── Reports/
|
|
│ ├── MasterMigrationPlan.md
|
|
│ └── {ProjectName}/
|
|
│ ├── OracleRiskAnalysis.md
|
|
│ ├── MigrationChecklist.md
|
|
│ ├── PostgresTestMigrationPlan.md
|
|
│ └── BUG_REPORT_*.md
|
|
└── DDL/
|
|
├── Oracle/ # Oracle DDL scripts (pre-migration)
|
|
└── Postgres/
|
|
└── {ProjectName}/ # PostgreSQL DDL scripts per project (post-migration)
|
|
```
|
|
|
|
## Usage
|
|
|
|
1. **Ask for Guidance**: Invoke the expert with a migration question or situation (e.g., *"How should I approach migrating my .NET solution to PostgreSQL?"* or *"What does Oracle do with empty strings that's different from PostgreSQL?"*)
|
|
2. **Learn & Plan**: The expert explains concepts, surfaces pitfall insights, and presents recommended workflow steps
|
|
3. **Choose Your Next Step**: Decide which task to tackle (master plan, risk analysis, testing, code migration, etc.)
|
|
4. **Confirm and Act**: Tell the expert to proceed, and it makes edits and runs commands directly
|
|
5. **Review & Continue**: Examine the results and ask for the next step
|
|
|
|
## Source
|
|
|
|
This plugin is part of [Awesome Copilot](https://github.com/github/awesome-copilot), a community-driven collection of GitHub Copilot extensions.
|
|
|
|
## License
|
|
|
|
MIT
|