Skip to content

Commit 0193383

Browse files
kapilsamantgithub-actions[bot]Kapilsamant-ms
authored
Add ssma agent (#1654)
* chore: publish from staged * Add SSMA console Agent * fix: regenerate README files after build * fix: remove materialized plugin directories * sync: align plugins folder with staged branch * fix: regenerate README after plugin sync * fix: correct SSMA agent naming * fix: regenerate README files after build * refactor: agent implementation to skill * refactor: reduce skill token size --------- Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: Kapil Samant <kapilsamant@microsoft.com>
1 parent dd919ab commit 0193383

2 files changed

Lines changed: 153 additions & 0 deletions

File tree

‎docs/README.skills.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -333,6 +333,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-skills) for guidelines on how to
333333
| [spring-boot-testing](../skills/spring-boot-testing/SKILL.md)<br />`gh skills install github/awesome-copilot spring-boot-testing` | Expert Spring Boot 4 testing specialist that selects the best Spring Boot testing techniques for your situation with Junit 6 and AssertJ. | `references/assertj-basics.md`<br />`references/assertj-collections.md`<br />`references/context-caching.md`<br />`references/datajpatest.md`<br />`references/instancio.md`<br />`references/mockitobean.md`<br />`references/mockmvc-classic.md`<br />`references/mockmvc-tester.md`<br />`references/restclienttest.md`<br />`references/resttestclient.md`<br />`references/sb4-migration.md`<br />`references/test-slices-overview.md`<br />`references/testcontainers-jdbc.md`<br />`references/webmvctest.md` |
334334
| [sql-code-review](../skills/sql-code-review/SKILL.md)<br />`gh skills install github/awesome-copilot sql-code-review` | Universal SQL code review assistant that performs comprehensive security, maintainability, and code quality analysis across all SQL databases (MySQL, PostgreSQL, SQL Server, Oracle). Focuses on SQL injection prevention, access control, code standards, and anti-pattern detection. Complements SQL optimization prompt for complete development coverage. | None |
335335
| [sql-optimization](../skills/sql-optimization/SKILL.md)<br />`gh skills install github/awesome-copilot sql-optimization` | Universal SQL performance optimization assistant for comprehensive query tuning, indexing strategies, and database performance analysis across all SQL databases (MySQL, PostgreSQL, SQL Server, Oracle). Provides execution plan analysis, pagination optimization, batch operations, and performance monitoring guidance. | None |
336+
| [ssma-console](../skills/ssma-console/SKILL.md)<br />`gh skills install github/awesome-copilot ssma-console` | Use when: SSMA console operations — create project, generate assessment report, convert schema, migrate data, Oracle to SQL Server migration, schema conversion, data migration | None |
336337
| [structured-autonomy-generate](../skills/structured-autonomy-generate/SKILL.md)<br />`gh skills install github/awesome-copilot structured-autonomy-generate` | Structured Autonomy Implementation Generator Prompt | None |
337338
| [structured-autonomy-implement](../skills/structured-autonomy-implement/SKILL.md)<br />`gh skills install github/awesome-copilot structured-autonomy-implement` | Structured Autonomy Implementation Prompt | None |
338339
| [structured-autonomy-plan](../skills/structured-autonomy-plan/SKILL.md)<br />`gh skills install github/awesome-copilot structured-autonomy-plan` | Structured Autonomy Planning Prompt | None |

‎skills/ssma-console/SKILL.md‎

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
---
2+
name: ssma-console
3+
description: "Use when: SSMA console operations — create project, generate assessment report, convert schema, migrate data, Oracle to SQL Server migration, schema conversion, data migration"
4+
---
5+
6+
# SSMA Console — Oracle to SQL Server Migration
7+
8+
Generate XML configs and invoke `SSMAforOracleConsole.exe` directly — no external scripts or wrappers.
9+
10+
**Operations** (run in order for "full migration"):
11+
1. **create-project** — connect source & target, map schema
12+
2. **generate-report** — assessment report
13+
3. **migrate-schema** — convert & deploy schema
14+
4. **migrate-data** — convert, deploy, migrate data end-to-end
15+
16+
## Collect Inputs
17+
18+
Ask for missing parameters. Defaults in parentheses.
19+
20+
**Oracle**: Host (`localhost`), Port (`1521`), Instance *(required, service name)*, User, Password, Schema
21+
**SQL Server**: Server, Database, User, Password, Encrypt (`true`), Trust Server Certificate (`true`), Target Schema (`dbo`)
22+
**Project**: Name (`ssma-migration`), Folder (`.`), Type (`sql-server-2022` — also `2016`/`2017`/`2019`/`2025`/`sql-azure`), SSMA Path (`C:\Program Files\Microsoft SQL Server Migration Assistant for Oracle\bin\SSMAforOracleConsole.exe`)
23+
24+
## Generate XML Files
25+
26+
Resolve ALL `{PLACEHOLDER}` tokens before writing. Generate 3 files:
27+
28+
### `ssma-variables.xml`
29+
30+
```xml
31+
<?xml version="1.0" encoding="utf-8"?>
32+
<variables>
33+
<variable name="$WorkingFolder$" value="{PROJECT_FOLDER}" />
34+
<variable name="$ProjectType$" value="{PROJECT_TYPE}" />
35+
<variable name="$ProjectName$" value="{PROJECT_NAME}" />
36+
<variable-group name="OracleConnection">
37+
<variable name="$OracleHostName$" value="{ORACLE_HOST}" />
38+
<variable name="$OracleInstance$" value="{ORACLE_INSTANCE}" />
39+
<variable name="$OraclePort$" value="{ORACLE_PORT}" />
40+
<variable name="$OracleUserName$" value="{ORACLE_USER}" />
41+
<variable name="$OraclePassword$" value="{ORACLE_PASSWORD}" />
42+
<variable name="$OracleSchemaName$" value="{ORACLE_SCHEMA}" />
43+
</variable-group>
44+
<variable-group name="SQLServerConnection">
45+
<variable name="$SQLServerName$" value="{SQL_SERVER}" />
46+
<variable name="$SQLServerDb$" value="{SQL_DATABASE}" />
47+
<variable name="$SQLServerUsrID$" value="{SQL_USER}" />
48+
<variable name="$SQLServerPwd$" value="{SQL_PASSWORD}" />
49+
</variable-group>
50+
<variable-group name="ReportSettings">
51+
<variable name="$SummaryReportFile$" value="Reports\Assessment\AssessmentReport.xml" />
52+
<variable name="$ConversionReportFile$" value="Reports\Conversion\ConversionReport.xml" />
53+
<variable name="$ConversionReportFolder$" value="Reports\Conversion" />
54+
<variable name="$DataMigrationReportFile$" value="Reports\Migration\DataMigrationReport.xml" />
55+
<variable name="$SynchronizationReportFolder$" value="Reports\Synchronization" />
56+
</variable-group>
57+
</variables>
58+
```
59+
60+
### `ssma-servers.xml`
61+
62+
**CRITICAL**: Use `tns-name-mode` — `standard-mode` treats instance as SID and fails with ORA-12505.
63+
64+
```xml
65+
<?xml version="1.0" encoding="utf-8"?>
66+
<servers>
67+
<oracle name="source_oracle">
68+
<tns-name-mode>
69+
<connection-provider value="OracleClient" />
70+
<service-name value="(DESCRIPTION =(ADDRESS_LIST =(ADDRESS = (PROTOCOL = TCP)(HOST = $OracleHostName$)(PORT = $OraclePort$)))(CONNECT_DATA =(SERVICE_NAME = $OracleInstance$)))" />
71+
<user-id value="$OracleUserName$" />
72+
<password value="$OraclePassword$" />
73+
</tns-name-mode>
74+
</oracle>
75+
<sql-server name="target_sqlserver">
76+
<sql-server-authentication>
77+
<server value="$SQLServerName$" />
78+
<database value="$SQLServerDb$" />
79+
<user-id value="$SQLServerUsrID$" />
80+
<password value="$SQLServerPwd$" />
81+
<encrypt value="{ENCRYPT}" />
82+
<trust-server-certificate value="{TRUST_CERT}" />
83+
</sql-server-authentication>
84+
</sql-server>
85+
</servers>
86+
```
87+
88+
### Operation Script XML
89+
90+
Generate one script per operation. All scripts share this common `<config>` block (add `<object-overwrite action="overwrite" />` for migrate-schema/migrate-data, add `<data-migration-connection source-use-last-used="true" target-server="target_sqlserver" />` for migrate-data, use `every-5%` progress for schema/data ops):
91+
92+
```xml
93+
<config>
94+
<output-providers>
95+
<output-window suppress-messages="false" destination="stdout" />
96+
<upgrade-project action="yes" />
97+
<user-input-popup mode="continue" />
98+
<progress-reporting enable="true" report-messages="true" report-progress="every-10%" />
99+
<log-verbosity level="info" />
100+
</output-providers>
101+
</config>
102+
```
103+
104+
All scripts start with this **preamble** in `<script-commands>`:
105+
106+
```xml
107+
<create-new-project project-folder="$WorkingFolder$" project-name="$ProjectName$"
108+
overwrite-if-exists="true" project-type="$ProjectType$" />
109+
<connect-source-database server="source_oracle">
110+
<object-to-collect object-name="$OracleSchemaName$" />
111+
</connect-source-database>
112+
```
113+
114+
**CRITICAL**: Always include `<object-to-collect>` — without it, `map-schema` fails with "Source namespace was not found".
115+
116+
**Per-operation commands** (after preamble, before `<save-project />`):
117+
118+
| Operation | File | Commands after preamble |
119+
|-----------|------|------------------------|
120+
| create-project | `ssma-create-project.xml` | `connect-target-database` → `map-schema source-schema="$OracleSchemaName$" sql-server-schema="$SQLServerDb$.{TARGET_SCHEMA}"` |
121+
| generate-report | `ssma-assessment.xml` | `generate-assessment-report object-name="$OracleSchemaName$" object-type="Schemas" write-summary-report-to="$SummaryReportFile$" verbose="true" report-errors="true"` |
122+
| migrate-schema | `ssma-schema.xml` | `connect-target-database` → `map-schema` → `convert-schema` (to `$ConversionReportFile$`) → `synchronize-target object-name="$SQLServerDb$.{TARGET_SCHEMA}"` |
123+
| migrate-data | `ssma-data.xml` | Same as migrate-schema + `refresh-from-database` → `migrate-data object-name="$OracleSchemaName$.Tables" object-type="category"` (to `$DataMigrationReportFile$`) → `close-project` |
124+
125+
## Execute
126+
127+
Show resolved XML and command to user. Confirm before running.
128+
129+
```powershell
130+
New-Item -ItemType Directory -Force -Path "Reports\Assessment","Reports\Conversion","Reports\Migration","Reports\Synchronization","Logs" | Out-Null
131+
& "{SSMA_CONSOLE_PATH}" -s "{SCRIPT_XML}" -c "ssma-servers.xml" -v "ssma-variables.xml" -l "Logs\{OPERATION}.log"
132+
```
133+
134+
## Report Results
135+
136+
Check exit code (`0` = success), read logs and reports (`Reports\Assessment\`, `Reports\Conversion\`, `Reports\Migration\`), summarize findings.
137+
138+
## Constraints
139+
140+
- No external scripts — no `.ps1`, `.bat`, `.sh`
141+
- Confirm connection details before executing
142+
- Resolve all placeholders — no `{...}` in final XML
143+
- Create output directories before execution
144+
145+
## Known Pitfalls
146+
147+
| Symptom | Fix |
148+
|---------|-----|
149+
| `ORA-12505: SID not registered` | Use `tns-name-mode`, not `standard-mode` |
150+
| `Source namespace was not found` | Add `<object-to-collect>` to `connect-source-database` |
151+
| `not found in metabase` on `force-load` | Use `object-to-collect` instead — `force-load` is unreliable |
152+
| `SQL Server Agent is not running` | Warning only — BCP client-side migration still works |

0 commit comments

Comments
 (0)