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 sua aplicação acessa colunas por nome e você quer evitar incompatibilidades entre maiúsculas e minúsculas. Frameworks 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', ...)

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

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

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

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:

Segurança da rosca

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

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:

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__)  # e.g., '1.5.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()

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 da sua aplicação 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

• Strings de conexão
• Gerenciamento de conexões
• Mapeamentos de tipo de dados