Configurar as definições do módulo mssql-python

O driver mssql-python fornece uma Settings classe que controla o comportamento a nível de módulo. Estas definições afetam todas as ligações e operações do cursor. Configure-as uma vez no início da aplicação, antes de criar qualquer ligação.

Definições de acesso

Recuperar o objeto atual Settings e inspecionar ou modificar as suas propriedades:

import mssql_python

# Get settings object
settings = mssql_python.get_settings()

# Check current values
print(settings.lowercase)
print(settings.decimal_separator)

Configurações disponíveis

As seguintes definições controlam como o driver devolve os dados e formata os resultados.

em minúsculas

A lowercase definição controla se os nomes das colunas em cursor.description aparecem em minúsculas. Ative esta definição quando a sua aplicação acede às colunas pelo nome e quiser evitar incompatibilidades entre maiúsculas e minúsculas. Frameworks web como Flask e FastAPI frequentemente convertem linhas em dicionários, o que torna a consistência das maiúsculas e minúsculas importantes:

settings = mssql_python.get_settings()

# Enable lowercase column names (default: False)
settings.lowercase = True

# Column names in cursor.description are now lowercased:
# ('productid', ...) instead of ('ProductID', ...)

Separador decimal

O driver fornece funções ao nível do módulo para controlar o separador decimal para conversões numéricas. Mude esta definição apenas se a sua instância do SQL Server usar um local com vírgula como separador decimal, como locais franceses ou alemães. A maioria das aplicações não precisa de alterar esta definição:

import mssql_python

# Get current separator
sep = mssql_python.getDecimalSeparator()
print(f"Current separator: {sep}")  # Usually "."

# Set custom separator (for locales using comma)
mssql_python.setDecimalSeparator(",")

Para mais informações sobre o tratamento decimal, consulte Mapeamentos de tipos de dados.

native_uuid

A definição native_uuid controla se as colunas UNIQUEIDENTIFIER são devolvidas como objetos Python uuid.UUID ou como cadeias de caracteres em maiúsculas compatíveis com pyodbc. Esta configuração é útil para equipas que estão a migrar do pyodbc e que dependem de valores UUID em formato de cadeia de caracteres:

settings = mssql_python.get_settings()

# Return UUIDs as uuid.UUID objects (default: True)
settings.native_uuid = True

# Return UUIDs as uppercase strings (pyodbc-compatible)
settings.native_uuid = False

Também pode definir native_uuid por ligação:

# Override for a specific connection
conn = mssql_python.connect(connection_string, native_uuid=False)

Constantes ao nível do módulo

O driver expõe constantes só de leitura de conformidade com a DB-API 2.0 que descrevem as suas capacidades. Use estas constantes para escrever código que se adapte a diferentes DB-API drivers:

import mssql_python

# DB-API 2.0 compliance level
print(mssql_python.apilevel)      # '2.0'

# Thread safety level
print(mssql_python.threadsafety)  # 1

# Parameter style
print(mssql_python.paramstyle)    # 'pyformat'

nível da API

A constante apilevel indica o nível de conformidade com a DB-API:

Segurança da rosca

A constante threadsafety indica o nível de segurança das threads:

O driver mssql-python usa threadsafety = 1, o que significa:

• Podes importar e usar o módulo entre threads.
• Cada conexão deve pertencer a uma única thread de cada vez.
• Crie uma ligação separada por thread, ou use um pool de ligações (ativado por defeito). Para mais informações, consulte agrupamento de ligações.

paramstyle

A constante paramstyle indica o formato do marcador de posição do parâmetro:

O driver mssql-python utiliza paramstyle = 'pyformat'. Use sempre parâmetros nomeados para evitar a injeção de SQL. Nunca construa consultas a partir da entrada do utilizador usando formatação de strings ou f-strings:

# Use named parameters with %(name)s syntax
cursor.execute(
    "SELECT * FROM Production.Product WHERE ProductSubcategoryID = %(cat)s AND ListPrice > %(price)s",
    {"cat": 5, "price": 10.00}
)

Informações sobre a versão

Verifique qual a versão do driver instalada:

import mssql_python

# Driver version
print(mssql_python.__version__)  # e.g., '1.5.0'

Configurar definições no arranque

Define a configuração do módulo uma vez no início da aplicação, antes de criares qualquer ligação. Definir valores cedo previne comportamentos inconsistentes entre ligações:

import mssql_python

def configure_driver():
    """Configure mssql-python settings for this application."""
    settings = mssql_python.get_settings()
    
    # Use lowercase column names in cursor.description
    settings.lowercase = True

# Call at application startup
configure_driver()

# All subsequent connections use these settings
conn = mssql_python.connect(connection_string)

Considerações sobre a segurança da rosca

As definições dos módulos são globais e afetam todas as ligações em todas as threads. Se mudares uma definição depois de as ligações já estarem abertas, as ligações existentes podem não refletir a alteração de forma consistente. Defina todos os valores de configuração antes de criar a sua primeira ligação:

import mssql_python
import threading

# Settings changes affect all threads
settings = mssql_python.get_settings()
settings.lowercase = True  # Affects all connections in all threads

def worker():
    # This connection uses the global settings
    conn = mssql_python.connect(connection_string)
    cursor = conn.cursor()
    cursor.execute("SELECT Name FROM Production.Product")
    row = cursor.fetchone()
    print(cursor.description[0][0])  # 'name' due to global setting

threads = [threading.Thread(target=worker) for _ in range(5)]
for t in threads:
    t.start()
for t in threads:
    t.join()

Configuração específica de ligação

Podes sobrescrever algumas definições por ligação sem alterar o padrão global. Utilize substituições por ligação quando diferentes partes da sua aplicação precisarem de comportamentos diferentes. Por exemplo, um módulo de reporte pode precisar de UUIDs de string enquanto o resto da aplicação usa uuid.UUID objetos:

# Per-connection native_uuid override
conn = mssql_python.connect(connection_string, native_uuid=False)

# Use the autocommit property
conn.autocommit = True

Conteúdo relacionado

• Cadeias de ligação
• Gestão de ligações
• Mapeamentos de tipo de dados