Suporte para LocalDB

Descarregar o driver PHP

O SQL Server Express LocalDB é um modo leve de instância de utilizador do SQL Server Express, disponível apenas para Windows. Ambos os drivers ligam-se a uma instância LocalDB da mesma forma que se ligam a qualquer instância nomeada, usando a forma de nome do (localdb)\<instance-name> servidor.

Observações

O LocalDB corre sob uma conta de utilizador do Windows. Os programas utilizam autenticação integrada no Windows, não autenticação Microsoft Entra. Utilize-o para desenvolvimento local do Windows quando uma instância de base de dados por utilizador se adequa ao seu fluxo de trabalho. Não é uma imagem contentor nem um serviço do Azure.

Liga-te a uma instância de LocalDB

Instala uma versão suportada do SQL Server Express LocalDB, bem como o pré-requisito ODBC e a extensão PHP que selecionares. A instalação do LocalDB não consegue carregar uma extensão PHP.

1. Executa sqllocaldb.exe i no teu terminal Windows para listar as tuas instâncias.
2. Se MSSQLLocalDB não existir, executa sqllocaldb.exe create MSSQLLocalDB.
3. Execute sqllocaldb.exe start MSSQLLocalDB, depois sqllocaldb.exe info MSSQLLocalDB para inspecionar a instância. Execute estes passos como a conta Windows que executa o programa PHP.
4. Guarda e executa um dos programas com PHP de linha de comandos. Cada um liga-se a master por defeito e verifica se o destino é realmente o LocalDB. Não é necessária uma base de dados de exemplo nem uma palavra-passe SQL.

O nome da instância é local para a máquina Windows e para a conta proprietária. Não é um nome de host DNS, porta TCP ou ligação a outro computador.

SQLSRV

Guarde este programa como connect-localdb-sqlsrv.php, e execute 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

Guarde este programa separado como connect-localdb-pdo.php, e execute 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;
}

Saída esperada com a configuração padrão:

LocalDB database: master

O SQLSRV devolve um recurso de ligação e indica falhas de ligação através de false. O PDO devolve um objeto e lança PDOException se a construção falhar. O programa PDO ativa explicitamente a busca numérica, de modo que o valor int é PHP int, correspondendo ao resultado do SQLSRV. Ambos usam UTF-8 para dados de caracteres e libertam os handles de instrução e de ligação mesmo quando uma consulta falha.

Selecione uma base de dados existente ou anexe um ficheiro

Os programas aceitam estas variáveis opcionais de processo:

Para usar uma base de dados já registada na instância, defina LOCALDB_DATABASE e deixe LOCALDB_MDF unset. Para anexar um ficheiro de base de dados existente, defina ambos. Por exemplo, no PowerShell:

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

Use um ficheiro de base de dados preparado para este propósito, não um ficheiro ainda associado a outra instância em execução. Conceda à conta do Windows acesso aos ficheiros da base de dados e ao seu diretório. AttachDBFileName não cria um ficheiro MDF em falta, não migra uma base de dados nem resolve uma versão incompatível do ficheiro da base de dados. Uma anexação regista a base de dados na instância; fechar o PHP não a desassocia nem a elimina. Testa o caminho de anexação de cada API a partir de um estado separado se precisares de verificar ambos independentemente.

A barra inversa da string do servidor é escapada nas cadeias de aspas simples do PHP como \\. As cadeias com aspas duplas do PHP também interpretam barras e variáveis, pelo que o programa PDO constrói deliberadamente a cadeia de instância. Ambos os programas escapam o nome da base de dados na ligação, mantendo o nome original para validação e verificação de resultados. Também verificam o caminho real do sistema de ficheiros antes de sair do valor anexo. Para cada valor da ligação, duplicam as chaves de fecho e envolvem o valor em colchetes. O SQLSRV requer o escape mesmo para opções de string fornecidas no seu array de ligação. Defina LOCALDB_DATABASE e LOCALDB_MDF até ao nome e caminho reais, sem adicionar ou duplicar os brackets por si próprio.

Estas ligações usam uma instância local, não um servidor remoto. Para SQL Server remoto, Base de Dados SQL do Azure, Azure SQL Managed Instance, Azure Synapse Analytics, base de dados SQL no Fabric ou Warehouse no Fabric, utilize o endpoint real do serviço. Defina explicitamente autenticação, encriptação e validação de certificados. Para mais informações, consulte Ligação ao servidor.

Diagnosticar problemas de conta e instância

Também pode gerir as bases de dados de uma instância LocalDB a partir da linha de comandos com sqlcmd, sqlcmd -S "(localdb)\MSSQLLocalDB"por exemplo. Uma instância de LocalDB que a sua conta interativa do Windows possui não concede automaticamente acesso à identidade do pool de aplicações do Serviços de Informação Internet (IIS). Verifica a propriedade da instância e as permissões do ficheiro ao mudares a conta que executa PHP. Para mais informações, consulte SQL Server Express LocalDB.

O arranque do LocalDB e a propriedade por utilizador pertencem ao SQL Server LocalDB e ao Windows. As extensões PHP fornecem opções de ligação através do ODBC. Não adicione credenciais SQL ou opções Microsoft Entra para compensar um problema de propriedade de instâncias.

Conteúdo relacionado

• Ligação ao servidor
• do SQL Server Express LocalDB