Avvio rapido: Connettersi a un database SQL da un notebook di Jupyter

In questa guida introduttiva rapida, usare Jupyter Notebook in Visual Studio Code per ricavare rapidamente informazioni aziendali utili. Usa il mssql-python driver di Python per collegarti al tuo database SQL, leggere i dati e poi formattarli per usarli in email, report e presentazioni.

Il mssql-python driver non richiede dipendenze esterne nei computer Windows. Il driver installa tutti gli elementi necessari con un'unica pip installazione, consentendo di usare la versione più recente del driver per i nuovi script senza interrompere altri script che non è necessario aggiornare e testare.

Documentazione di mssql-python | mssql-python Codice sorgente | Pacchetto (PyPI) | Visual Studio Code

Prerequisiti

• Python 3.10 o versione successiva.

• Se Python non è già disponibile, installare il runtime Python e la gestione pacchetti pip da python.org.

• Non si vuole usare il proprio ambiente? Segui Container e lo sviluppo locale per creare un devcontainer riproducibile o un ambiente di Codespaces su GitHub.

• Visual Studio Code con le seguenti estensioni:

  • Estensione Python per Visual Studio Code

  • Estensione Jupyter per Visual Studio Code

• Interfaccia Command-Line di Azure per l'autenticazione senza password in macOS e Linux.

• Se non hai già uv, segui le istruzioni di installazione.

• Un database su SQL Server, un database SQL di Azure o un database SQL in Fabric con lo AdventureWorks2025 schema di esempio e una stringa di connessione valida.

Prerequisiti per installare il sistema operativo

Installare prerequisiti specifici del sistema operativo monouso. Gli utenti Windows possono saltare questo passaggio. Per dettagli completi sulla piattaforma, vedi Installa mssql-python.

apk add libtool krb5-libs krb5-dev libstdc++

apt-get install -y libltdl7 libkrb5-3 libgssapi-krb5-2

dnf install -y libtool-ltdl krb5-libs

zypper install -y libltdl7 libkrb5-3 libgssapi-krb5-2

zypper install -y libltdl7

brew install openssl

Creare un database SQL

Crea o collegati a un database SQL su una delle seguenti piattaforme:

Creare il progetto ed eseguire il codice

• Creare un nuovo progetto
• Aggiungere dipendenze
• Avviare Visual Studio Code
• Aggiornare pyproject.toml
• Salvare la stringa di connessione
• Creare un notebook di Jupyter
• Visualizzare i risultati in una tabella
• Visualizzare i risultati in un grafico

Creare un nuovo progetto

1. Apri un prompt dei comandi nella directory di sviluppo. Se non ne hai una, crea una nuova directory, come python o scripts. Evita le cartelle sul tuo OneDrive, poiché la sincronizzazione può interferire con la gestione del tuo ambiente virtuale.

2. Creare un nuovo progetto con uv.

   uv init jupyter-notebook-qs
   cd jupyter-notebook-qs
   

Aggiungere dipendenze

Nella stessa directory, installare i pacchetti mssql-python, python-dotenv, rich, pandas e matplotlib. Aggiungi quindi ipykernel e uv come dipendenze di sviluppo. VS Code richiede ipykernel per eseguire le celle del notebook e uv per gestire i pacchetti direttamente dalle celle del notebook.

uv add mssql-python python-dotenv rich pandas matplotlib
uv add --dev ipykernel
uv add --dev uv

Avviare Visual Studio Code

Nella stessa directory eseguire il comando seguente.

code .

Aggiornare pyproject.toml

1. Aprire il file pyproject.toml nell'editor. Questo file contiene i metadati del tuo progetto.

2. Aggiorna il valore description.

   description = "A quick example using the mssql-python driver and Jupyter Notebooks."
   

3. Salva e chiudi il file.

Salvare la stringa di connessione

1. Aprire il .gitignore file e aggiungere un'esclusione per .env i file. Il tuo file dovrebbe essere simile al seguente esempio.

   # Python-generated files
   __pycache__/
   *.py[oc]
   build/
   dist/
   wheels/
   *.egg-info
   
   # Virtual environments
   .venv
   
   # Connection strings and secrets
   .env
   

2. Salvare e chiudere .gitignore.

3. Nella directory corrente creare un nuovo file denominato .env.

4. All'interno del .env file aggiungere una voce per la stringa di connessione denominata SQL_CONNECTION_STRING. Sostituite i segnaposto con i valori effettivi.

   SQL_CONNECTION_STRING="Server=<server>;Database=<database>;Encrypt=yes;TrustServerCertificate=no;Authentication=ActiveDirectoryInteractive"
   

   La stringa di connessione dipende dal tipo di database SQL a cui ti stai collegando. Per database SQL di Azure o SQL database in Fabric, usa la stringa di connessione ODBC dalla scheda stringa di connessiones e regola il tipo di autenticazione per il tuo scenario. Per maggiori informazioni sulla sintassi delle stringa di connessione, vedi Connection strings for mssql-python.

   Suggerimento

   In macOS, entrambi ActiveDirectoryInteractive e ActiveDirectoryDefault funzionano per l'autenticazione di Microsoft Entra. ActiveDirectoryInteractive richiede di accedere ogni volta che si esegue lo script. Per evitare ripetuti prompt di accesso, accedi una volta con il comando interfaccia della riga di comando di Azureaz login e usa ActiveDirectoryDefault. ActiveDirectoryDefault Riutilizza la credenziale memorizzata.

Creare un notebook di Jupyter

1. Selezionare File, quindi Nuovo file e Jupyter Notebook dall'elenco. Verrà aperto un nuovo notebook.

2. Selezionare File, quindi Salva con nome e assegnare un nome al nuovo notebook.

3. Aggiungere le importazioni seguenti nella prima cella.

   from os import getenv
   from mssql_python import connect
   from dotenv import load_dotenv
   from rich.console import Console
   from rich.table import Table
   import pandas as pd
   import matplotlib.pyplot as plt
   

4. Usare il pulsante + Markdown nella parte superiore del notebook per aggiungere una nuova cella markdown.

5. Aggiungere il testo seguente alla nuova cella markdown.

   ## Define queries for use later
   

6. Selezionare il segno di spunta nella barra degli strumenti delle celle o usare i Ctrl+Enter tasti di scelta rapida o Shift+Enter per eseguire il rendering della cella markdown.

7. Usare il pulsante + Codice nella parte superiore del notebook per aggiungere una nuova cella di codice.

8. Aggiungere il codice seguente alla nuova cella di codice.

   SQL_QUERY_ORDERS_BY_CUSTOMER = """
   SELECT TOP 5
       c.CustomerID,
       c.CompanyName,
       COUNT(soh.SalesOrderID) AS OrderCount
   FROM SalesLT.Customer AS c
   LEFT OUTER JOIN SalesLT.SalesOrderHeader AS soh
       ON c.CustomerID = soh.CustomerID
   GROUP BY
       c.CustomerID,
       c.CompanyName
   ORDER BY OrderCount DESC;
   """
   
   SQL_QUERY_SPEND_BY_CATEGORY = """
   SELECT TOP 10
       pc.Name AS ProductCategory,
       SUM(sod.OrderQty * sod.UnitPrice) AS Spend
   FROM SalesLT.SalesOrderDetail AS sod
   INNER JOIN SalesLT.SalesOrderHeader AS soh
       ON sod.SalesOrderID = soh.SalesOrderID
   INNER JOIN SalesLT.Product AS p
       ON sod.ProductID = p.ProductID
   INNER JOIN SalesLT.ProductCategory AS pc
       ON p.ProductCategoryID = pc.ProductCategoryID
   GROUP BY pc.Name
   ORDER BY Spend;
   """
   

Visualizzare i risultati in una tabella

1. Usare il pulsante + Markdown nella parte superiore del notebook per aggiungere una nuova cella markdown.

2. Aggiungere il testo seguente alla nuova cella markdown.

   ## Print orders by customer and display in a table
   

3. Selezionare il segno di spunta nella barra degli strumenti delle celle o usare i Ctrl+Enter tasti di scelta rapida o Shift+Enter per eseguire il rendering della cella markdown.

4. Usare il pulsante + Codice nella parte superiore del notebook per aggiungere una nuova cella di codice.

5. Aggiungere il codice seguente alla nuova cella di codice.

   load_dotenv()
   with connect(getenv("SQL_CONNECTION_STRING")) as conn: # type: ignore
       with conn.cursor() as cursor:
           cursor.execute(SQL_QUERY_ORDERS_BY_CUSTOMER)
           if cursor:
               table = Table(title="Orders by Customer")
               # https://rich.readthedocs.io/en/stable/appendix/colors.html
               table.add_column("Customer ID", style="bright_blue", justify="center")
               table.add_column("Company Name", style="bright_white", justify="left")
               table.add_column("Order Count", style="bold green", justify="right")
   
               records = cursor.fetchall()
   
               for r in records:
                   table.add_row(f"{r.CustomerID}", f"{r.CompanyName}", f"{r.OrderCount}")
   
               Console().print(table)
   

6. Usare il pulsante Esegui tutto nella parte superiore del notebook per eseguire il notebook.

7. Selezionare il kernel jupyter-notebook-qs quando richiesto.

Visualizzare i risultati in un grafico

1. Rivedi l'output della cella precedente. Verrà visualizzata una tabella con tre colonne e cinque righe.

2. Usare il pulsante + Markdown nella parte superiore del notebook per aggiungere una nuova cella markdown.

3. Aggiungere il testo seguente alla nuova cella markdown.

   ## Display spend by category in a horizontal bar chart
   

4. Selezionare il segno di spunta nella barra degli strumenti delle celle o usare i Ctrl+Enter tasti di scelta rapida o Shift+Enter per eseguire il rendering della cella markdown.

5. Usare il pulsante + Codice nella parte superiore del notebook per aggiungere una nuova cella di codice.

6. Aggiungere il codice seguente alla nuova cella di codice.

   with connect(getenv("SQL_CONNECTION_STRING")) as conn: # type: ignore
       data = pd.read_sql_query(SQL_QUERY_SPEND_BY_CATEGORY, conn)
       # Set the style - use print(plt.style.available) to see all options
       plt.style.use('seaborn-v0_8-notebook')
       plt.barh(data['ProductCategory'], data['Spend'])
   

7. Utilizzare il pulsante Esegui cella o Ctrl+Alt+Enter per eseguire la cella.

8. Esaminare il grafico.

Contenuti correlati

• Compila le stringhe di connessione in modo programmativo
• Usa mssql-python con pandas
• Usa mssql-python con Apache Arrow