Sql Server: Descomplicando as Connection Strings

O que é uma connection string SQL Server

Em termos simples, uma connection string SQL Server é uma lista de pares chave e valor separados por ponto e vírgula. O sinal de igual liga cada palavra-chave ao seu valor, como em Database=myDataBase.

O driver lê essa cadeia assim que você a atribui à conexão. Por isso, um erro de sintaxe já gera uma exceção do tipo ArgumentException antes mesmo de qualquer tentativa de acesso ao servidor.

Outro detalhe importante: as palavras-chave não diferenciam maiúsculas de minúsculas. Ou seja, server, Server e SERVER têm o mesmo efeito.

Além disso, várias palavras-chave possuem sinônimos. Por exemplo, Server, Data Source, Address, Addr e Network Address apontam para a mesma configuração, enquanto Database e Initial Catalog também são equivalentes.

Quando um valor contém ponto e vírgula ou aspas, você precisa envolvê-lo em aspas duplas. Assim, o driver entende que aquele caractere faz parte do valor e não separa um novo parâmetro.

Conexão padrão na connection string SQL Server

A conexão padrão reúne propriedades básicas: o servidor, o nome do banco ao qual o programa deve se conectar e as informações de autenticação, ou seja, usuário e senha. Veja o formato abaixo:

Server=myServerAddress;Database=myDataBase;User Id=myUsername;Password=myPassword;

Essa estrutura recebe o nome de padrão porque atende à maior parte dos projetos. No entanto, a definição de padrão pode variar de acordo com a tecnologia de desenvolvimento ou com o serviço de dados utilizado.

Conexão confiável com segurança integrada

Nesse modo de conexão, o SQL Server autentica o usuário por meio de um token referente à identidade do Windows. Esse é o modo de autenticação padrão do SQL Server, e a Microsoft o considera mais seguro que a autenticação por usuário e senha.

Para estabelecer uma conexão confiável, basta adicionar o parâmetro Trusted_Connection à connection string SQL Server. Com isso, você permite que os usuários se autentiquem com as credenciais do Windows.

Server=myServerAddress;Database=myDataBase;Trusted_Connection=True;

O parâmetro Trusted_Connection é sinônimo de Integrated Security. Além de True e False, ele aceita yes, no e sspi, que a documentação recomenda e que equivale a True.

Um ponto merece atenção: se você informar User ID e Password junto com a segurança integrada ativa, o driver ignora usuário e senha. Nesse caso, prevalece a identidade do Windows.

Com esse recurso, você também pode atribuir permissões a grupos de usuários do sistema. Esses grupos são criados e configurados no próprio Windows e, depois, recebem acesso ao servidor de dados.

Instância nomeada na connection string SQL Server

Conectar a uma instância nada mais é que especificar, pelo nome, a instalação do banco de dados que você deseja usar. Uma única máquina pode ter várias instalações do SQL Server, e quem se conecta sem informar esse nome acessa a instância padrão.

Na propriedade Server, além do nome ou endereço do servidor, você pode declarar a instância desejada. Para isso, use uma barra invertida entre os dois nomes:

Server=myServerName\myInstanceName;Database=myDataBase;User Id=myUsername;Password=myPassword;

Para a máquina local, a documentação recomenda usar (local) ou o ponto como nome do servidor. Por exemplo, Server=.\SQLEXPRESS aponta para a instância SQLEXPRESS instalada no seu computador.

O LocalDB, versão leve do SQL Server Express voltada ao desenvolvimento, também usa essa sintaxe. Assim, a connection string SQL Server para ele fica parecida com Server=(localdb)\MSSQLLocalDB;Database=myDataBase;Trusted_Connection=True;.

Connection string SQL Server com porta diferente

Partindo da conexão padrão, existem casos em que o servidor aceita conexões apenas por uma porta diferente da habitual. No SQL Server, a porta padrão do protocolo TCP é a 1433.

Para apontar uma porta, a mudança na connection string SQL Server é pequena. Basta adicionar uma vírgula após o nome do servidor e, logo em seguida, informar a porta desejada:

Server=myServerAddress,1433;Database=myDataBase;User Id=myUsername;Password=myPassword;

Se o seu servidor escuta em outra porta, como 14330, troque apenas o número depois da vírgula. Repare que a separação usa vírgula, e não dois-pontos como em uma URL.

Você também pode forçar o protocolo TCP com o prefixo tcp:, como em Server=tcp:myServerAddress,1433. Esse formato aparece com frequência nas strings geradas pelo portal do Azure SQL Database.

Conexão via endereço IP

Nesse tipo de conexão, o exemplo clássico usa a propriedade Data Source em vez de Server para indicar onde está o banco de dados. Esse campo da connection string SQL Server pode receber o endereço IP do servidor e, por padrão, usa a porta 1433.

Caso a porta configurada seja outra, use a vírgula conforme você viu no tópico anterior. Veja o exemplo completo:

Data Source=190.190.200.100,1433;Network Library=DBMSSOCN;Initial Catalog=myDataBase;User ID=myUsername;Password=myPassword;

Criptografia e certificados na conexão

Além das propriedades mais comuns, existem parâmetros que controlam a criptografia do canal entre a aplicação e o banco. Eles ganharam importância porque o comportamento padrão da connection string SQL Server mudou nas versões recentes do driver.

O parâmetro Encrypt define se o tráfego usa TLS. No pacote Microsoft.Data.SqlClient, o valor padrão passou a ser true a partir da versão 4.0, enquanto as versões 3.x e anteriores usavam false.

Por isso, muitos projetos que funcionavam antes começaram a falhar após a atualização do pacote. Afinal, o servidor local quase sempre usa um certificado autoassinado, que o cliente não reconhece como confiável.

O parâmetro TrustServerCertificate=True resolve esse cenário em desenvolvimento. Com ele, o driver mantém a criptografia, mas deixa de validar a cadeia do certificado:

Server=localhost,1433;Database=myDataBase;User ID=myUsername;Password=myPassword;Encrypt=True;TrustServerCertificate=True;

Em produção, porém, o ideal é instalar um certificado válido no servidor e manter a validação ativa. A partir da versão 5 do driver, o valor Encrypt=Strict usa o TDS 8.0 e ignora o TrustServerCertificate, tratando-o sempre como falso.

Outros parâmetros úteis da connection string SQL Server

A connection string SQL Server aceita dezenas de palavras-chave. Algumas delas aparecem com frequência em projetos reais e merecem uma explicação rápida.

O parâmetro Connect Timeout define quantos segundos o driver espera pela conexão antes de gerar um erro. O valor padrão é 15, e a documentação sugere 30 segundos para o Azure SQL Database.

Já o Command Timeout controla o tempo de espera na execução de um comando, com padrão de 30 segundos. Ele surgiu nas versões mais novas do Microsoft.Data.SqlClient.

O Application Name identifica sua aplicação nas ferramentas de monitoramento do servidor. Dessa forma, fica muito mais fácil descobrir qual sistema abriu determinada sessão.

O MultipleActiveResultSets, também chamado de MARS, permite manter vários conjuntos de resultados ativos na mesma conexão. Por padrão, ele vem desligado.

Os parâmetros Pooling, Min Pool Size e Max Pool Size controlam o pool de conexões. O pool vem ativo por padrão e aceita até 100 conexões, o que costuma bastar para a maioria das aplicações.

Por fim, o Persist Security Info deve permanecer como false, que é o padrão. Assim, o driver não devolve a senha quando alguém lê a connection string de uma conexão já aberta.

Montando a connection string SQL Server no C#

Concatenar textos para montar a conexão é arriscado, principalmente quando parte dos valores vem do usuário. Por exemplo, alguém poderia digitar uma senha como valid;Database=otherDb para tentar acessar outro banco.

Para evitar esse tipo de injeção, a documentação recomenda a classe SqlConnectionStringBuilder. Ela valida cada valor e gera a cadeia final já no formato correto:

using Microsoft.Data.SqlClient;

// Monta a conexão de forma tipada, sem concatenar textos
var builder = new SqlConnectionStringBuilder
{
    DataSource = "localhost,1433",
    InitialCatalog = "myDataBase",
    UserID = "myUsername",
    Password = "myPassword",
    Encrypt = true,
    TrustServerCertificate = true,
    ConnectTimeout = 30
};

using var connection = new SqlConnection(builder.ConnectionString);
connection.Open();

Console.WriteLine($"State: {connection.State}");

Repare que o resultado de builder.ConnectionString é uma connection string SQL Server comum, pronta para qualquer biblioteca de acesso a dados.

Depois de abrir a conexão, lembre-se de fechá-la. O bloco using garante isso automaticamente e devolve a conexão ao pool quando o código sai do escopo.

Se você trabalha com acesso a dados em C#, vale conhecer também o artigo como criar um CRUD com Dapper. Afinal, todo acesso com Dapper começa justamente por uma conexão bem configurada.

Onde guardar a connection string

No ASP.NET Core, o lugar mais comum para a connection string SQL Server é a seção ConnectionStrings do arquivo appsettings.json. Em seguida, o método GetConnectionString lê o valor pelo nome:

{
  "ConnectionStrings": {
    "DefaultConnection": "Server=(localdb)\\MSSQLLocalDB;Database=myDataBase;Trusted_Connection=True;"
  }
}

var builder = WebApplication.CreateBuilder(args);

// Lê a chave ConnectionStrings:DefaultConnection da configuração
var connectionString = builder.Configuration.GetConnectionString("DefaultConnection")
    ?? throw new InvalidOperationException("Connection string 'DefaultConnection' not found.");

No entanto, a documentação da Microsoft é clara: senhas nunca devem ir para arquivos de configuração versionados. Durante o desenvolvimento, use o Secret Manager com o comando dotnet user-secrets set "ConnectionStrings:DefaultConnection" "...".

Em produção, prefira variáveis de ambiente, o Azure Key Vault ou, melhor ainda, identidades gerenciadas que dispensam senha. Para entender como o ASP.NET Core combina essas fontes, leia o artigo sobre o Configuration Manager do ASP.NET.

Vale lembrar ainda que, em variáveis de ambiente, o separador de dois-pontos vira dois sublinhados. Portanto, a chave fica ConnectionStrings__DefaultConnection.

Erros comuns e como evitá-los

Mesmo quem já escreveu muitas vezes uma connection string SQL Server tropeça em alguns erros clássicos.

O primeiro erro frequente é esquecer o nome da instância. Se o SQL Server foi instalado como instância nomeada, apontar apenas para o nome da máquina leva a um erro de rede ou de tempo esgotado.

O segundo é confundir a vírgula da porta com dois-pontos. Escrever localhost:1433 não funciona, porque o driver espera localhost,1433.

Outro problema clássico aparece após atualizar o pacote do driver. Nesse caso, a mensagem fala em falha no "pre-login handshake" ou em certificado não confiável, e a solução em ambiente local é o TrustServerCertificate=True visto acima.

Também é comum misturar Trusted_Connection=True com usuário e senha. Como você viu, a segurança integrada vence, e o login informado acaba ignorado.

Por fim, cuidado com contêineres. Se o banco roda em Docker, use localhost com a porta mapeada e o login sa, conforme mostra o artigo SQL Server no Docker.

Para consultar todas as palavras-chave aceitas, a referência oficial é a documentação da propriedade SqlConnection.ConnectionString. Já o site ConnectionStrings.com reúne exemplos prontos para vários drivers e cenários.

Conclusão

Neste artigo, você viu definições para os casos mais frequentes de uso da connection string SQL Server. Você também conheceu as propriedades mais comuns e outras que controlam criptografia, tempo de conexão e pool.

Se você está usando este conteúdo como material de estudo, instale uma instância de banco de dados e teste um conjunto de configurações para cada cenário. Então, compare os resultados de cada combinação e observe como o driver reage.

Com esse exercício, você passa a ler qualquer connection string SQL Server com segurança. Além disso, ganha autonomia para diagnosticar falhas de conexão sem depender de tentativa e erro.

FAQ

Qual a diferença entre Server e Data Source?

Nenhuma, pois as duas palavras-chave são sinônimas. O mesmo vale para Database e Initial Catalog.

Trusted_Connection e Integrated Security são a mesma coisa?

Sim, são sinônimos que ativam a autenticação do Windows. O valor recomendado pela documentação é sspi, equivalente a true.

Como informo uma porta diferente de 1433?

Adicione uma vírgula após o nome do servidor e, em seguida, a porta. Por exemplo, Server=myServer,14330.

Por que minha conexão quebrou após atualizar o Microsoft.Data.SqlClient?

A partir da versão 4.0, o Encrypt passou a ser true por padrão. Em desenvolvimento, adicione TrustServerCertificate=True ou instale um certificado válido no servidor.

Posso guardar a senha no appsettings.json?

Não é recomendado, porque o arquivo costuma ir para o repositório. Use o Secret Manager no desenvolvimento e variáveis de ambiente ou Key Vault em produção.