Configurar configurações de módulo mssql-python

O driver mssql-python fornece uma Settings classe que controla o comportamento em todo o módulo. Essas configurações afetam todas as conexões e operações do cursor. Configure-as uma vez na inicialização do aplicativo, antes de criar qualquer conexão.

Configurações de acesso

Recupere o objeto atual Settings e inspecione ou modifique 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 configurações a seguir controlam como o driver retorna os dados e formata os resultados.

em minúsculas

A lowercase configuração determina se os nomes das colunas em cursor.description aparecem em minúsculas. Ative esta configuração quando seu aplicativo acessar colunas por nome e você quiser evitar incompatibilidades entre maiúsculas e minúsculas. Estruturas da web, como Flask e FastAPI, frequentemente convertem linhas em dicionários, o que torna importante a consistência na capitalização:

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', ...)
Valor Descrição
False Padrão. Os nomes das colunas preservam a capitalização original.
True Os nomes das colunas em cursor.description são convertidos para minúsculas.

Separador decimal

O driver fornece funções em nível de módulo para controlar o separador decimal para conversões numéricas. Mude essa configuração somente se 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 alterar essa configuraçã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 manuseio decimal, veja Mapeamentos de tipos de dados.

native_uuid

A configuração native_uuid controla se as colunas UNIQUEIDENTIFIER são retornadas como objetos Python uuid.UUID ou como strings em maiúsculas compatíveis com pyodbc. Essa configuração é útil para equipes que estão migrando do pyodbc e dependem de valores de UUID em formato de string:

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
Valor Descrição
True Padrão. UNIQUEIDENTIFIER colunas retornam uuid.UUID objetos.
False UNIQUEIDENTIFIER As colunas retornam strings em maiúsculas (compatíveis com pyodbc).

Você também pode definir native_uuid por conexão:

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

Note

A native_uuid configuração foi introduzida na versão 1.5.0 do mssql-python.

Selecione o provedor ODBC nativo

O driver carrega um provedor ODBC nativo por processo. Dois provedores estão disponíveis:

Provider Descrição Entrega em
msodbcsql18 Padrão. Driver Microsoft ODBC 18 para SQL Server. mssql-python-odbc
mssql-odbc Aceitar. Um provedor ODBC baseado em Rust. mssql-python-rs

Ambos os pacotes são instalados com pip install mssql-python, então você não precisa instalar mais nada para tentar o mssql-odbc provedor. Seu código de aplicação não muda.

Selecione o provedor com a variável de ambiente MSSQL_PYTHON_NATIVE_PROVIDER. No Linux ou macOS:

export MSSQL_PYTHON_NATIVE_PROVIDER=mssql-odbc

No Windows PowerShell:

$env:MSSQL_PYTHON_NATIVE_PROVIDER = "mssql-odbc"

Ou defina o atributo native_provider do módulo antes de abrir a primeira conexão:

import mssql_python

mssql_python.native_provider = "mssql-odbc"

conn = mssql_python.connect(connection_string)
print(mssql_python.get_native_provider_info())

A função get_native_provider_info() retorna o provedor selecionado e de onde veio a seleção:

{'id': 'mssql-odbc', 'package': 'mssql_py_core', 'version': None, 'driver_path': '...', 'source': 'property', 'frozen': True}

O driver aplica estas regras ao resolver o provedor:

  • A variável ambiente tem precedência sobre o native_provider atributo. Se você definir o atributo para um provedor diferente da variável de ambiente, o driver emite RuntimeWarning e usa a variável de ambiente.

  • A seleção é fixada quando o driver carrega o provedor, o que acontece após a análise da cadeia de conexão e antes do driver entrar em contato com o servidor. A seleção permanece fixa mesmo que a conexão falhe, por exemplo, porque o servidor está inacessível. Um erro gerado antes do carregamento do provedor, como um erro de análise de cadeia de conexão ou um pacote de provedor ausente, não resolve o problema da seleção. Após a seleção ser fixada, uma mudança em native_provider emite RuntimeWarning e não tem efeito no restante do processo.

  • Um nome de provedor não reconhecido gera ValueError. Definir o atributo para um nome desconhecido gera um erro imediatamente. Um nome desconhecido na variável de ambiente gera um erro quando você abre a primeira conexão. O driver não usa o provedor padrão como alternativa.

  • Defina native_provider como None para limpar uma seleção antes da primeira conexão.

Constantes em nível de módulo

O driver expõe constantes de conformidade com a DB-API 2.0 que são apenas leitura e descrevem suas capacidades. Use essas constantes para escrever código que se adapta a diferentes drivers DB-API:

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'

Apilevel

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

Valor Meaning
'2.0' Conformidade total com a DB-API 2.0.

threadsafety

A constante threadsafety informa o nível de segurança de thread:

Valor Meaning
0 Threads não podem compartilhar o módulo.
1 Threads podem compartilhar o módulo, mas não as conexões.
2 Threads podem compartilhar o módulo e as conexões.
3 Threads podem compartilhar o módulo, as conexões e os cursores.

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

  • Você pode importar e usar o módulo entre threads.
  • Cada conexão deve estar associada a somente uma thread por vez.
  • Crie uma conexão separada por thread, ou use um pool de conexões (ativado por padrão). Para mais informações, veja Agrupamento de conexões.

paramstyle

A paramstyle constante reporta o formato do parâmetro provisório:

Style Format Example
'qmark' Pontos de interrogação WHERE id = ?
'numeric' Posição numérica WHERE id = :1
'named' nomeado WHERE id = :id
'format' ANSI C printf WHERE id = %s
'pyformat' Formato Python WHERE id = %(id)s

O driver mssql-python usa paramstyle = 'pyformat'. Sempre use parâmetros nomeados para evitar a injeção de SQL. Nunca crie consultas usando dados fornecidos pelo usuário por meio de 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 da versão

Verifique qual versão do driver está instalada:

import mssql_python

# Driver version
print(mssql_python.__version__)  # For example, '1.16.0'

Configurar configurações na inicialização

Defina a configuração do módulo uma vez na inicialização do aplicativo, antes de criar qualquer conexão. Definir valores cedo previne comportamentos inconsistentes entre conexõ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 configurações do módulo são globais e afetam todas as conexões entre todos os threads. Se você mudar uma configuração depois que as conexões já estão abertas, as conexões existentes podem não refletir a mudança de forma consistente. Defina todos os valores de configuração antes de criar sua primeira conexã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()

Importante

Configure as configurações antes de criar conexões. Mudar as configurações após a criação das conexões pode levar a comportamentos inconsistentes.

Configuração específica de conexão

Você pode sobrescrever algumas configurações por conexão sem mudar o padrão global. Use substituições por conexão quando diferentes partes do seu aplicativo precisarem de comportamento diferente. Por exemplo, um módulo de relatório pode precisar de UUIDs de string enquanto o restante 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

  • Última atualização em