Stringhe di connessione per mssql-python

Il driver mssql-python supporta le seguenti parole chiave di stringa di connessione quando si connette a SQL Server, database SQL di Azure, Istanza gestita di SQL di Azure e database SQL in Microsoft Fabric.

Sintassi della stringa di connessione

Le stringhe di connessione utilizzano coppie chiave-valore separate da punti e virgola:

keyword1=value1;keyword2=value2;...

Valori di avvolgimento che contengono caratteri speciali (punti e virgola, segni uguali o parentesi a riccio) tra le parentesi a riccio:

PWD={my;complex=password}

Per includere una parentesi di chiusura letterale in un valore, si usano due parentesi di chiusura (}}):

PWD={password}}with}}brace}

Esempi di connessione di base

I seguenti esempi mostrano come connettersi utilizzando diversi metodi di autenticazione. Per applicazioni di produzione, utilizza l'autenticazione Microsoft Entra ogni volta che è possibile. Elimina le password dal codice e dalle stringhe di connessione.

SQL Server con autenticazione Microsoft Entra (consigliato)

Questo esempio utilizza ActiveDirectoryDefault, che prova più fonti di credenziali (interfaccia della riga di comando di Azure, variabili di ambiente, identità gestita) in ordine. Nessuna password è memorizzata nel codice:

import mssql_python

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;Database=<database>;Authentication=ActiveDirectoryDefault;Encrypt=yes;"
)

SQL Server con autenticazione SQL

Usa l'autenticazione SQL solo per lo sviluppo locale su un'istanza di SQL Server che controlli. Le credenziali sono incorporate nella stringa di connessione, quindi conservale in variabili di ambiente o in un .env file invece che nel codice sorgente:

conn = mssql_python.connect(
    "Server=<server>;"
    "Database=<database>;"
    "UID=<login>;"
    "PWD=<password>;"
    "Encrypt=yes;"
)

Azure SQL con autenticazione Microsoft Entra

La stringa di connessione per database SQL di Azure è la stessa di SQL Server. ActiveDirectoryDefaultfunziona tra sviluppo locale, container e ambienti ospitati su Azure senza modifiche al codice:

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryDefault;"
    "Encrypt=yes;"
)

Usa argomenti per parole chiave

Puoi passare i parametri di connessione come argomenti chiave invece o in aggiunta a una stringa di connessione. Gli argomenti per parole chiave evitano le insidie di fuga dell'assemblaggio della stringa di connessione. Le password con caratteri speciali come @, ;, {, o } non necessitano di wrapping a corvette quando vengono passate come argomenti per parole chiave:

conn = mssql_python.connect(
    server="<server>.database.windows.net",
    database="<database>",
    authentication="ActiveDirectoryDefault",
    encrypt="yes"
)

Confronta con l'assembly della stringa di connessione, dove una password contenente @ deve essere avvolta:

# Connection string requires escaping
conn = mssql_python.connect("Server=srv;UID=user;PWD={p@ss;word};")

# Keyword arguments - no escaping needed
conn = mssql_python.connect(server="srv", uid="user", pwd="p@ss;word")

Il driver unisce gli argomenti delle parole chiave nella stringa di connessione dopo la normalizzazione. Se un argomento di parola chiave corrisponde a un parametro già presente nella stringa di connessione, l'argomento della parola chiave ha la precedenza e sovrascrive il valore della stringa di connessione:

# The keyword argument database="production" overrides Database=dev in the connection string
conn = mssql_python.connect(
    "Server=<server>.database.windows.net;Database=<database>;Encrypt=yes;",
    database="production",
    authentication="ActiveDirectoryDefault"
)
# Connects to "production", not "dev"

Il seguente esempio combina una stringa di connessione con argomenti di parola chiave:

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;Database=<database>;",
    authentication="ActiveDirectoryDefault",
    encrypt="yes"
)

Parole chiave per le stringhe di connessione

Server e database

Specifica l'istanza SQL Server di destinazione e il database per la connessione.

Authentication

Fornire credenziali per l'autenticazione SQL o specificare una modalità di autenticazione Microsoft Entra. Per le opzioni senza password, vedi modalità di autenticazione Microsoft Entra.

Crittografia e sicurezza

Tutte le connessioni vengono usate Encrypt=yes di default. Per la maggior parte delle applicazioni, il valore predefinito è sufficiente. Usa strict solo quando la tua istanza di SQL Server supporta TDS 8.0 e richiedi TLS 1.3. Da utilizzare TrustServerCertificate=yes solo in ambienti di sviluppo con certificati autofirmati.

Disponibilità elevata e failover

Queste parole chiave si applicano ai gruppi di disponibilità sempre attivo. Impostato ApplicationIntent=ReadOnly per instradare carichi di lavoro con grande lettura (report, analisi) verso repliche secondarie, riducendo il carico sul primario. Imposta MultiSubnetFailover=yes quando il tuo gruppo di disponibilità copre più subreti.

Prestazioni e rete

I valori predefiniti funzionano per la maggior parte delle applicazioni. Aumenta PacketSize (fino a 32767) per trasferimenti dati in massa. Configura KeepAlive se le connessioni attraversano firewall o bilanciatori di carico che interrompono sessioni TCP inattive.

Parole chiave riservate

Modalità di autenticazione Microsoft Entra

La Authentication parola chiave supporta i seguenti valori. Scegli la modalità che si adatta al tuo dispiegamento:

Per la configurazione riproducibile di Docker, devcontainer e ambienti CI, vedi Container e sviluppo locale. Quell'articolo centralizza la selezione runtime di Python e mostra come utilizzare immagini in dig pinned in ambienti condivisi.

Esempio: DefaultAzureCredential

ActiveDirectoryDefaultmappa alla catena di identità DefaultAzureCredential di Azure. Prova prima il token interfaccia della riga di comando di Azure durante lo sviluppo locale, poi l'identità gestita quando viene distribuito su Azure:

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryDefault;"
    "Encrypt=yes;"
)

Esempio: Flusso di codice del dispositivo

Usa il flusso di codice del dispositivo quando si esegue in ambienti senza browser, come sessioni SSH o container Docker. Il driver mostra un URL e un codice da inserire su un dispositivo separato:

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryDeviceCode;"
    "Encrypt=yes;"
)
# Follow the prompt to authenticate at https://microsoft.com/devicelogin

Esempio: Principio di servizio

L'autenticazione del principale servizio utilizza un'identità di applicazione registrata con un ID client e un segreto. Usa questo approccio per pipeline CI/CD e servizi in background che funzionano senza interazione dell'utente:

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryServicePrincipal;"
    "UID=<client-id>;"
    "PWD=<client-secret>;"
    "Encrypt=yes;"
)

Per registrare l'applicazione e concederle l'accesso al database, consulta Microsoft Entra service principals con Azure SQL. Per l'installazione completa in mssql-python, vedi Autenticazione del principale del servizio.

Timeout della connessione

Imposta il timeout della connessione usando il parametro timeout . Usa un timeout per evitare che la tua applicazione rimanga bloccata indefinitamente quando il server non è raggiungibile:

# 30-second connection timeout
conn = mssql_python.connect(connection_string, timeout=30)

Puoi anche modificare il timeout su una connessione esistente:

conn.timeout = 60

Modalità autocommit

Di default, autocommit è False, che richiede chiamate esplicite commit() . Abilita l'autocommit per le istruzioni DDL o le query di sola lettura che non richiedono il controllo delle transazioni:

# Via parameter
conn = mssql_python.connect(connection_string, autocommit=True)

# Or after connection
conn.setautocommit(True)

Attributi di connessione

Imposta gli attributi della connessione ODBC prima che la connessione venga stabilita usando attrs_before:

import mssql_python

conn = mssql_python.connect(
    connection_string,
    attrs_before={
        mssql_python.SQL_ATTR_LOGIN_TIMEOUT: 30,
        mssql_python.SQL_ATTR_CONNECTION_TIMEOUT: 60,
    }
)

Costruzione di stringa di connessione programmatica

Per prevenire l'iniezione di stringa di connessione, non usare concatenazione di stringhe o f-strings con input dell'utente. Usa invece argomenti chiave o variabili ambientali. Per altri pattern di costruzione inclusi file di configurazione JSON/YAML, Azure Key Vault e una classe builder, vedi Build strings connection programically.

import os

conn = mssql_python.connect(
    server=os.environ["DB_SERVER"],
    database=os.environ["DB_NAME"],
    authentication=os.environ.get("DB_AUTH", "ActiveDirectoryDefault"),
    encrypt="yes"
)

Validazione della stringa di connessione

Il driver valida le stringhe di connessione e aumenta ConnectionStringParseError le rilanci per parole chiave sconosciute o con errori di scrittura:

try:
    conn = mssql_python.connect("Servr=localhost;")  # Typo
except mssql_python.ConnectionStringParseError as e:
    print(f"Invalid connection string: {e}")
    # Output: Unknown keyword 'Servr'

Contenuti correlati

• Compila le stringhe di connessione in modo programmativo
• Installa mssql-python
• Autenticazione Microsoft Entra
• Pool di connessioni
• Gestione delle connessioni