Compatibilidad con LocalDB

Descargar controlador PHP

SQL Server Express LocalDB es un modo ligero de instancia de usuario de SQL Server Express, disponible solo para Windows. Ambos controladores se conectan a una instancia de LocalDB de la misma forma que se conectan a cualquier instancia con nombre, utilizando el formato de nombre de servidor (localdb)\<instance-name>.

Observaciones

LocalDB se ejecuta bajo una cuenta de usuario de Windows. Los programas utilizan la autenticación integrada de Windows, no la autenticación de Microsoft Entra. Úsalo para desarrollo local de Windows cuando una instancia de base de datos por usuario se adapte a tu flujo de trabajo. No es una imagen contenedor ni un servicio de Azure.

Conectarse a una instancia de LocalDB

Instala una versión compatible de SQL Server Express LocalDB, así como el requisito previo de ODBC y la extensión de PHP que selecciones. La instalación de LocalDB no carga una extensión PHP.

1. Ejecuta sqllocaldb.exe i en tu terminal de Windows para listar tus instancias.
2. Si MSSQLLocalDB no existe, corre sqllocaldb.exe create MSSQLLocalDB.
3. Ejecuta sqllocaldb.exe start MSSQLLocalDB, luego sqllocaldb.exe info MSSQLLocalDB para inspeccionar la instancia. Realiza estos pasos como la cuenta de Windows que ejecuta el programa PHP.
4. Guarda y ejecuta uno de los programas con PHP de línea de comandos. Cada uno se conecta a master de forma predeterminada y verifica que el destino sea realmente LocalDB. No se requiere una base de datos de ejemplo ni contraseña SQL.

El nombre de la instancia es específico del equipo Windows y de la cuenta propietaria. No es un nombre de host DNS, un puerto TCP ni una conexión a otro ordenador.

SQLSRV

Guarda este programa como connect-localdb-sqlsrv.php, y ejecuta php connect-localdb-sqlsrv.php.

<?php
$instance = getenv('LOCALDB_INSTANCE') ?: 'MSSQLLocalDB';
$database = getenv('LOCALDB_DATABASE');
if ($database === false || $database === '') {
    $database = 'master';
}
$file = getenv('LOCALDB_MDF');
$databaseValue = '{' . str_replace('}', '}}', $database) . '}';
$options = ['Database' => $databaseValue, 'LoginTimeout' => 30, 'CharacterSet' => 'UTF-8'];
if ($file !== false && $file !== '') {
    if ($database === 'master' || !is_file($file)) {
        throw new RuntimeException('Set a non-master database name and an accessible MDF path.');
    }
    $options['AttachDBFileName'] = '{' . str_replace('}', '}}', $file) . '}';
}
$conn = sqlsrv_connect('(localdb)\\' . $instance, $options);
if ($conn === false) {
    throw new RuntimeException(print_r(sqlsrv_errors(), true));
}
$stmt = null;
try {
    $stmt = sqlsrv_query(
        $conn,
        "SELECT DB_NAME() AS DatabaseName, CAST(SERVERPROPERTY('IsLocalDB') AS int) AS IsLocalDB"
    );
    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, 'IsLocalDB' => 1]) {
        throw new RuntimeException('Expected the selected LocalDB database.');
    }
    echo 'LocalDB database: ', $row['DatabaseName'], PHP_EOL;
} finally {
    if (is_resource($stmt)) {
        sqlsrv_free_stmt($stmt);
    }
    sqlsrv_close($conn);
}

PDO_SQLSRV

Guarda este programa separado como connect-localdb-pdo.php, y ejecuta php connect-localdb-pdo.php.

<?php
$instance = getenv('LOCALDB_INSTANCE') ?: 'MSSQLLocalDB';
$database = getenv('LOCALDB_DATABASE');
if ($database === false || $database === '') {
    $database = 'master';
}
$file = getenv('LOCALDB_MDF');
$databaseValue = '{' . str_replace('}', '}}', $database) . '}';
$dsn = "sqlsrv:Server=(localdb)\\$instance;Database=$databaseValue;LoginTimeout=30";
if ($file !== false && $file !== '') {
    if ($database === 'master' || !is_file($file)) {
        throw new RuntimeException('Set a non-master database name and an accessible MDF path.');
    }
    $dsn .= ';AttachDBFileName={' . str_replace('}', '}}', $file) . '}';
}
$pdo = new PDO($dsn, null, null, [
    PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
    PDO::SQLSRV_ATTR_FETCHES_NUMERIC_TYPE => true,
    PDO::SQLSRV_ATTR_ENCODING => PDO::SQLSRV_ENCODING_UTF8,
]);
$stmt = null;
try {
    $stmt = $pdo->query(
        "SELECT DB_NAME() AS DatabaseName, CAST(SERVERPROPERTY('IsLocalDB') AS int) AS IsLocalDB"
    );
    $row = $stmt->fetch(PDO::FETCH_ASSOC);
    if ($row !== ['DatabaseName' => $database, 'IsLocalDB' => 1]) {
        throw new RuntimeException('Expected the selected LocalDB database.');
    }
    echo 'LocalDB database: ', $row['DatabaseName'], PHP_EOL;
} finally {
    $stmt = null;
    $pdo = null;
}

Salida esperada con la configuración predeterminada:

LocalDB database: master

SQLSRV devuelve un recurso de conexión y reporta los fallos de conexión como false. PDO devuelve un objeto y lanza PDOException si falla la construcción. El programa PDO habilita explícitamente la recuperación numérica, por lo que el valor int es PHP int, coincidiendo con el resultado de SQLSRV. Ambos utilizan UTF-8 para los datos de caracteres y liberan las instrucciones y los identificadores de conexión incluso cuando falla una consulta.

Seleccione una base de datos existente o adjunte un archivo

Los programas aceptan estas variables opcionales de proceso:

Para usar una base de datos ya registrada en la instancia, establece LOCALDB_DATABASE y deja LOCALDB_MDF sin establecer. Para adjuntar un archivo de base de datos existente, establece ambos valores. Por ejemplo, en PowerShell:

$env:LOCALDB_DATABASE = 'myData'
$env:LOCALDB_MDF = 'C:\Data\myData.mdf'

Utiliza un archivo de base de datos preparado para este propósito, no un archivo que aún esté adjunto a otra instancia que siga en ejecución. Conceda a la cuenta de Windows acceso a los archivos de base de datos y a su directorio. AttachDBFileName no crea un archivo MDF que falte, no migra una base de datos ni resuelve una versión incompatible del archivo de la base de datos. Una conexión registra la base de datos en la instancia; al cerrar PHP, esta no se desconecta ni se elimina. Comprueba la ruta de conexión de cada API desde un estado desconectado si necesitas verificar ambas de forma independiente.

La barra inversa de la cadena del servidor se escapa en cadenas de comillas simples de PHP como \\. Las cadenas entre comillas dobles de PHP también interpretan barras invertidas y variables, por lo que el programa PDO construye deliberadamente la cadena de instancia. Ambos programas escapan el nombre de la base de datos para la conexión, al tiempo que conservan el nombre original para la validación y la comprobación de resultados. También comprueban la ruta real del sistema de archivos antes de aplicar el escape al valor del archivo adjunto. Para cada valor de conexión, duplican los corchetes de cierre y encierran el valor entre corchetes. SQLSRV exige que se aplique el escape incluso a las opciones de cadena proporcionadas en su matriz de conexión. Establece LOCALDB_DATABASE y LOCALDB_MDF con el nombre y la ruta reales correspondientes, sin añadir ni duplicar llaves por tu cuenta.

Estas conexiones utilizan una instancia local, no un servidor remoto. Para SQL Server remoto, Azure SQL Database, Azure SQL Managed Instance, Azure Synapse Analytics, base de datos SQL en Fabric o Warehouse en Fabric, utiliza el endpoint real del servicio. Establece la autenticación, el cifrado y la validación de certificados de forma explícita. Para más información, consulta Conexión al servidor.

Diagnosticar problemas de cuentas e instancias

También puedes gestionar las bases de datos de una instancia de LocalDB desde la línea de comandos con sqlcmd, sqlcmd -S "(localdb)\MSSQLLocalDB"por ejemplo. Una instancia de LocalDB que posee tu cuenta interactiva de Windows no concede automáticamente acceso a la identidad de un pool de aplicaciones de Internet Information Services (IIS). Comprueba la propiedad de la instancia y los permisos del archivo al cambiar la cuenta que ejecuta PHP. Para más información, consulta SQL Server Express LocalDB.

El inicio de LocalDB y la propiedad por usuario pertenecen a SQL Server LocalDB y a Windows. Las extensiones PHP ofrecen opciones de conexión a través de ODBC. No añadas credenciales SQL ni opciones de Microsoft Entra para compensar un problema de propiedad de una instancia.

Contenido relacionado

• Conexión al servidor
• SQL Server Express LocalDB