Conectarse a un Microsoft SQL Server usando Python y Pyodbc

Usa pyodbc para conectar una aplicación Python a Microsoft SQL Server mediante ODBC. Instala tanto el paquete de Python como un controlador ODBC compatible con SQL Server; después, pasa el servidor, la base de datos, el controlador y la configuración de autenticación a pyodbc.connect(). Esta guía usa SQL directamente; un ORM es otra opción si quieres representar las tablas de la base de datos como objetos de Python.

Instalar pyodbc y el controlador ODBC de SQL Server

Instala pyodbc en el mismo entorno de Python que ejecuta tu aplicación, por ejemplo, con python -m pip install pyodbc. Esto instala la interfaz de Python, pero no el controlador ODBC de Microsoft. Instala por separado un controlador ODBC de SQL Server en el equipo o contenedor donde se ejecuta el programa y asegúrate de que su nombre coincida exactamente con el del controlador instalado. Un nombre habitual es ODBC Driver 18 for SQL Server; usa el nombre disponible en tu sistema.

Antes de conectarte, reúne la dirección del servidor y el nombre de la base de datos. El servidor puede ser un nombre de host, una dirección o un nombre de host e instancia, como db.example.net\SQLEXPRESS; los entornos alojados también pueden requerir un puerto. Es posible que el administrador tenga que conceder a la cuenta acceso a la base de datos seleccionada. La información de conexión de SQL Server es independiente del directorio de trabajo de Python, pero el controlador debe estar disponible para el administrador ODBC del sistema operativo.

Conectar con un controlador y autenticación de confianza

En un entorno Windows configurado para la autenticación integrada, usa una cadena de conexión basada en un controlador con Trusted_Connection=yes. Sustituye los valores del controlador, el servidor y la base de datos por los de tu instalación. El siguiente programa pequeño construye y muestra la cadena para que puedas comprobar cómo se unen sus campos; no se conecta a ninguna base de datos.

Ejecuta este ejemplo:

El código y las etiquetas o salidas visibles de esta sección se mantienen en inglés.

driver = "ODBC Driver 18 for SQL Server"
server = "db.example.net"
database = "Sales"
connection_string = (
    f"Driver={{{driver}}};"
    f"Server={server};"
    f"Database={database};"
    "Trusted_Connection=yes;"
)
print(connection_string)

Driver={ODBC Driver 18 for SQL Server};Server=db.example.net;Database=Sales;Trusted_Connection=yes;

Para abrir la conexión en tu aplicación, pasa esa cadena a pyodbc.connect(connection_string). La autenticación integrada usa la identidad disponible para el proceso y depende de la configuración del sistema operativo, del controlador y de SQL Server; no equivale a proporcionar un nombre de usuario y una contraseña de SQL Server. Para configurar TLS, sigue la política de certificados de tu organización. Los valores predeterminados de cifrado pueden variar entre versiones de controladores, así que no desactives la comprobación de certificados solo para conseguir que funcione una conexión.

Conectar mediante un DSN con credenciales

Un nombre de origen de datos (DSN) es una configuración ODBC creada en el host. Puede contener la configuración compartida del servidor y del controlador, de modo que la aplicación solo tenga que indicar el nombre del DSN y, cuando sea necesario, las credenciales. La cadena de conexión tiene este formato: DSN=SalesReadOnly;UID=app_reader;PWD=<secret>;. El DSN debe existir en el mismo entorno y estar visible para el proceso de Python; es posible que un DSN configurado para un usuario interactivo no esté disponible para una cuenta de servicio o un contenedor.

Proporciona las credenciales mediante un gestor de secretos o una configuración específica del entorno, en lugar de guardarlas en el código fuente. Si el secreto contiene caracteres especiales, usa las reglas de comillas compatibles con las cadenas de conexión ODBC o configura la credencial por separado; de lo contrario, el punto y coma podría interpretarse como separador de campos. Evita imprimir la cadena de conexión completa, ya que podría revelar la contraseña en los registros. Usa la misma llamada pyodbc.connect(...) con la cadena del DSN y elige la autenticación integrada o la de SQL según la configuración del DSN y del servidor.

Ejecutar una consulta y cerrar los recursos

Después de conectarte, crea un cursor, ejecuta SQL y obtén las filas devueltas, ya sea recuperándolas o iterando sobre ellas. Usa marcadores de parámetros para los valores proporcionados por usuarios o por los datos de la aplicación. En pyodbc, ? es el marcador posicional; pasar los valores por separado los mantiene diferenciados del texto SQL. Los parámetros sirven para valores de datos, no para nombres de tablas o columnas. Si un identificador debe variar, selecciónalo de una lista de permitidos fija y delimítalo según las reglas de SQL Server.

Un flujo de aplicación habitual es connection = pyodbc.connect(connection_string), seguido de cursor = connection.cursor() y cursor.execute("SELECT name FROM dbo.Customers WHERE customer_id = ?", customer_id). Itera sobre cursor para procesar las filas o llama a fetchall() cuando el resultado sea lo bastante pequeño como para caber en memoria. Para conjuntos de resultados grandes, procesa las filas de forma incremental. La consulta presupone que la tabla y la columna indicadas existen en la base de datos seleccionada; sustitúyelas por las de tu esquema.

Cuando connection = pyodbc.connect(connection_string) se haya completado correctamente, incluye el trabajo con el cursor en un bloque try y cierra la conexión en su cláusula finally: try: ... finally: connection.close(). Para limpiar el cursor, usa with connection.cursor() as cursor: dentro de ese bloque; al salir del contexto del cursor, este se cierra. Un contexto de conexión de pyodbc, como with connection:, gestiona el ámbito de la transacción: confirma los cambios al salir normalmente y revierte la transacción si se propaga una excepción, pero no cierra la conexión. Puedes combinar ese contexto de transacción con el contexto del cursor dentro del try y llamar después a connection.close() en finally. Así se cierra la conexión después de procesar la consulta tanto si se termina normalmente como si ocurre una excepción, siempre que la conexión se haya abierto correctamente. Si modificas datos, decide explícitamente en qué momento se debe confirmar la transacción. Este patrón de uso requiere un SQL Server, un controlador y un esquema configurados; no se ha ejecutado como parte de este artículo.

Diagnosticar errores habituales de conexión

Si pyodbc indica que no se encuentra un controlador, comprueba que el controlador ODBC esté instalado en el entorno de ejecución del programa y que el valor Driver={...} coincida con el nombre registrado, incluidos los espacios y la versión. Si no se puede acceder al servidor, verifica el DNS o la escritura del host, la configuración del puerto y de la instancia, el acceso del firewall y si SQL Server acepta conexiones de red. Por lo general, un tiempo de espera agotado apunta a un problema de conectividad o a la carga del servidor; aumentarlo no corregirá un destino incorrecto.

Si falla el inicio de sesión, confirma qué identidad usa realmente la conexión. La autenticación de confianza usa la identidad del proceso, mientras que UID y PWD solicitan credenciales de SQL; mezclar estos métodos puede hacer que se envíe una identidad incorrecta. Comprueba también el acceso a la base de datos y su nombre. Si hay errores de certificado o cifrado, consulta con el administrador la cadena de certificados del servidor y la configuración de cifrado del controlador, en vez de debilitar la verificación. Por último, revisa la cadena de conexión para detectar puntos y coma ausentes, llaves sin cerrar alrededor de los nombres de los controladores, espacios accidentales en las claves o caracteres especiales sin escapar. Mantén la utilidad de los registros de diagnóstico y oculta las contraseñas y otros secretos.

Para obtener información sobre los controladores y las cadenas de conexión, consulta la guía de conexión de pyodbc a SQL Server y la documentación oficial de pyodbc. Para ver un ejemplo relacionado con la lectura de resultados de consultas, consulta How to Extract Elements From a Database Using fetchall() in Python. No hay un destino localizado disponible para este enlace; se conserva el destino original en inglés.