Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
SQL Server Express LocalDB é um motor SQL Server leve para desenvolvimento local no Windows. Ele roda sob a identidade do seu usuário do Windows e inicia sob demanda. O LocalDB não é um serviço de banco de dados remoto e não roda no Linux ou macOS.
Para desenvolvimento multiplataforma, use um contêiner SQL Server suportado ou um endpoint SQL remoto. Instalar o pacote NuGet Microsoft.Data.SqlClient instala o driver do cliente, não o LocalDB.
Instalar o LocalDB
Instale o LocalDB através do setup do SQL Server Express ou do Visual Studio Installer. No Visual Studio, selecione uma carga de trabalho de desenvolvimento de dados apropriada ou o componente individual do SQL Server Express LocalDB. Veja Instalação do SQL Server Express LocalDB para downloads atuais e opções de instalador.
A instalação do LocalDB fornece o motor, SQLUserInstance.dll, e a SqlLocalDB.exe utilidade de gerenciamento. Se SqlLocalDB não estiver em PATH, execute-o a partir do diretório das ferramentas instaladas do SQL Server.
Liste suas versões e instâncias instaladas:
SqlLocalDB versions
SqlLocalDB info
Conectar-se à instância automática
A instância automática é nomeada MSSQLLocalDB e pertence ao usuário atual do Windows. Use a autenticação integrada do Windows. O LocalDB não suporta autenticação Microsoft Entra.
Para um aplicativo de console .NET com Microsoft.Data.SqlClient instalado:
using Microsoft.Data.SqlClient;
string connectionString =
@"Server=(localdb)\MSSQLLocalDB;Database=master;Integrated Security=true;Encrypt=true;TrustServerCertificate=true;";
using var connection = new SqlConnection(connectionString);
await connection.OpenAsync();
using var command = new SqlCommand("SELECT DB_NAME();", connection);
Console.WriteLine(await command.ExecuteScalarAsync());
A consulta imprime master. A primeira conexão pode demorar mais porque o LocalDB cria ou inicia a instância. Se a inicialização ultrapassar o tempo de uso da conexão, inspecione o status da instância, espere a inicialização concluir e tente novamente.
Este exemplo permite o certificado de desenvolvimento local com TrustServerCertificate=true. Mantenha essa exceção restrita ao desenvolvimento local. Para um endpoint SQL remoto, use um certificado verificável e TrustServerCertificate=false; veja Criptografia e validação de certificados.
Barras invertidas em cadeias de conexão
O valor da string de conexão contém uma barra invertida entre (localdb) e o nome da instância. Escapar depende de onde você escreve o valor:
| Localidade | Valor do servidor |
|---|---|
| Texto simples, configuração em XML ou uma cadeia de caracteres entre aspas simples no PowerShell. | (localdb)\MSSQLLocalDB |
| Cadeia de caracteres textual em C#. | @"(localdb)\MSSQLLocalDB" |
| uma cadeia de caracteres comum em C# ou uma string no formato JavaScript Object Notation (JSON). | "(localdb)\\MSSQLLocalDB" |
Não copie barras invertidas duplas do C# para uma cadeia de conexão em texto simples.
Instâncias nomeadas e compartilhadas
Use uma instância nomeada quando desejar usar uma instância de mecanismo local separada para um aplicativo. Crie isso antes de conectar:
SqlLocalDB create SqlClientDev
SqlLocalDB start SqlClientDev
SqlLocalDB info SqlClientDev
Conecte-se usando esta cadeia de conexão em texto sem formatação:
Server=(localdb)\SqlClientDev;Database=master;Integrated Security=true;Encrypt=true;TrustServerCertificate=true;
Usuários diferentes de Windows podem ter instâncias privadas com o mesmo nome. O nome sozinho não identifica a instância de outro usuário.
Uma instância compartilhada possui um alias visível para outros usuários no mesmo computador. Um administrador deve configurar o compartilhamento, e outros usuários precisam de um login apropriado para Windows ou SQL. Compartilhar não concede permissões ao banco de dados automaticamente. Use o namespace compartilhado:
Server=(localdb)\.\<shared_instance>;Database=<database>;Integrated Security=true;Encrypt=true;TrustServerCertificate=true;
Compartilhe uma instância de desenvolvimento somente de forma intencional. Revise o acesso local a arquivos e permissões ao banco de dados. Veja Instâncias Compartilhadas do LocalDB.
Comentários
Use AttachDBFilename para anexar um arquivo de banco de dados existente que o dono da instância possa acessar. Além disso, especifique um nome de banco de dados:
Server=(localdb)\MSSQLLocalDB;Database=<database>;AttachDBFilename=C:\Data\<database>.mdf;Integrated Security=true;Encrypt=true;TrustServerCertificate=true;
Use um caminho absoluto de arquivo ou um valor configurado |DataDirectory| adequadamente.
AttachDBFilename não cria um arquivo de banco de dados ausente. O motor deve suportar a versão do arquivo do banco de dados, e outra instância não pode ter o arquivo aberto.
Se você omitir Database ao anexar um arquivo, o banco de dados é removido da instância do LocalDB quando o aplicativo fecha. Especifique Database quando você quer um registro persistente no banco de dados.
User Instance=true não é válido para o LocalDB. Não use MultiSubnetFailover=true com o LocalDB; sua conexão local com nome de pipe não é um endpoint de failover do Protocolo de Controle de Transmissão (TCP).
Proteja o banco de dados e os arquivos de log com permissões de arquivos do Windows. Uma pessoa que pode copiar um arquivo de banco de dados não protegido pode potencialmente anexá-lo a uma instância que controla. Permissões SQL não substituem a proteção do sistema de arquivos.
Criar programaticamente uma instância nomeada
Aplica-se a: .NET Framework
Para uma aplicação do .NET Framework, declare uma instância nomeada e sua versão instalada do motor LocalDB na system.data.localdb seção de app.config. Registre o tipo de seção de configuração Microsoft.Data.LocalDBConfigurationSection do assembly Microsoft.Data.SqlClient e, em seguida, adicione a instância em localdbinstances.
Compare o nome Server=(localdb)\<instance> da instância com a entrada de configuração e use uma versão do motor LocalDB instalada no computador. Não copie uma versão antiga do assembly do driver ou do mecanismo para um novo aplicativo.
O .NET moderno não usa essa seção de configuração para criar instâncias. Use SqlLocalDB durante a configuração do desenvolvedor ou a API de gerenciamento do LocalDB quando uma aplicação precisa gerenciar uma instância.
Limitations
O LocalDB roda com as permissões do dono da instância. É destinado ao desenvolvimento local, não a um serviço de produção compartilhado.
- O LocalDB é exclusivo para Windows. Uma conexão LocalDB em rede gerenciada em uma plataforma não Windows gera
PlatformNotSupportedException. - O gerenciamento remoto não é suportado.
- O uso de FILESTREAM e de assinante de replicação de mesclagem não é compatível.
- O Service Broker suporta apenas filas locais.
- Os limites de tamanho e recursos do banco de dados seguem o mecanismo SQL Server Express instalado, não a versão do pacote SqlClient.
| Engine | Capacidade computacional máxima por instância | Pool máximo de buffer em megabytes (MB) | Tamanho máximo do banco de dados relacional em gigabytes (GB) |
|---|---|---|---|
| SQL Server 2022 Express LocalDB. | Menor que 1 soquete ou 4 núcleos. | 1.410 MB. | 10 GB. |
| SQL Server 2025 Express LocalDB. | Menor que 1 soquete ou 4 núcleos. | 1.410 MB. | 50 GB. |
Veja os limites de edição para SQL Server 2022 e SQL Server 2025. Os testes com o LocalDB não testam a autenticação do Microsoft Entra, a validação remota de certificados TLS, o failover do grupo de disponibilidade nem as limitações dos serviços de nuvem. Teste-os separadamente no ambiente de implantação pretendido.