Início Rápido: Conecte e consulte com C++ e ODBC

Aplica-se a:SQL ServerBanco de Dados SQL do Azure

Neste quickstart, você constrói um aplicativo de console C++ no Windows, Linux ou macOS. O aplicativo se conecta a um AdventureWorksLT banco de dados usando o Microsoft ODBC Driver 18 para SQL Server, vincula um parâmetro de consulta, executa a consulta e lê as linhas de resultados.

Pré-requisitos

  • Driver Microsoft ODBC 18 para SQL Server. Instale o driver para Windows, Linux ou macOS.
  • Um compilador C++17 e os arquivos de desenvolvimento ODBC da plataforma:
    • No Windows, instale o Visual Studio 2022 ou as Ferramentas de Compilação para Visual Studio 2022 com a carga de trabalho Desenvolvimento para área de trabalho com C++. O SDK do Windows fornece os arquivos de cabeçalho ODBC e odbc32.lib.
    • No Linux, instale um compilador C++ e o pacote de desenvolvimento unixODBC para sua distribuição. O pacote fornece os cabeçalhos ODBC e libodbc.
    • No macOS, instale as ferramentas de linha de comando do Xcode e unixODBC a partir do Homebrew.
  • Um banco de dados no Banco de Dados SQL do Azure ou SQL Server que contém os AdventureWorksLT dados de exemplo. Para Banco de Dados SQL do Azure, selecione a fonte de dados de exemplo ao criar um único banco de dados. Para o SQL Server, restaure um backup AdventureWorksLT a partir dos bancos de dados de amostra do AdventureWorks.

Verifique o controlador

Confirme se o gerenciador de drivers consegue encontrar o Microsoft ODBC Driver 18 para SQL Server.

Execute este comando no PowerShell:

Get-OdbcDriver -Name "ODBC Driver 18 for SQL Server"

Cada comando deve listar ODBC Driver 18 for SQL Server. Se o driver não estiver listado, reinstale-o antes de continuar.

Configurar a conexão

A aplicação lê a cadeia de conexão completa da ODBC_CONNECTION_STRING variável de ambiente. Ele não exibe a cadeia de conexão nem a aceita como argumento de linha de comando.

Use uma cadeia de conexão do Driver 18 que seja válida para seu banco de dados e método de autenticação. O exemplo a seguir de autenticação SQL funciona no Windows, Linux e macOS quando o banco de dados permite autenticação SQL:

Driver={ODBC Driver 18 for SQL Server};Server=tcp:<server>,1433;Database=<database>;UID=<user_id>;PWD=<password>;Encrypt=yes;TrustServerCertificate=no;

Para as opções de autenticação do Microsoft Entra, veja Usar a ID do Microsoft Entra com o driver ODBC. Para todas as configurações com suporte, consulte palavras-chave e atributos de DSN e de cadeia de conexão.

O Driver ODBC 18 da Microsoft habilita criptografia por padrão. Especifique Encrypt=yes para que o requisito da aplicação seja explícito. Mantenha TrustServerCertificate=no em produção para que o driver valide o certificado do servidor. O certificado deve corresponder ao nome do servidor e encadear até uma autoridade certificadora em que o cliente confie. Para orientações de configuração, veja Falhas de validação de certificados.

Caution

TrustServerCertificate=yes ignora a validação do certificado. Use apenas para desenvolvimento local isolado enquanto você configura um certificado em que o cliente confia. Não o use em produção.

Defina a variável de ambiente sem adicionar a cadeia de conexão ao histórico do seu shell.

PowerShell para desenvolvedores abertos para VS 2022. Execute esses comandos e depois cole a cadeia de conexão no prompt:

$secureConnectionString = Read-Host "ODBC connection string" -AsSecureString
$env:ODBC_CONNECTION_STRING = [System.Net.NetworkCredential]::new(
    "", $secureConnectionString).Password
$secureConnectionString = $null

Uma variável de ambiente mantém a cadeia de conexão fora do arquivo de origem, mas o processo e seus processos filhos podem lê-la. Para aplicações de produção, use a autenticação Microsoft Entra sempre que possível e recupere segredos de um armazenamento seguro em tempo de execução.

Criar o aplicativo

  1. Crie um diretório de projeto e mude para ele:

    New-Item -ItemType Directory odbc-quickstart
Set-Location odbc-quickstart

  1. Crie um arquivo nomeado odbc-quickstart.cpp com o seguinte código:

    #ifdef _WIN32
#include <windows.h>
#endif

#include <sql.h>
#include <sqlext.h>
#include <sqltypes.h>

#include <cstdlib>
#include <iomanip>
#include <iostream>
#include <string>

std::string ReadEnvironmentVariable(const char* name)
{
#ifdef _WIN32
    char* value = nullptr;
    std::size_t length = 0;
    if (_dupenv_s(&value, &length, name) != 0 || value == nullptr)
        return {};

    std::string result(value);
    std::free(value);
    return result;
#else
    const char* value = std::getenv(name);
    return value == nullptr ? std::string{} : value;
#endif
}

void PrintDiagnostics(SQLSMALLINT handleType, SQLHANDLE handle)
{
    SQLCHAR state[6];
    SQLINTEGER nativeError;
    SQLCHAR message[SQL_MAX_MESSAGE_LENGTH];
    SQLSMALLINT messageLength;

    for (SQLSMALLINT record = 1;
         SQL_SUCCEEDED(SQLGetDiagRec(handleType, handle, record, state,
                                     &nativeError, message, sizeof(message),
                                     &messageLength));
         ++record)
    {
        std::cerr << '[' << state << "] (" << nativeError << ") "
                  << message << '\n';
    }
}

bool Succeeded(SQLRETURN result, SQLSMALLINT handleType, SQLHANDLE handle)
{
    if (SQL_SUCCEEDED(result))
        return true;

    PrintDiagnostics(handleType, handle);
    return false;
}

struct OdbcHandles
{
    SQLHENV environment = SQL_NULL_HENV;
    SQLHDBC connection = SQL_NULL_HDBC;
    SQLHSTMT statement = SQL_NULL_HSTMT;

    ~OdbcHandles()
    {
        if (statement != SQL_NULL_HSTMT)
            SQLFreeHandle(SQL_HANDLE_STMT, statement);
        if (connection != SQL_NULL_HDBC)
        {
            SQLDisconnect(connection);
            SQLFreeHandle(SQL_HANDLE_DBC, connection);
        }
        if (environment != SQL_NULL_HENV)
            SQLFreeHandle(SQL_HANDLE_ENV, environment);
    }
};

int main()
{
    std::string connectionString =
        ReadEnvironmentVariable("ODBC_CONNECTION_STRING");
    if (connectionString.empty())
    {
        std::cerr << "Set ODBC_CONNECTION_STRING before running.\n";
        return 1;
    }

    OdbcHandles handles;
    SQLRETURN result = SQLAllocHandle(
        SQL_HANDLE_ENV, SQL_NULL_HANDLE, &handles.environment);
    if (!SQL_SUCCEEDED(result))
    {
        std::cerr << "Unable to allocate an ODBC environment handle.\n";
        return 1;
    }

    result = SQLSetEnvAttr(
        handles.environment,
        SQL_ATTR_ODBC_VERSION,
        reinterpret_cast<SQLPOINTER>(SQL_OV_ODBC3_80),
        0);
    if (!Succeeded(result, SQL_HANDLE_ENV, handles.environment))
        return 1;

    result = SQLAllocHandle(
        SQL_HANDLE_DBC, handles.environment, &handles.connection);
    if (!Succeeded(result, SQL_HANDLE_ENV, handles.environment))
        return 1;

    result = SQLDriverConnect(
        handles.connection,
        nullptr,
        reinterpret_cast<SQLCHAR*>(connectionString.data()),
        SQL_NTS,
        nullptr,
        0,
        nullptr,
        SQL_DRIVER_NOPROMPT);
    if (!Succeeded(result, SQL_HANDLE_DBC, handles.connection))
        return 1;

    result = SQLAllocHandle(
        SQL_HANDLE_STMT, handles.connection, &handles.statement);
    if (!Succeeded(result, SQL_HANDLE_DBC, handles.connection))
        return 1;

    SQLINTEGER minimumProductId = 0;
    SQLLEN minimumProductIdLength = 0;
    result = SQLBindParameter(
        handles.statement,
        1,
        SQL_PARAM_INPUT,
        SQL_C_SLONG,
        SQL_INTEGER,
        10,
        0,
        &minimumProductId,
        0,
        &minimumProductIdLength);
    if (!Succeeded(result, SQL_HANDLE_STMT, handles.statement))
        return 1;

    SQLCHAR query[] =
        "SELECT TOP (5) ProductID, Name "
        "FROM SalesLT.Product "
        "WHERE ProductID > ? "
        "ORDER BY ProductID;";
    result = SQLExecDirect(handles.statement, query, SQL_NTS);
    if (!Succeeded(result, SQL_HANDLE_STMT, handles.statement))
        return 1;

    std::cout << "Product ID  Name\n"
              << "----------  ----\n";

    while (SQL_SUCCEEDED(result = SQLFetch(handles.statement)))
    {
        SQLINTEGER productId;
        SQLLEN productIdLength;
        SQLCHAR productName[256];
        SQLLEN productNameLength;

        result = SQLGetData(
            handles.statement, 1, SQL_C_SLONG, &productId,
            sizeof(productId), &productIdLength);
        if (!Succeeded(result, SQL_HANDLE_STMT, handles.statement))
            return 1;

        result = SQLGetData(
            handles.statement, 2, SQL_C_CHAR, productName,
            sizeof(productName), &productNameLength);
        if (!Succeeded(result, SQL_HANDLE_STMT, handles.statement))
            return 1;

        std::cout << std::left << std::setw(12) << productId
                  << productName << '\n';
    }

    if (result != SQL_NO_DATA)
    {
        PrintDiagnostics(SQL_HANDLE_STMT, handles.statement);
        return 1;
    }

    return 0;
}

A aplicação utiliza apenas a API padrão ODBC, então inclui os cabeçalhos do driver manager e links para a biblioteca driver-manager. A cadeia de conexão seleciona o driver Microsoft ODBC 18 para SQL Server em tempo de execução.

SQL_DRIVER_NOPROMPT impede SQLDriverConnect a abertura de um diálogo de configuração. Se a cadeia de conexão estiver incompleta, a chamada retorna um erro e a aplicação imprime todos os registros diagnósticos.

A consulta associa 0 a um parâmetro int do SQL Server, lê os cinco primeiros produtos em SalesLT.Product e obtém a ID e o nome de cada produto com SQLGetData.

Compile e execute o aplicativo

  1. Na mesma janela do PowerShell do Desenvolvedor, compile a aplicação:

    cl /std:c++17 /EHsc /W4 odbc-quickstart.cpp /link odbc32.lib

  2. Execute o aplicativo:

    .\odbc-quickstart.exe

A saída padrão da aplicação é:

Product ID  Name
----------  ----
680         HL Road Frame - Black, 58
706         HL Road Frame - Red, 58
707         Sport-100 Helmet, Red
708         Sport-100 Helmet, Black
709         Mountain Bike Socks, M

Limpe a cadeia de conexão quando terminar.

Remove-Item Env:\ODBC_CONNECTION_STRING

Conteúdo relacionado

  • Last updated on