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. Você usa o mssql-python driver do Python para se conectar ao seu banco 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 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 o Banco de Dados SQL do Azure, banco de dados SQL no Fabric, ambientes de desenvolvimento compartilhados, CI e implantações em produção, comece com a autenticação do 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.

Pré-requisitos para instalar o sistema operacional

Instale pré-requisitos específicos do sistema operacional uma vez. Usuários do Windows podem pular essa etapa. Para detalhes completos da plataforma, veja Instalar mssql-python.

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

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.

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 desejados estão instalados.

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 banco de dados SQL 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"

    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 banco de dados SQL no Fabric, use a autenticação do 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.

    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 prompts repetidos de login, faça login 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.

  1. Crie uma variável para a string de consulta do 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;
"""

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

  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

    Um número aleatório de produto reduz a chance de um erro de chave duplicada quando você executa essa amostra mais de uma vez.

  3. Crie uma string de instruções 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)
"""

  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

Conteúdo relacionado

  • Última atualização em