Oracle to SQL Server Conversion Toolkit

Overview

This repository contains a reference implementation of a tooling suite that assists with migrating Oracle database artifacts to Microsoft SQL Server. It centralizes specifications, conversion logic, validation routines, and documentation that support the broader migration program described in OracleToSqlServerConversionSpec.md.

Key Capabilities

• Comprehensive specification that defines conversion requirements, architecture decisions, roadmap, and success metrics.
• Python package (ora2mssql) providing configuration loading, conversion orchestration, plugin discovery, validation, and logging utilities.
• Documentation tailored for both human operators and AI collaborators to ensure consistent execution practices.
• Automated tests validating the core data type mapping, function translation, and validation behavior.
• Schema prefixing support for organizing converted objects in SQL Server.
• C4 architecture documentation for understanding the system design.
• Automated diagram rendering for better visualization.

Repository Layout

.
├── OracleToSqlServerConversionSpec.md  # End-to-end program specification
├── README.md                          # Project overview and usage guidance
├── TASKS.md                           # Work breakdown structure and status tracking
├── diagrams/                          # Rendered architecture diagrams
│   ├── README.md                      # Diagrams folder documentation
│   ├── *.png                          # Rendered diagram images
│   └── *.mmd                          # Mermaid source files
├── docs/                              # Human and AI documentation assets
│   ├── C4_Architecture.md             # C4 architecture documentation summary
│   ├── C4_Context.md                  # C4 context diagram
│   ├── C4_Container.md                # C4 container diagram
│   ├── C4_Component.md                # C4 component diagram
│   ├── C4_Deployment.md               # C4 deployment diagram
│   ├── C4_Levels.md                   # C4 model levels explanation
│   ├── C4_Summary.md                  # Summary of all C4 documentation
│   ├── C4_KeyComponents.md            # Key components visualization
│   ├── C4_Navigation.md               # Navigation for all C4 documentation
│   ├── Beautiful_C4_Viewer.md         # Beautiful C4 viewer
│   ├── Enhanced_C4_Viewer.md          # Enhanced C4 viewer
│   ├── C4_Dashboard.md                # C4 dashboard (Recommended)
│   ├── diagram_gallery.html           # Complete diagram gallery
│   ├── index.html                     # Main documentation dashboard
│   ├── style.css                      # CSS styling for documentation
│   ├── README_C4.md                   # C4 documentation README
│   ├── HumanOperatorGuide.md          # Guide for human operators
│   ├── AIContributorGuide.md          # Guide for AI contributors
│   ├── DIAGRAM_RENDERING_GUIDE.md     # Guide for rendering diagrams
│   ├── render_diagrams.py             # Python script for diagram rendering
│   ├── render_diagrams.bat            # Windows batch script
│   ├── render_diagrams.sh             # Linux/Mac shell script
│   ├── add_navigation.py              # Script to add navigation headers
│   └── nav_header.html                # Navigation header template
├── src/ora2mssql/                     # Python conversion toolkit implementation
├── tests/                             # Pytest-based automated tests
├── start_docs.bat                     # Script to start documentation server
└── SUCCESSOR_DIAGRAM_PROMPT.md        # Guide for future maintainers

Getting Started

1. Set up the environment

   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   pip install -e .[test]

2. Run the automated test suite

   pytest

3. Explore the documentation
   • docs/HumanOperatorGuide.md
   • docs/AIContributorGuide.md
   • docs/C4_Navigation.md (Start here for C4 architecture overview)
   • docs/C4_Dashboard.md (Recommended beautiful C4 viewer)
   • OracleToSqlServerConversionSpec.md

Viewing Documentation with Rendered Diagrams

To view the documentation with rendered diagrams:

1. Open HTML Dashboard:

   • Open docs/index.html directly in your web browser
   • Open docs/diagram_gallery.html to see all diagrams in one place

2. Start Local HTTP Server (Recommended):

   # Double-click start_docs.bat or run:
   python -m http.server 8000
   # Then open http://localhost:8000/docs/index.html in your browser

3. View Individual Documentation Files:

   • All Markdown files in the docs/ folder include CSS styling and navigation headers

Rendering Architecture Diagrams

The documentation includes Mermaid diagrams that can be rendered as images for better visualization:

For Windows:

docs\render_diagrams.bat

For Linux/Mac:

docs/render_diagrams.sh

Direct Python execution:

python docs/render_diagrams.py

See Diagram Rendering Guide for more details.

Running Conversions

The CLI accepts a mix of individual files and directories:

ora2mssql path/to/views.sql path/to/procedures --output converted_artifacts

• When a directory is provided, all *.sql files under it are discovered recursively.
• Output filenames mirror the relative path of each artifact (e.g., procedures/order/process.sql → procedures_order_process.sql).
• scorecard.json is emitted alongside the converted SQL to summarize diagnostics and confidence.

Schema Prefixing

You can add a schema prefix to all converted objects using the --schema-prefix option:

ora2mssql path/to/views.sql --output converted_artifacts --schema-prefix myschema

This will prefix all table names, view names, and other database objects with the specified schema.

Configuration

The tool supports JSON configuration files that can be specified with the --config option:

ora2mssql path/to/views.sql --output converted_artifacts --config myconfig.json

Configuration options include:

• schema_prefix: Default schema prefix for objects
• environment: Environment label for tracking
• confidence_threshold: Minimum confidence level for conversions
• plugin_paths: Paths to custom plugin modules
• data_type_defaults: Default data type mappings
• feature_flags: Feature toggles for experimental functionality

Example configuration file:

{
  "schema_prefix": "myschema",
  "environment": "dev",
  "confidence_threshold": 0.8,
  "plugin_paths": ["my.custom.plugin"],
  "data_type_defaults": {
    "NUMBER": {"precision": 12, "scale": 4}
  },
  "feature_flags": {
    "emit_try_catch": true
  }
}

Contributing

Please review the repository-specific guidance in AGENTS.md prior to making changes. At a minimum:

• Maintain alignment with the specification and documentation.
• Add or update tests alongside code changes.
• Run pytest locally before submitting a pull request.