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 manera que a cualquier instancia nombrada, usando el formulario de nombre del (localdb)\<instance-name> servidor.

Observaciones

LocalDB se ejecuta bajo una cuenta de usuario de Windows. Los programas utilizan autenticación integrada de Windows, no 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 master se conecta por defecto 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 permite explícitamente la obtención numérica, de modo que el valor int es PHP int, coincidiendo con el resultado SQLSRV. Ambos usan UTF-8 para datos de caracteres y gestiones de sentencias de lanzamiento y conexión incluso cuando una consulta falla.

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 falta, no migra una base de datos ni resuelve una versión incompatible de un archivo de base de datos. Un archivo adjunto registra la base de datos con la instancia; cerrar PHP no la desconecta ni la elimina. Prueba la ruta de anexo de cada API desde un estado separado si necesitas verificar ambos 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 evitan el nombre de la base de datos para la conexión manteniendo el nombre original para validación y comprobación de resultados. También comprueban la ruta real del sistema de archivos antes de escapar del valor adjunto. Para cada valor de conexión, duplican los brackets de cierre y encierran el valor en brackets. SQLSRV requiere que escape incluso para opciones de cadena suministradas 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 arranque de LocalDB y la propiedad por usuario pertenecen a SQL Server LocalDB y 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