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. Você usa o mssql-python driver para Python para se conectar ao seu banco de dados e executar operações básicas, como ler e gravar 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.

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

apk add libtool krb5-libs krb5-dev
pip install mssql-python

apt-get install -y libltdl7 libkrb5-3 libgssapi-krb5-2
pip install mssql-python

dnf install -y libtool-ltdl krb5-libs
pip install mssql-python

zypper install -y libltdl7 libkrb5-3 libgssapi-krb5-2
pip install mssql-python

zypper install -y libltdl7
pip install mssql-python

brew install openssl
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

Você pode usar a ferramenta de linha de comando PyPI para verificar se os pacotes pretendidos estão instalados.

Verifique a lista de pacotes instalados com pip list.
```
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_name>;Database=<database_name>;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_name>;UID=<username>;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.

Executar uma consulta

Use uma cadeia de caracteres de consulta SQL para executar uma consulta e analisar os resultados.

Crie uma variável para a cadeia de caracteres de consulta 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 essencialmente 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.

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 pedidos repetidos para iniciar sessão, inicie sessão uma vez através da CLI do Azure ao executar az login, e depois utilize ActiveDirectoryDefault, que reutiliza a credencial em cache.

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

Gerar um número de produto aleatório aqui garante que você possa executar esse exemplo várias vezes.

Crie uma string de instrução 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
```

Passos seguintes

Use estes artigos para continuar a construir:

Cadeias de ligação para adaptar o exemplo para SQL Server local, SQL do Azure, contentores e instâncias nomeadas.
Gestão de ligações para utilização de gestores de contexto, agrupamento e definições de ligação.
Resolução de problemas para diagnosticar autenticação, certificados e problemas de conectividade.

Cadeias de ligação

Comentários

Esta página foi útil?

Last updated on 2026-07-22