Configurar la configuración del módulo mssql-python

El controlador mssql-python proporciona una Settings clase que controla el comportamiento a nivel de módulo. Estos ajustes afectan a todas las conexiones y operaciones de cursor. Configúralas una vez al iniciar la aplicación, antes de crear cualquier conexión.

Configuración de acceso

Recuperar el objeto actual Settings e inspeccionar o modificar sus propiedades:

import mssql_python

# Get settings object
settings = mssql_python.get_settings()

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

Configuración disponible

Las siguientes configuraciones controlan cómo el controlador devuelve los datos y formatea los resultados.

minúsculas

La configuración lowercase controla si los nombres de las columnas en cursor.description aparecen en minúsculas. Habilita esta configuración si tu aplicación accede a las columnas por nombre y quieres evitar discordancias entre mayúsculas y minúsculas. Frameworks web como Flask y FastAPI suelen convertir las filas en diccionarios, lo que hace importante mantener un uso coherente de mayúsculas y minúsculas:

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

El controlador proporciona funciones de nivel de módulo para controlar el separador decimal para las conversiones numéricas. Cambia esta configuración solo si tu instancia de SQL Server usa una localidad con coma como separador decimal, como localidades francesas o alemanas. La mayoría de las aplicaciones no necesitan cambiar esta configuración:

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 más información sobre el manejo decimal, véase Mapeos de tipos de datos.

native_uuid

La native_uuid configuración controla si UNIQUEIDENTIFIER las columnas se devuelven como objetos Python uuid.UUID o como cadenas mayúsculas compatibles con pyodbc. Esta configuración es útil para equipos que migran desde pyodbc y que dependen de valores UUID de cadena:

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

También puedes configurar native_uuid por conexión:

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

Constantes a nivel de módulo

El controlador expone constantes de solo lectura de conformidad con DB-API 2.0 que describen sus capacidades. Utiliza estas constantes para escribir código que se adapte a diferentes controladores de 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'

nivel de API

La apilevel constante indica el nivel de cumplimiento de DB-API:

Seguridad de rosca

El threadsafety constante informa del nivel de seguridad del hilo:

El controlador mssql-python utiliza threadsafety = 1, lo que significa:

• Puedes importar y usar el módulo entre hilos.
• Cada conexión debe pertenecer solo a un hilo a la vez.
• Crea una conexión separada por hilo, o usa un pool de conexiones (activado por defecto). Para más información, consulta la agrupación de conexiones.

paramstyle

La paramstyle constante informa del formato de marcador de posición del parámetro:

El controlador mssql-python utiliza paramstyle = 'pyformat'. Utiliza siempre parámetros con nombre para evitar la inyección SQL. No construyas nunca consultas con datos introducidos por el usuario usando formateo de cadenas ni 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}
)

Información de versión

Comprueba qué versión del controlador está instalada:

import mssql_python

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

Configurar ajustes al arrancar

Configura la configuración del módulo una vez al iniciar la aplicación, antes de crear cualquier conexión. Establecer valores temprano previene comportamientos inconsistentes entre conexiones:

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)

Consideraciones sobre la seguridad de la rosca

La configuración del módulo es global y afecta a todas las conexiones de todos los hilos. Si cambias una configuración después de que las conexiones ya estén abiertas, las conexiones existentes pueden no reflejar el cambio de forma consistente. Establece todos los valores de configuración antes de crear tu primera conexión:

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()

Configuración específica de la conexión

Puedes anular algunos ajustes por conexión sin cambiar el valor global por defecto. Usa anulaciones por conexión cuando diferentes partes de tu aplicación necesitan un comportamiento distinto. Por ejemplo, un módulo de informes puede necesitar UUID de cadena mientras el resto de la aplicación utiliza uuid.UUID objetos:

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

# Use the autocommit property
conn.autocommit = True

Contenido relacionado

• Cadenas de conexión
• Administración de conexiones
• Asignaciones de tipos de datos