Início Rápido: Conectar-se com o driver mssql-python para Python

Neste início rápido, você conecta um script Python a um banco de dados criado e carregado com dados de exemplo. Use o mssql-python driver do Python para se conectar ao 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 computadores 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 você controla. Para Banco de Dados SQL do Azure, SQL database em Fabric, ambientes de desenvolvimento compartilhados, CI e implantações em produção, comece com autenticação Microsoft Entra ou outro fluxo sem senha.

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

Pré-requisitos

Crie ou conecte-se a um banco de dados no SQL Server, Banco de Dados SQL do Azure ou banco de dados SQL no Fabric. Use os passos a seguir para configurar um banco de dados com o AdventureWorks2025 esquema de exemplo e mantenha a cadeia de conexão para depois.

Criar um Banco de Dados SQL

Crie ou conecte-se a um banco de dados SQL em uma das seguintes plataformas:

Configuração

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

Observação

Esse driver utiliza o protocolo Tabular Data Stream (TDS ). SQL Server, banco de dados SQL no Fabric e Banco de Dados SQL do Azure ativam o TDS por padrão, então não é necessária nenhuma configuração extra.

Instalar o pacote mssql-python

Obtenha o mssql-python pacote do PyPI.

  1. Abra um prompt de comando em um diretório vazio.

  2. Instale o pacote mssql-python.

    pip install mssql-python

Instale o pacote python-dotenv

Obtenha o pacote python-dotenv do PyPI.

  1. 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.

  1. Verifique a lista de pacotes instalados com pip list.

    pip list

Executar o código

Criar um novo arquivo

  1. Crie um arquivo chamado app.py.

  2. Adicione um módulo docstring.

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

  3. Importar pacotes, incluindo mssql-python.

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

  4. Use a função mssql-python.connect para se conectar a um banco de dados SQL.

    load_dotenv()
conn = connect(getenv("SQL_CONNECTION_STRING"))

  5. No diretório atual, crie um novo arquivo chamado .env.

  6. No arquivo .env, adicione uma entrada para sua cadeia de conexão chamada SQL_CONNECTION_STRING. Use um dos exemplos a seguir e substitua os marcadores de lugar pelos seus valores reais.

    Para o Banco de Dados SQL do Azure ou o SQL database no Fabric, comece usando a autenticação 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"

    Cuidado

    Trate .env como uma conveniência de desenvolvimento local, não como um mecanismo de implantação. Nunca faça um commit, nunca reutilize esse exemplo de autenticação SQL em ambientes compartilhados ou de produção, e mantenha a validação de certificados ativada fora do desenvolvimento local.

    Use strings de conexão para adaptar o exemplo para instâncias nomeadas, contêineres ou configurações avançadas. Se você estiver se conectando ao Banco de Dados SQL do Azure ou ao banco de dados SQL no Fabric, use autenticação Microsoft Entra para opções de entrada interativa e sem senha. Para orientações mais amplas sobre segredos e certificados, veja 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.

  1. 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;
"""

  2. Use cursor.execute para recuperar um conjunto de resultados de uma consulta em relação ao banco de dados.

    cursor = conn.cursor()
cursor.execute(SQL_QUERY)

    Observação

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

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

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

  4. Salve o app.py arquivo.

    Dica

    No macOS, tanto ActiveDirectoryInteractive quanto ActiveDirectoryDefault funcionam para autenticação do Microsoft Entra. ActiveDirectoryInteractive solicita que você faça login toda vez que executar o script. Para evitar repetidos prompts de login, faça login uma vez pela CLI do Azure executando az login, depois use ActiveDirectoryDefault, que reutiliza a credencial em cache.

  5. Abra um terminal e teste o aplicativo.

    python app.py

    Esta é 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 uma transação

Execute uma instrução INSERT com segurança e passe parâmetros. Passar parâmetros como valores protege seu aplicativo contra ataques de injeção de SQL .

  1. Adicione uma importação de randrange da biblioteca random no topo de app.py.

    from random import randrange

  2. No final de app.py, adicione o código para gerar um número de produto aleatório.

    productNumber = randrange(1000)

    Dica

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

  3. Crie uma cadeia de caracteres 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)
"""

  4. 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
   }
)

  5. Busque o resultado único usando cursor.fetchone, imprima o identificador exclusivo do resultado e confirme a operação como uma transação usando connection.commit.

    result = cursor.fetchone()
print(f"Inserted Product ID : {result.ProductID}")
conn.commit()

    Dica

    Opcionalmente, você pode usar connection.rollback para reverter a transação.

  6. Feche o cursor e a conexão usando cursor.close e connection.close.

    cursor.close()
conn.close()

  7. Salve o app.py arquivo e teste o aplicativo novamente.

    python app.py

    Esta é a saída esperada.

    Inserted Product ID : 1001

Próximas Etapas 

Use estes artigos para continuar construindo:

Strings de conexão

  • Last updated on