Partilhar via

Guia de início rápido: conecte-se com o driver pyodbc 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 pyodbc driver para Python para se conectar ao seu banco de dados e executar operações básicas, como ler e gravar dados.

Documentação pyodbc | código fonte pyodbc | Pacote (PyPi)

Pré-requisitos

  • Python 3

    • Se você ainda não tiver o Python, instale o gerenciador de pacotes Python runtime e Python Package Index (PyPI) a partir do python.org.

    • Prefere não utilizar o seu próprio ambiente? Abra como um devcontainer usando o GitHub Codespaces.

  • pyodbc pacote do PyPI.

  • Um banco de dados no SQL Server, Banco de Dados SQL do Azure ou Banco de Dados SQL no Fabric com o AdventureWorks2025 esquema de exemplo e uma cadeia de conexão válida.

Preparação

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

Observação

Esse driver usa o protocolo TDS (Tabular Data Stream ), que é habilitado por padrão no SQL Server, no banco de dados SQL no Fabric e no Banco de Dados SQL do Azure. Nenhuma configuração extra é necessária.

Instalar o pacote pyodbc

Obtenha o pyodbc pacote do PyPI.

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

  2. Instale o pacote pyodbc.

    pip install pyodbc

Instalar o pacote python-dotenv

Obtenha o 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

Criar uma base de dados SQL

Este quickstart requer o esquema AdventureWorks2025 Lightweight no Microsoft SQL Server, na base de dados SQL no Fabric ou na Azure SQL Database.

Execute o código

Criar um novo ficheiro

  1. Crie um novo arquivo chamado app.py.

  2. Adicione um módulo docstring.

    """
Connects to a SQL database using pyodbc
"""

  3. Importe o pacote pyodbc.

    from os import getenv
from dotenv import load_dotenv
from pyodbc import connect

  4. Use a pyodbc.connect função 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. Dentro do .env arquivo, adicione uma entrada para sua cadeia de conexão chamada SQL_CONNECTION_STRING. Substitua o exemplo aqui pelo valor real da cadeia de conexão.

    SQL_CONNECTION_STRING="Driver={ODBC Driver 18 for SQL Server};Server=<server_name>;Database={<database_name>};Encrypt=yes;TrustServerCertificate=no;Authentication=ActiveDirectoryInteractive"

    Sugestão

    A cadeia de conexão usada aqui depende em grande parte do tipo de banco de dados SQL ao qual você está se conectando. Se você estiver se conectando a um Banco de Dados SQL do Azure ou a um banco de dados SQL na Malha, use a cadeia de conexão ODBC na guia Cadeias de conexão. Talvez seja necessário ajustar o tipo de autenticação dependendo do cenário. Para obter mais informações sobre cadeias de conexão e sua sintaxe, consulte Referência de sintaxe de cadeia de conexão.

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 no banco de dados.

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

    Observação

    Esta função essencialmente aceita qualquer consulta e retorna um conjunto de resultados, que pode ser iterado com o uso de cursor.fetchone().

  3. Use cursor.fetchall com um foreach loop para obter todos os registros do banco de dados. Em seguida, 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

    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

Insira 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 para randrange da biblioteca random ao topo de app.py.

    from random import randrange

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

  3. Crie uma cadeia de instrução SQL.

    SQL_STATEMENT = """
INSERT SalesLT.Product (
Name,
ProductNumber,
StandardCost,
ListPrice,
SellStartDate
) OUTPUT INSERTED.ProductID
VALUES (?, ?, ?, ?, CURRENT_TIMESTAMP)
"""

  4. Execute a instrução usando cursor.execute.

    cursor.execute(
    SQL_STATEMENT,
    (
        f'Example Product {productNumber}',
        f'EXAMPLE-{productNumber}',
        100,
        200
    )
)

  5. Buscar a primeira coluna do resultado único usando cursor.fetchval, imprimir o identificador exclusivo do resultado e, em seguida, confirmar a operação como uma transação usando connection.commit.

    resultId = cursor.fetchval()
print(f"Inserted Product ID : {resultId}")
conn.commit()

    Sugestão

    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

    Aqui está a saída esperada.

    Inserted Product ID : 1001

Próximo passo

Visite o pyodbc repositório GitHub do driver para obter mais exemplos, para contribuir com ideias ou relatar problemas.

driver pyodbc no GitHub

  • Last updated on