Tutorial: Cos'è la conversione dello schema da Oracle al server flessibile di Database di Azure per PostgreSQL

Questa esercitazione illustra come convertire gli schemi di database Oracle in Database di Azure per PostgreSQL usando l'estensione postgreSQL Visual Studio Code con Microsoft Foundry per generare ed esaminare le definizioni di PostgreSQL.

Illustra la connessione all'origine Oracle e alla destinazione Database di Azure per PostgreSQL, la configurazione di Microsoft Foundry, l'esecuzione della Migrazione guidata e l'analisi degli artefatti PostgreSQL generati. Prima di iniziare, assicurarsi di avere accesso alla rete e credenziali sia per i server che per una distribuzione di Microsoft Foundry.

Ecco cosa ci si può aspettare durante la conversione:

• Individuazione dello schema: lo strumento analizza gli oggetti dello schema Oracle.
• AI processing: Microsoft Foundry elabora e converte oggetti compatibili.
• Controlli scratch-database: lo strumento tenta la compilazione e i controlli statici disponibili. La convalida funzionale, dei dati e dell'applicazione rimane separata.
• Revisione dell'oggetto: usare Esplora oggetti di conversione per esaminare i risultati e perfezionare le definizioni di PostgreSQL generate.
• Generazione di output: gli oggetti convertiti correttamente vengono salvati come file PostgreSQL.

Prerequisiti

Questa sezione descrive i prerequisiti per l'uso della funzionalità di conversione dello schema da Oracle a Database di Azure per PostgreSQL in Visual Studio Code prima di avviare una conversione.

Requisiti di sistema

Supporto dei sistemi operativi

Requisiti di destinazione per Database di Azure per PostgreSQL

Requisiti del modello di intelligenza artificiale

È necessario uno dei componenti di intelligenza artificiale seguenti configurati:

Configurazione di distribuzione di Microsoft Foundry

In Microsoft Foundry creare una distribuzione che usa il modello gpt-5.2. Il nome della distribuzione è quello scelto al momento della creazione della distribuzione; non deve corrispondere al nome del modello.

L'endpoint è l'URL della risorsa Microsoft Foundry. Le risorse di Microsoft Foundry espongono diversi nomi host equivalenti; uno qualsiasi dei formati seguenti è valido:

• https://{your-resource}.services.ai.azure.com
• https://{your-resource}.openai.azure.com
• https://{your-resource}.cognitiveservices.azure.com

Sostituire {your-resource} con il nome della risorsa Microsoft Foundry, ad esempio oracletopg. Se è necessario chiamare direttamente un endpoint di inferenza, il percorso di anteprima attuale è /openai/responses?api-version=2025-04-01-preview.

Per altre informazioni sui formati degli endpoint e sulle route di inferenza, vedere Endpoints for Microsoft Foundry Models.

Privilegi di database necessari

Prima di eseguire la conversione dello schema, verificare l'accesso ai metadati di origine e le autorizzazioni del database temporaneo con gli amministratori del database. L'account Oracle deve accedere ai metadati dello schema e alle viste del dizionario, non ai dati delle righe dell'applicazione. L'account PostgreSQL deve essere in grado di eliminare e ricreare schemi corrispondenti e creare oggetti per la convalida. Usare un account dedicato, se possibile, e seguire il principio dei privilegi minimi.

Privilegi Oracle di origine

Per il database Oracle di origine sono necessari i privilegi minimi seguenti:

Privilegi dei database di scratch

Configurare il seguente accesso sul database creato da zero selezionato. A livello di database CREATE non concede l'autorizzazione per eliminare uno schema di proprietà di un altro ruolo.

Requisiti di rete

• Connettività in uscita: endpoint Microsoft Foundry.
• Connettività del database: sia Oracle di origine che il server flessibile del Database di Azure per PostgreSQL.
• Accesso HTTPS: Visual Studio Code Extensions Marketplace e servizi GitHub Copilot.
• Accesso al repository GitHub: https://github.com/microsoft/pgsql-tools/.

Oracle Instant Client (per la modalità client “thick”)

Lo strumento di conversione dello schema si connette a Oracle usando la modalità thin client per impostazione predefinita, che non richiede software aggiuntivo. Se l'ambiente richiede la modalità client pesante, installare Oracle Instant Client sul computer su cui è in esecuzione Visual Studio Code. Lo strumento legge la configurazione di sqlnet.ora e tnsnames.ora e passa automaticamente alla modalità thick quando un'impostazione lo richiede.

È possibile determinare se è necessaria la modalità client spessa controllando i file di configurazione di rete Oracle nell'ambiente di origine. Cercare i parametri seguenti nel sqlnet.ora file (in genere si trova in $ORACLE_HOME/network/admin/):

autenticazione di Microsoft Foundry

Configurare uno dei metodi di autenticazione seguenti per Microsoft Foundry:

Processo di migrazione

Questa sezione illustra il flusso di lavoro di conversione. Installare l'estensione, inizializzare un progetto, connettersi a Oracle, esaminare Discovery e configurare il database scratch e Microsoft Foundry. I tentativi di conversione eseguono la compilazione e i controlli statici disponibili nel database creato da zero. Esaminare e perfezionare l'output, distribuirlo in un database non di produzione separato e convalidarlo in modo indipendente prima dell'uso in produzione.

Passaggio 1: Installare l'estensione PostgreSQL Visual Studio Code

1. Apri Visual Studio Code.

2. Passare alla visualizzazione Estensioni (Ctrl+Shift+X).

3. Cercare PostgreSQL e installare l'estensione PostgreSQL pubblicata da Microsoft.

   1. Download del Marketplace

   

Passaggio 2: Creare una connessione per Database di Azure per PostgreSQL

1. Nel pannello dell'estensione PostgreSQL, creare una connessione all'istanza server flessibile del Database di Azure per PostgreSQL.

2. Immettere i dettagli della connessione (host, database, nome utente, password).

3. Testare e salvare la connessione.

   

Passaggio 3: Aprire una nuova area di lavoro

1. Creare una nuova cartella nel computer locale per il progetto di migrazione.

2. Aprire la cartella come nuova area di lavoro in Visual Studio Code.

   

Passaggio 4: Inizializzare un progetto di migrazione

1. Aprire l'estensione PostgreSQL.

2. Passare al pannello Migrazioni .

3. Selezionare Crea progetto di migrazione.

   

Passaggio 5: Configurare le impostazioni del progetto

1. Nella Procedura guidata di migrazione, inserire il nome del progetto.

2. Seleziona Avanti per continuare.

   

Passaggio 6: Configurare la connessione Oracle

1. Immettere i dettagli della connessione Oracle:

   • Nome host o nome del server.
   • Numero porta.
   • Nome del database o del servizio.
   • Nome utente e password.

   Lo strumento seleziona automaticamente la modalità client thin o thick dalle tue impostazioni sqlnet.ora e tnsnames.ora; l'interfaccia utente non offre un selettore manuale. La modalità sottile viene usata per impostazione predefinita. Se il tuo sqlnet.ora richiede la modalità thick, assicurati che Oracle Instant Client sia installato e che il relativo percorso sia incluso nella variabile di ambiente PATH prima di continuare. Per altre informazioni, vedere Oracle Instant Client.

2. Selezionare Carica schemi. Lo strumento verifica la connessione Oracle e, se ha esito positivo, elenca tutti gli schemi definiti dall'utente disponibili in Oracle.

3. Selezionare uno o più schemi da convertire in PostgreSQL.

4. Selezionare Avanti: Discovery.

   

Passaggio 7: Esaminare i risultati di Discovery

La funzione di individuazione mostra l'inventario di origine e l'ambito dell'estrazione pianificata. Nessun DDL viene estratto in questa fase. Per una spiegazione dei conteggi di riepilogo e dell'ambito, vedere Panoramica dell'individuazione nella conversione dello schema.

1. Attendere la conclusione di Individuazione.

2. In Autorizzazioni di origine, esaminare ciascun controllo, il suo scopo e il relativo risultato. Esaminare i controlli non riusciti con l'amministratore del database Oracle. Dopo aver risolto i problemi di autorizzazione, selezionare Aggiorna individuazione e rivedere i risultati aggiornati. Per le autorizzazioni necessarie, consultare Privilegi Oracle di origine.

3. Rivedere i conteggi riepilogativi di oggetti individuati, da estrarre, esclusi e oggetti non validi.

4. Espandere Tipi di oggetto supportati per esaminare i conteggi di oggetti Da estrarre, Esclusi e Non validi per tipo. Un tipo supportato può comunque avere oggetti esclusi; questi conteggi non sono risultati di conversione.

5. Espandere Tipi di oggetto non supportati per esaminare le categorie non supportate trovate nel contenuto di origine. Per informazioni dettagliate sul supporto e alternative di PostgreSQL, vedere Limitazioni di conversione dello schema.

6. In Schemi dipendenti, esaminare gli schemi non selezionati a cui si fa riferimento. Selezionare Mostra diagramma per visualizzare i riferimenti. I numeri sulle connessioni rappresentano riferimenti alle dipendenze, non il numero di oggetti da estrarre o convertire.

7. Consultare l'avviso separato sugli schemi di sistema Oracle menzionati che non vengono migrati. Non trattare questi riferimenti come schemi applicativi aggiuntivi selezionati per la conversione.

8. Se è necessario modificare la selezione dello schema, selezionare Indietro per tornare alla schermata Connessione a Oracle, aggiornare Schemi e selezionare di nuovo Avanti: Rilevamento. Esaminare l'ambito aggiornato prima di continuare.

9. Selezionare Ho esaminato gli oggetti, le esclusioni e gli schemi dipendenti.

10. Selezionare Avanti: Connessione PostgreSQL.

    

Passaggio 8: Configurare un database scratch di Database di Azure per PostgreSQL

Usare un database scratch vuoto o dedicato senza oggetti o dati da conservare. Per indicazioni sulla preparazione, vedere Preparare il database scratch.

1. Selezionare la connessione Database di Azure per PostgreSQL definita nell'estensione PostgreSQL.

2. Selezionare il database di destinazione dall'elenco a discesa.

3. Selezionare Verifica estensioni. Se viene visualizzato l'avviso Estensioni consigliate non installate , esaminare le estensioni mancanti. Seguire le indicazioni per la preparazione del database scratch per aggiungere le estensioni necessarie all'elenco di elementi consentiti del server e installarle nel database selezionato, quindi selezionare di nuovo Verifica estensioni . È possibile continuare nonostante l'avviso, ma gli oggetti che dipendono dalle estensioni mancanti potrebbero richiedere modifiche manuali.

   

4. Selezionare la casella di controllo che riconosce che gli schemi creati da zero corrispondenti agli schemi Oracle selezionati vengono rimossi e ricreati durante la conversione, eliminando i loro oggetti e dati esistenti.

5. Selezionare Avanti: Configurazione del modello di Microsoft Foundry.

Passaggio 9: Configurare il modello linguistico Microsoft Foundry

In Microsoft Foundry, allocare una quota di distribuzione maggiore di 1.000.000 token al minuto (TPM). L'esempio di distribuzione seguente è configurato per 2,3 milioni di TPM; la quota disponibile mostrata è specifica per tale ambiente.

Tornare alla procedura guidata di migrazione in Visual Studio Code per configurare la connessione al modello:

1. Immettere i dettagli di Microsoft Foundry:
   • URL dell'endpoint
   • Nome della distribuzione (nome assegnato alla distribuzione in Microsoft Foundry; il modello sottostante deve essere gpt-5.2).
2. Selezionare il metodo di autenticazione:
   • Chiave API: immettere la chiave API per la distribuzione di Microsoft Foundry.
   • Microsoft Entra ID: Accedi con l'estensione Account Azure. Lo strumento acquisisce automaticamente il token di autenticazione. Assicurarsi che l'identità connessa abbia il ruolo Foundry User (in precedenza Azure AI User) sulla risorsa Microsoft Foundry. Per altre informazioni, vedere Controllo degli accessi in base al ruolo per Microsoft Foundry.
3. Selezionare Test Microsoft Foundry Connection per verificare la configurazione.
4. Una volta stabilita la connessione, selezionare Crea progetto di migrazione.

Passaggio 10: Eseguire la conversione dello schema

1. Il sistema passa alla schermata principale della Procedura guidata di migrazione.

2. Selezionare Esegui migrazione per avviare il processo di conversione dello schema.

3. Monitorare lo stato di avanzamento della conversione nell'interfaccia Visual Studio Code.

4. Al termine della conversione, il progetto mostra che la conversione dello schema è stata completata e l'azione Rivedi il riepilogo della conversione.

   

Passaggio 11: Esaminare il report di conversione dello schema

1. Al termine della conversione dello schema, il report di conversione HTML viene aperto automaticamente.
2. Esaminare i risultati di individuazione, estrazione e conversione e le note a livello di oggetto.
3. Per indicazioni sull'interpretazione del report, vedere Visualizzare il report HTML per la conversione dello schema Oracle.

Passaggio 12: Esaminare e perfezionare gli oggetti convertiti

1. Dal progetto di migrazione completato, selezionare Rivedi il riepilogo della conversione.

   

2. Nella pagina Riepilogo conversione selezionare Esplora oggetti di conversione.

   

3. Selezionare un oggetto per confrontare le definizioni Oracle e PostgreSQL e leggere le note di conversione.

   

4. Usare Ask per spiegare la conversione e le relative dipendenze oppure Fix per aprire un prompt di Copilot e apportare modifiche al file PostgreSQL.

5. Esamina le modifiche e verifica che lo SQL di distribuzione includa le correzioni che intendi distribuire. Non presupporre che la modifica di un file per oggetto aggiorni il deploy.sql generato.

Per i passaggi di filtro, confronto e compilazione manuale, vedere Esaminare gli oggetti convertiti in Conversion Esplora oggetti.

Passaggio 13: Preparare la distribuzione con Setup Experience

Il flusso di lavoro di conversione genera automaticamente i file di installazione al termine. L'apertura delle istruzioni di installazione non avvia una distribuzione.

1. Nel progetto di migrazione completato, seleziona Rivedi il riepilogo della conversione.
2. Nella pagina Riepilogo conversione selezionare Istruzione di configurazione. Questa azione diventa disponibile quando i file di installazione sono pronti.
3. Esaminare il file generato setup_instructions.md , che viene aperto nell'editor. Visual Studio Code rivela anche la cartella di installazione in Explorer.
4. Seguire Distribuire schemi convertiti con Esperienza di installazione per preparare un database di destinazione separato non di produzione, eseguire controlli di idoneità, distribuire gli schemi convertiti ed esaminare i risultati della distribuzione.

Passaggio 14: Convalidare lo schema distribuito prima dell'uso in produzione

Usare il database non di produzione implementato nel passaggio precedente per la convalida funzionale, dei dati e dell'applicazione, e non il database scratch di conversione.

Se si modifica un oggetto dopo la distribuzione, applicare manualmente la correzione:

1. Connettere l'editor SQL al server PostgreSQL non di produzione e al database in cui è distribuito lo schema convertito. Confermare il database attivo dell'editor.
2. Esaminare i riferimenti allo schema e selezionare l'istruzione o le istruzioni complete che si intende eseguire.
3. Selezionare il pulsante Play per eseguire solo le istruzioni selezionate. Esaminare l'output dell'esecuzione e risolvere gli errori prima di continuare.
4. Verificare che i file oggetto e SQL di distribuzione contengano le correzioni testate prima della distribuzione di produzione. L'aggiornamento di un file, l'aggiornamento di un oggetto distribuito e l'aggiornamento di deploy.sql sono azioni separate.

Validare in modo indipendente lo schema distribuito nell'ambiente di destinazione con dati di test rappresentativi e carichi di lavoro dell'applicazione. Verificare le dipendenze, i vincoli, la logica di business e i set di risultati rispetto all'origine dati Oracle e ripetere il test dopo le correzioni. Esaminare gli oggetti che non sono stati convertiti o distribuiti, anziché testare solo le conversioni riuscite.

Per altre informazioni sull'estensione Visual Studio Code, visitare l'estensione PostgreSQL per Visual Studio Code e Cursor.

Contenuti correlati

• Che cos'è la conversione dello schema da Oracle ad Database di Azure per PostgreSQL Flexible Server?
• Esaminare gli oggetti convertiti in Conversion Esplora oggetti
• Distribuire schemi convertiti con Esperienza di installazione
• Limitazioni della conversione dello schema da Oracle ad Database di Azure per PostgreSQL - server flessibile