Conexión a Microsoft Azure SQL Database

Descargar controlador PHP

Los controladores SQLSRV y PDO_SQLSRV se conectan a los siguientes destinos SQL de Azure y Fabric con un nombre de servidor totalmente cualificado y las opciones de conexión en Opciones de Conexión. SQLSRV toma un array de opciones; PDO_SQLSRV toma un nombre de fuente de datos (DSN), argumentos de credenciales separados cuando es necesario y atributos PDO.

Ambas extensiones PHP habilitan por defecto Múltiples Conjuntos de Resultados Activos (MARS). Warehouse no soporta MARS, así que deshabilítalo explícitamente en el array de opciones de SQLSRV o en el DSN de PDO_SQLSRV. Las bases de datos SQL en Fabric y Warehouse son productos separados; no asumas que una función soportada por una está soportada por la otra.

Prepara el endpoint, la identidad y el host PHP

Tu proceso PHP necesita acceso de red al endpoint SQL, una forma soportada de iniciar sesión y permiso para abrir la base de datos seleccionada. Revisa cada requisito por separado. Por ejemplo, abrir un puerto de cortafuegos no concede acceso a la base de datos.

1. Instala la extensión PHP y el controlador Microsoft ODBC en la máquina o contenedor que ejecute PHP. Verifica la extensión en ese proceso, no solo en un terminal de desarrollo. Para más información, consulta Carga de los controladores.
2. Copia el servidor y la base de datos desde los detalles de conexión del destino. No incluyas un esquema de URL HTTPS. Utiliza el nombre de host suministrado por el servicio para que la validación del certificado compruebe el punto final previsto. Un endpoint público de Azure SQL Managed Instance puede incluir un puerto no predeterminado; conservar el puerto suministrado.
3. Configura el acceso a la red del servicio para tu host PHP. Para un endpoint privado, confirme la resolución de nombres privados y una ruta desde la red de aplicaciones. Una regla de firewall público no proporciona una ruta a una dirección privada.
4. Elige la identidad utilizada por el proceso PHP. Para una aplicación alojada en Azure, activa su identidad gestionada e identifica si está asignada por el sistema o por el usuario. El inicio de sesión de un desarrollador en CLI de Azure no es la identidad gestionada de la aplicación.
5. Que un administrador de base de datos conceda a esa identidad acceso a la base de datos seleccionada y los permisos mínimos que requiere la aplicación. En Warehouse, también comprueba el acceso a elementos y áreas de trabajo de Fabric. Los permisos de gestión de recursos de Azure no otorgan por sí solos permisos para consultar tablas de aplicación.
6. Configure SQL_SERVER y SQL_DATABASE en la configuración de la aplicación. No guardes contraseña para los ejemplos de identidad gestionada.

Los ejemplos verifican una conexión sin crear tablas. Superar esta comprobación no demuestra que la identidad puede leer o escribir el esquema de tu aplicación. Prueba las operaciones reales por separado bajo la misma identidad.

Utiliza autenticación Microsoft Entra sin contraseña

Utiliza una identidad gestionada cuando tu entorno de alojamiento exponga un punto final de identidad gestionada y el destino SQL conceda acceso a esa identidad. Los siguientes programas completos utilizan una identidad gestionada asignada por el sistema. No son ejemplos de workstation. Ejecutalos en el host de Azure configurado, con SQL_SERVER y SQL_DATABASE disponible para su proceso PHP.

Ambos programas desactivan MARS, por lo que la configuración de conexión también es adecuada al seleccionar Warehouse. Utilizan una instrucción activa a la vez. Para la configuración de identidad y otros modos de autenticación, véase Conectar usando autenticación Microsoft Entra.

Establece SQL_DATABASE con el nombre real de la base de datos. Cada programa crea un valor escapado separado para la conexión duplicando las llaves de cierre y encerrando el nombre entre llaves. Escapar evita que los caracteres especiales en el nombre de la base de datos cambien la forma en que el controlador lee los ajustes de conexión. Los programas conservan el nombre original para comprobar el resultado de DB_NAME().

SQLSRV

Guarda este programa como connect-azure-sqlsrv.php, y ejecuta php connect-azure-sqlsrv.php en el host configurado.

<?php
$server = getenv('SQL_SERVER');
$database = getenv('SQL_DATABASE');
if ($server === false || $server === '' || $database === false || $database === '') {
    throw new RuntimeException('Set SQL_SERVER and SQL_DATABASE.');
}
$databaseValue = '{' . str_replace('}', '}}', $database) . '}';

$conn = sqlsrv_connect($server, [
    'Database' => $databaseValue,
    'Authentication' => 'ActiveDirectoryMsi',
    'Encrypt' => true,
    'TrustServerCertificate' => false,
    'LoginTimeout' => 30,
    'MultipleActiveResultSets' => false,
    'CharacterSet' => 'UTF-8',
]);
if ($conn === false) {
    throw new RuntimeException(print_r(sqlsrv_errors(), true));
}

$stmt = null;
try {
    $stmt = sqlsrv_query(
        $conn,
        'SELECT DB_NAME() AS DatabaseName, CAST(1 AS int) AS Connected',
        [],
        ['QueryTimeout' => 30]
    );
    if ($stmt === false) {
        throw new RuntimeException(print_r(sqlsrv_errors(), true));
    }
    $row = sqlsrv_fetch_array($stmt, SQLSRV_FETCH_ASSOC);
    if ($row === false) {
        throw new RuntimeException(print_r(sqlsrv_errors(), true));
    }
    if ($row !== ['DatabaseName' => $database, 'Connected' => 1]) {
        throw new RuntimeException('Unexpected database or connection result.');
    }
    echo 'Connected to ', $row['DatabaseName'], '.', PHP_EOL;
} finally {
    if (is_resource($stmt)) {
        sqlsrv_free_stmt($stmt);
    }
    sqlsrv_close($conn);
}

PDO_SQLSRV

Guarda este programa separado como connect-azure-pdo.php, y ejecuta php connect-azure-pdo.php en el host configurado. Se establece PDO::SQLSRV_ATTR_FETCHES_NUMERIC_TYPE para que el resultado int sea un valor de PHP int. Sin él, PDO_SQLSRV devuelve esta columna como cadena por defecto. La codificación PDO es un atributo, no la opción SQLSRV CharacterSet .

<?php
$server = getenv('SQL_SERVER');
$database = getenv('SQL_DATABASE');
if ($server === false || $server === '' || $database === false || $database === '') {
    throw new RuntimeException('Set SQL_SERVER and SQL_DATABASE.');
}
$databaseValue = '{' . str_replace('}', '}}', $database) . '}';
$pdo = new PDO(
    "sqlsrv:Server=$server;Database=$databaseValue;Authentication=ActiveDirectoryMsi;"
    . "Encrypt=true;TrustServerCertificate=false;LoginTimeout=30;"
    . "MultipleActiveResultSets=false",
    null,
    null,
    [
        PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
        PDO::SQLSRV_ATTR_ENCODING => PDO::SQLSRV_ENCODING_UTF8,
        PDO::SQLSRV_ATTR_FETCHES_NUMERIC_TYPE => true,
    ]
);

$stmt = null;
try {
    $stmt = $pdo->prepare(
        'SELECT DB_NAME() AS DatabaseName, CAST(1 AS int) AS Connected',
        [PDO::SQLSRV_ATTR_QUERY_TIMEOUT => 30]
    );
    $stmt->execute();
    $row = $stmt->fetch(PDO::FETCH_ASSOC);
    if ($row !== ['DatabaseName' => $database, 'Connected' => 1]) {
        throw new RuntimeException('Unexpected database or connection result.');
    }
    echo 'Connected to ', $row['DatabaseName'], '.', PHP_EOL;
} finally {
    $stmt = null;
    $pdo = null;
}

Si SQL_DATABASE es appdb, cada programa imprime:

Connected to appdb.

ActiveDirectoryMsino utiliza el inicio de sesión local de tu CLI de Azure. Para desarrollo local o integración continua (CI), elige un método de autenticación soportado por la extensión PHP y el controlador ODBC. Puedes obtener un token de acceso de Microsoft Entra a través de una biblioteca de identidad y proporcionarlo a través de AccessToken. Al usar un token, omite el nombre de usuario, la contraseña y la configuración de Authentication. Configura AccessToken en el array de opciones de conexión SQLSRV o en el DSN PDO_SQLSRV. Mantén los tokens fuera del código fuente y los registros. Para obtener más información, consulte Connect using Microsoft Entra authentication.

ActiveDirectoryServicePrincipal usa un ID de cliente y un secreto de cliente; no es autenticación sin contraseña. Si lo usas, lee el secreto desde la configuración protegida de la aplicación. La autenticación SQL es una alternativa solo para los objetivos que la soportan; ni la base de datos SQL en Fabric ni en Warehouse soporta autenticación SQL.

Adapta la autenticación a tu entorno

Utiliza un único mecanismo de autenticación para cada conexión. No dejes un nombre de usuario, contraseña o configuración Authentication antigua al cambiar a AccessToken.

Solicita un token para el servicio SQL, no para la gestión de recursos de Azure. La audience del token identifica el servicio que lo acepta. Para Azure Public Cloud, solicita el scope https://database.windows.net/.default desde tu biblioteca de identidad. Confirma el recurso adecuado para otro entorno cloud. Pasa el token a la extensión PHP como cadena; no lo conviertas manualmente en una estructura de token de acceso ODBC.

Un token puede expirar mientras un worker sigue funcionando. Obtén un token válido antes de abrir otra conexión y actualiza los tokens según sea necesario en los trabajadores de larga duración. Nunca loges un DSN que contenga un token de acceso. Para más información sobre la autenticación ODBC, consulte Uso de Microsoft Entra ID con el controlador ODBC.

Mantén separados el cifrado y las comprobaciones de identidad

Encrypt=true solicita una conexión cifrada. TrustServerCertificate=false requiere validar el certificado del servidor, incluida su identidad. La autenticación Microsoft Entra establece quién es tu aplicación; no sustituye la validación de certificados de servidor.

Utiliza el endpoint proporcionado por el servicio SQL y mantén el almacén de confianza de certificados del sistema operativo cliente. No cambies el nombre del host por una dirección IP para evitar un problema de resolución de nombres. Para un endpoint privado, corrige la resolución de nombres y el enrutamiento manteniendo el nombre de conexión esperado del servicio.

LoginTimeout limita el establecimiento de conexión. QueryTimeout para SQLSRV y PDO::SQLSRV_ATTR_QUERY_TIMEOUT para PDO_SQLSRV aplican a la ejecución de instrucciones. Aumentar el tiempo de espera de una consulta no solucionará la ausencia de un punto de conexión de identidad administrada ni un usuario incorrecto de la base de datos.

Resolución de problemas por fase de fallo

SQLSRV devuelve false y expone una colección de errores a través de sqlsrv_errors(). La construcción de PDO lanza PDOException; los ejemplos también permiten excepciones para fallos de sentencias. Captura los diagnósticos inmediatamente en registros restringidos y mantén las advertencias SQLSRV distintas de errores. No devuelvas diagnósticos en bruto, tokens o detalles de conexión a un navegador.

Plan para conexiones interrumpidas

Un servicio puede desconectar una sesión inactiva o interrumpir una operación durante el mantenimiento o la conmutación por error. La resiliencia de la conexión inactiva de ODBC y los reintentos de la aplicación resuelven problemas diferentes. Para palabras clave de reintento y una prueba de desconexión controlada, véase Idle connection resiliency.

No repitas una operación de escritura solo porque el cliente haya perdido la conexión. El servidor podría haber hecho commit antes de que se perdiera la respuesta. Utiliza una política de reintentos específica para la aplicación y una forma de detectar trabajo duplicado. Libere las sentencias y los manejadores de conexión cuando termine la solicitud o el trabajo, incluidas las rutas de error. Para el comportamiento del ciclo de vida y de la agrupación, véase Conectarse al servidor.

Contenido relacionado

• Conéctate usando la autenticación de Microsoft Entra
• Opciones de conexión
• Cómo acceder a Azure SQL Database desde PHP