Guia de início rápido: conecte-se com o driver mssql-python para Python

Neste início rápido, você conecta um script Python a um banco de dados que você criou e carregou com dados de exemplo. Utiliza o mssql-python driver do Python para se ligar à sua base de dados e realizar operações básicas, como ler e escrever dados.

O mssql-python driver não requer nenhuma dependência externa em máquinas Windows. O driver instala tudo o que precisa com uma única pip instalação, permitindo que você use a versão mais recente do driver para novos scripts sem quebrar outros scripts que você não tem tempo para atualizar e testar.

Use o exemplo da autenticação SQL local neste artigo apenas para desenvolvimento local contra uma instância do SQL Server que controla. Para Base de Dados SQL do Azure, base de dados SQL em Fabric, ambientes de desenvolvimento partilhados, CI e implementações em produção, comece com autenticação Microsoft Entra ou outro fluxo sem palavra-passe.

Documentação | Código-fonte | Pacote (PyPI) | Código Visual Studio

Pré-requisitos

Python 3.10 ou posterior.
Se ainda não tens o Python, instala o runtime do Python e o gestor de pacotes pip a partir de python.org.
Não quer usar o seu próprio ambiente? Consulte Container and local development para criar um ambiente devcontainer reproduzível ou um ambiente do GitHub Codespaces.
(Opcional) Azure Command-Line Interface (CLI).

Crie ou ligue-se a uma base de dados no SQL Server, Base de Dados SQL do Azure ou base de dados SQL no Fabric. Use os passos seguintes para configurar uma base de dados com o AdventureWorks2025 esquema de exemplo e guarde a cadeia de ligação para mais tarde.

Criar uma base de dados SQL

Criar ou ligar-se a uma base de dados SQL numa das seguintes plataformas:

Criar um banco de dados SQL em minutos usando o portal do Azure

Configuração

Siga estas etapas para configurar seu ambiente de desenvolvimento para desenvolver um aplicativo usando o mssql-python driver Python.

Observação

Este controlador utiliza o protocolo Tabular Data Stream (TDS ). O SQL Server, a base de dados SQL no Fabric e o Base de Dados SQL do Azure ativam o TDS por defeito, por isso não é necessária qualquer configuração adicional.

Pré-requisitos para instalar o sistema operativo

Instale pré-requisitos que devem ser instalados uma única vez específicos do sistema operacional. Os utilizadores do Windows podem saltar este passo. Para detalhes completos da plataforma, consulte Instalar 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

Instalar o pacote mssql-python

Obtenha o pacote mssql-python do PyPI.

Abra um prompt de comando em um diretório vazio.
Instale o pacote mssql-python.
```
pip install mssql-python
```

Instale o pacote python-dotenv

Obtenha o pacote python-dotenv do PyPI.

No mesmo diretório, instale o python-dotenv pacote.

pip install python-dotenv

Verifique os pacotes instalados

Use pip list para verificar se os pacotes que pretende instalar estão instalados.

pip list

Criar um novo ficheiro

Crie um novo arquivo chamado app.py.

Adicione um módulo docstring.

"""
Connects to a SQL database using mssql-python
"""

Importar pacotes, incluindo mssql-python.

from os import getenv
from dotenv import load_dotenv
from mssql_python import connect

Use a mssql-python.connect função para se conectar a um banco de dados SQL.
```
load_dotenv()
conn = connect(getenv("SQL_CONNECTION_STRING"))
```
No diretório atual, crie um novo arquivo chamado .env.
Dentro do .env arquivo, adicione uma entrada para sua cadeia de conexão chamada SQL_CONNECTION_STRING. Utilize um dos exemplos seguintes e substitua os marcadores de posição pelos seus valores reais.

Para Base de Dados SQL do Azure ou SQL Database no Fabric, comece com a autenticação do Microsoft Entra:
```
SQL_CONNECTION_STRING="Server=<server>;Database=<database>;Encrypt=yes;TrustServerCertificate=no;Authentication=ActiveDirectoryInteractive"
```
Para o SQL Server local durante o desenvolvimento, comece pela autenticação SQL:
```
SQL_CONNECTION_STRING="Server=localhost,1433;Database=<database>;UID=<user_id>;PWD=<password>;Encrypt=yes;TrustServerCertificate=yes"
```
Atenção

Trate .env como uma conveniência de desenvolvimento local, não como um mecanismo de implementação. Nunca o envie para o repositório, nunca reutilize este exemplo de autenticação SQL em ambientes partilhados ou de produção e mantenha a validação do certificado ativada fora do desenvolvimento local.

Use strings de Conexão para adaptar a amostra a instâncias nomeadas, contentores ou definições avançadas. Se estiver a ligar-se ao Base de Dados SQL do Azure ou à base de dados SQL no Fabric, use a autenticação Microsoft Entra para opções de login interativo e sem palavra-passe. Para orientações mais amplas sobre segredos e certificados, consulte as melhores práticas de segurança.

Sugestão

No macOS, tanto ActiveDirectoryInteractive como ActiveDirectoryDefault funcionam para a autenticação do Microsoft Entra. ActiveDirectoryInteractive Solicita-te para iniciar sessão sempre que executas o script. Para evitar repetidos prompts de início de sessão, inicie sessão uma vez com o comando CLI do Azureaz login e use ActiveDirectoryDefault. ActiveDirectoryDefault Reutiliza a credencial em cache.

Executar uma consulta

Use uma string de consulta Transact-SQL (T-SQL) para executar uma consulta e analisar os resultados.

Crie uma variável para a cadeia de consulta T-SQL.

SQL_QUERY = """
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;
"""

Use cursor.execute para recuperar um conjunto de resultados de uma consulta no banco de dados.
```
cursor = conn.cursor()
cursor.execute(SQL_QUERY)
```
Observação

Esta função aceita qualquer consulta e devolve um conjunto de resultados. Para iterar sobre o conjunto de resultados, use cursor.fetchone().

Use cursor.fetchall com um for loop para obter todos os registros do banco de dados. Depois, imprime os registos.

records = cursor.fetchall()
for r in records:
    print(f"{r.CustomerID}\t{r.OrderCount}\t{r.CompanyName}")

Salve o app.py arquivo.

Abra um terminal e teste o aplicativo.

python app.py

Aqui está a saída esperada.

29485   1       Professional Sales and Service
29531   1       Remarkable Bike Store
29546   1       Bulk Discount Store
29568   1       Coalition Bike Company
29584   1       Futuristic Bikes

Inserir uma linha como transação

Executa uma INSERT instrução de forma segura e passa os parâmetros. Passar parâmetros como valores protege seu aplicativo contra ataques de injeção de SQL .

Adicione uma importação para randrange da biblioteca random no topo do app.py.
```
from random import randrange
```
No final de app.py, adicione código para gerar um número de produto aleatório.
```
productNumber = randrange(1000)
```
Sugestão

Um número aleatório de produto reduz a probabilidade de um erro de chave duplicado quando se executa esta amostra mais do que uma vez.

Crie uma cadeia de caracteres de instrução T-SQL.

SQL_STATEMENT = """
INSERT SalesLT.Product (
    Name,
    ProductNumber,
    StandardCost,
    ListPrice,
    SellStartDate
)
OUTPUT INSERTED.ProductID
VALUES (%(name)s, %(product_number)s, %(standard_cost)s, %(list_price)s, CURRENT_TIMESTAMP)
"""

Execute a instrução usando cursor.execute.

cursor.execute(
    SQL_STATEMENT,
    {
        'name': f'Example Product {productNumber}',
        'product_number': f'EXAMPLE-{productNumber}',
        'standard_cost': 100,
        'list_price': 200
    }
)

Buscar o único resultado usando cursor.fetchone, imprimir o identificador exclusivo do resultado e, em seguida, confirmar a operação como uma transação usando connection.commit.
```
result = cursor.fetchone()
print(f"Inserted Product ID : {result.ProductID}")
conn.commit()
```
Sugestão

Opcionalmente, você pode usar connection.rollback para reverter a transação.
Feche o cursor e a conexão usando cursor.close e connection.close.
```
cursor.close()
conn.close()
```
Salve o app.py arquivo e teste o aplicativo novamente.
```
python app.py
```
Aqui está a saída esperada.
```
Inserted Product ID : 1001
```

Comentários

Esta página foi útil?

Última atualização a 2026-10-19