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', ...)
Valor Descripción
False Predeterminado. Los nombres de las columnas conservan la carcasa original.
True Los nombres de las columnas en cursor.description se convierten a minúsculas.

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
Valor Descripción
True Predeterminado. UNIQUEIDENTIFIER las columnas devuelven uuid.UUID objetos.
False UNIQUEIDENTIFIER Las columnas devuelven cadenas en mayúsculas (compatibles con pyodbc).

También puedes configurar native_uuid por conexión:

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

Note

La native_uuid configuración se introdujo en la versión 1.5.0 de mssql-python.

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:

Valor Meaning
'2.0' Conformidad total con DB-API 2.0.

Seguridad de rosca

El threadsafety constante informa del nivel de seguridad del hilo:

Valor Meaning
0 Threads no puede compartir el módulo.
1 Los hilos pueden compartir el módulo pero no las conexiones.
2 Los hilos pueden compartir el módulo y las conexiones.
3 Los hilos pueden compartir el módulo, las conexiones y los cursores.

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:

Style Formato Ejemplo
'qmark' Signos de interrogación WHERE id = ?
'numeric' Posición numérica WHERE id = :1
'named' Con nombre WHERE id = :id
'format' ANSI C printf WHERE id = %s
'pyformat' Formato Python WHERE id = %(id)s

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

Importante

Configura los ajustes antes de crear conexiones. Cambiar la configuración después de crear conexiones puede provocar comportamientos inconsistentes.

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

  • Last updated on