Comparación de las funciones de ejecución

Descargar controlador PHP

Ambos controladores pueden ejecutar una sentencia una vez o preparar una sentencia para su ejecución repetida. Usa parámetros para los valores proporcionados por los usuarios, incluso cuando ejecutas una consulta solo una vez.

Elige la API de ejecución por separado de cómo obtienes los resultados. Preparar una consulta no recupera sus filas, y almacenar un resultado en búfer no hace que una consulta esté parametrizada. Los siguientes ejemplos preparan una consulta de solo lectura una vez, la ejecutan dos veces con valores diferentes y consumen cada resultado antes de la siguiente ejecución.

sqlsrv_query() se prepara y ejecuta en una sola llamada y devuelve un recurso de instrucción. sqlsrv_prepare() devuelve un recurso de instrucción sin ejecutarlo; llama a sqlsrv_execute() en cada ejecución. El query() de PDO ejecuta y devuelve PDOStatement, mientras que exec() devuelve un conteo de filas afectadas en lugar de un objeto de resultado. Una llamada correcta a exec() puede devolver 0, así que compare un valor devuelto en caso de error con === false, no con if (!$count).

PDO::query() no acepta un array de valores de parámetros. Sus argumentos opcionales configuran la obtención. Para consultas PDO_SQLSRV parametrizadas, use prepare() y execute().

Preparar una vez te permite reutilizar un controlador de sentencia con valores diferentes. Esto no garantiza que el servidor nunca recompile su plan de ejecución. PDO_SQLSRV utiliza ejecución preparada por defecto, incluyendo para PDO::query(); su atributo de consulta directa controla esa elección separada.

Prepara una vez y ejecuta repetidamente

Estos son programas de línea de comandos completos y separados. Instala y carga la extensión seleccionada, y establece SQL_SERVER, SQL_DATABASE, SQL_USER, y SQL_PASSWORD en el entorno de proceso PHP. Utiliza una base de datos de prueba de SQL Server y un certificado de servidor en el que el cliente confíe. Para la configuración del entorno y alternativas sin contraseña, véase Conectarse al servidor.

Almacena el nombre real de la base de datos, nombre de usuario y contraseña en las variables de entorno. Ambos programas escapan estos valores una vez duplicando las llaves de cierre y encerrando cada valor entre llaves, como requiere el manejo de conexiones de estilo ODBC del controlador PHP. El escape de los valores de conexión es independiente de vincular los parámetros de consulta.

Los programas ejecutan una consulta Transact-SQL (T-SQL) sobre dos filas en línea sin crear una tabla ni cambiar datos. Guarda cada programa en su propio .php archivo y ejecútalo con php <file>. No se requiere ninguna base de datos de muestras.

SQLSRV

Pasar $productId por referencia con &$productId. Cada sqlsrv_execute() utiliza entonces su valor actual. SQLSRV_FETCH_ASSOC devuelve un array indexado por nombre de columna. Un resultado null significa que no hay más filas; false indica un error.

<?php
$config = [];
foreach (['SQL_SERVER', 'SQL_DATABASE', 'SQL_USER', 'SQL_PASSWORD'] as $name) {
    $value = getenv($name);
    if ($value === false || $value === '') {
        throw new RuntimeException("Set $name before running this example.");
    }
    $config[$name] = $value;
}
foreach (['SQL_DATABASE', 'SQL_USER', 'SQL_PASSWORD'] as $name) {
    $config[$name] = '{' . str_replace('}', '}}', $config[$name]) . '}';
}
$conn = sqlsrv_connect($config['SQL_SERVER'], [
    'Database' => $config['SQL_DATABASE'],
    'UID' => $config['SQL_USER'],
    'PWD' => $config['SQL_PASSWORD'],
    'Encrypt' => true,
    'TrustServerCertificate' => false,
    'LoginTimeout' => 30,
    'CharacterSet' => 'UTF-8',
]);
if ($conn === false) {
    throw new RuntimeException(print_r(sqlsrv_errors(), true));
}

$sql = "SELECT Name FROM (VALUES (1, 'Bike'), (2, 'Helmet')) AS Product(ProductId, Name) WHERE ProductId = ?";
$productId = 1;
$stmt = null;
try {
    $stmt = sqlsrv_prepare($conn, $sql, [&$productId], ['QueryTimeout' => 30]);
    if ($stmt === false) {
        throw new RuntimeException(print_r(sqlsrv_errors(), true));
    }
    foreach ([1 => 'Bike', 2 => 'Helmet'] as $productId => $expected) {
        if (!sqlsrv_execute($stmt)) {
            throw new RuntimeException(print_r(sqlsrv_errors(), true));
        }
        $names = [];
        while (($row = sqlsrv_fetch_array($stmt, SQLSRV_FETCH_ASSOC)) !== null) {
            if ($row === false) {
                throw new RuntimeException(print_r(sqlsrv_errors(), true));
            }
            $names[] = $row['Name'];
        }
        if ($names !== [$expected]) {
            throw new RuntimeException('Expected exactly one matching product.');
        }
        echo $names[0], PHP_EOL;
    }
} finally {
    if (is_resource($stmt)) {
        sqlsrv_free_stmt($stmt);
    }
    sqlsrv_close($conn);
}

PDO_SQLSRV

Vincula $productId una vez con bindParam(). Cada execute() lee su valor actual. PDO::PARAM_INT especifica el tipo de enlace PHP/PDO del parámetro; no controla el tipo PHP de columnas obtenidas del resultado. Establece el modo de excepción para que un error de base de datos interrumpa la ejecución en lugar de confundirse con un resultado vacío.

<?php
$config = [];
foreach (['SQL_SERVER', 'SQL_DATABASE', 'SQL_USER', 'SQL_PASSWORD'] as $name) {
    $value = getenv($name);
    if ($value === false || $value === '') {
        throw new RuntimeException("Set $name before running this example.");
    }
    $config[$name] = $value;
}
foreach (['SQL_DATABASE', 'SQL_USER', 'SQL_PASSWORD'] as $name) {
    $config[$name] = '{' . str_replace('}', '}}', $config[$name]) . '}';
}
$server = $config['SQL_SERVER'];
$database = $config['SQL_DATABASE'];
$pdo = new PDO(
    "sqlsrv:Server=$server;Database=$database;Encrypt=true;"
    . "TrustServerCertificate=false;LoginTimeout=30",
    $config['SQL_USER'],
    $config['SQL_PASSWORD'],
    [
        PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
        PDO::SQLSRV_ATTR_ENCODING => PDO::SQLSRV_ENCODING_UTF8,
    ]
);
$sql = "SELECT Name FROM (VALUES (1, 'Bike'), (2, 'Helmet')) AS Product(ProductId, Name) WHERE ProductId = ?";
$stmt = null;
try {
    $stmt = $pdo->prepare($sql, [PDO::SQLSRV_ATTR_QUERY_TIMEOUT => 30]);
    $productId = 1;
    $stmt->bindParam(1, $productId, PDO::PARAM_INT);
    foreach ([1 => 'Bike', 2 => 'Helmet'] as $productId => $expected) {
        $stmt->execute();
        $names = $stmt->fetchAll(PDO::FETCH_COLUMN);
        if ($names !== [$expected]) {
            throw new RuntimeException('Expected exactly one matching product.');
        }
        echo $names[0], PHP_EOL;
        $stmt->closeCursor();
    }
} finally {
    $stmt = null;
    $pdo = null;
}

Cada ejemplo imprime:

Bike
Helmet

Los valores en un array que se pasan a execute() de PDO se tratan como PDO::PARAM_STR. Cuando SQL requiere un parámetro entero, como un recuento parametrizado TOP, llame a bindValue() con PDO::PARAM_INT y luego llame a execute() sin un array.

Vincular valores sin cambiar la consulta

Un marcador de parámetro representa un valor, no un nombre de tabla, nombre de columna, palabra clave o dirección de ordenación. No pongas comillas alrededor ?. Para un identificador dinámico o ASC/DESC, selecciona de una lista de elementos permitidos controlada por la aplicación en lugar de concatenar texto no confiable. Para una IN lista, proporciona un marcador por valor.

Mantén activas las variables de referencia al ejecutar la sentencia preparada. El programa SQLSRV cambia la variable vinculada en lugar de reemplazar el array de parámetros. El programa PDO llama execute() deliberadamente sin un array tras el enlace; no mezcles ese patrón con la ejecución basada en array.

Los valores de salida de los procedimientos almacenados requieren su propio manejo, incluida la finalización del procesamiento de los resultados del procedimiento. No infieras comportamiento de parámetros de salida a partir de estos ejemplos solo de entrada. Para más información, véase Uso de los parámetros direccionales.

Configurar el comportamiento de ejecución y recuperación

Los ejemplos demuestran resultados pequeños. fetchAll() carga cada fila en memoria PHP; utiliza un bucle de búsqueda para un conjunto de resultados grande. Una consulta que no devuelve coincidencias no es un error de ejecución. SQLSRV informa del final del resultado como null de sqlsrv_fetch_array(); PDO lo informa como false de fetch(). Un SQL NULL dentro de una fila obtenida sigue siendo PHP null.

No utilices el conteo SELECT de filas como única comprobación de éxito. Los cursores solo hacia adelante no ofrecen las mismas capacidades de conteo de filas que los cursores con búfer o desplazables. Busca y cuenta las filas que necesitas, o usa una consulta aparte COUNT . Para opciones y limitaciones específicas del cursor, consulte Especificar un tipo de cursor y seleccionar filas.

Gestionar fallos y resultados finales

Comprueba las operaciones de preparación SQLSRV, ejecución y obtención por separado. Una preparación exitosa no demuestra que la ejecución tendrá éxito: el servidor puede rechazar valores de parámetros, permisos o la sentencia en el momento de ejecución. Captura sqlsrv_errors() inmediatamente cuando una operación devuelva false. SQLSRV trata muchas advertencias como errores por defecto, así que inspecciona la colección completa.

Para PDO, los fallos de conexión y errores de base de datos en modo excepción lanzan PDOException. Inspeccionar su estado SQLSTATE y la información de error del controlador en el diagnóstico de aplicación protegida; no devolver el texto de excepción ni las credenciales en una respuesta HTTP. prepare() Tener éxito no es prueba de que la instrucción ya se haya ejecutado.

Los ejemplos cierran sus instrucciones y cierran sus conexiones en finally. No inician una transacción. Utiliza una transacción explícita cuando varias escrituras deben hacer commit juntas o revertir todas. Reutilizar una sentencia preparada no agrupa las operaciones de escritura en una transacción.

Diferencias entre objetivo e implementación

Las APIs de preparación/ejecución y las reglas de referencia de PHP pertenecen a las extensiones y a PHP/PDO. El destino SQL decide qué sentencias y tipos de T-SQL son compatibles, y ODBC realiza la comunicación subyacente. Prepararlo una vez puede reducir el trabajo repetido, pero no garantiza un plan de ejecución del servidor específico ni una aceleración.

Los patrones de enlace de entrada se aplican a SQL Server, Azure SQL Database, Azure SQL Managed Instance, Azure Synapse Analytics, base de datos SQL en Microsoft Fabric y Warehouse en Microsoft Fabric. Estos programas utilizan autenticación SQL para SQL Server. Para la incorporación en Azure, prefiero la autenticación Microsoft Entra. Ambos productos Fabric lo requieren, y Warehouse también requiere desactivar los Múltiples Conjuntos Activos de Resultados (MARS). Comprueba el soporte del destino seleccionado para cambios de esquema, transacciones y procedimientos almacenados antes de reutilizar el código de SQL Server. Para diferencias entre endpoint y autenticación, véase conexiones Azure y Fabric.

Contenido relacionado

• Referencia de la API de controladores SQLSRV
• Referencia del controlador PDO_SQLSRV
• Guía de programación para los controladores de Microsoft para PHP para SQL Server