Konfiguracja połączeń ODBC z Microsoft SQL

Skonfiguruj połączenie ODBC, wybierając, gdzie przechowywać jego ustawienia, z którą bazą danych się połączyć, jak się uwierzytelniać oraz jak chronić połączenie. Dodawaj ustawienia routingu, odzyskiwania lub specyficzne dla aplikacji tylko wtedy, gdy wdrożenie ich wymaga.

Ten przewodnik wyjaśnia te opcje dla sterownika Microsoft ODBC dla SQL Server na systemach Windows, Linux i macOS. Sterownik ODBC 18 jest obecną główną wersją; Sterownik ODBC 17 pozostaje obsługiwaną wersją docelową. Przykłady używają sterownika 18 i wskazują ustawienia różniące się w sterowniku 17. Użyj odwołania do słowa kluczowego i atrybutu , aby wyszukać każde akceptowane słowo kluczowe, wartość i platformę.

Wybierz metodę połączenia

parametry połączenia dostarcza sterownikowi pary keyword=value;. Nazwa źródła danych (DSN) przechowuje ustawienia połączenia oddzielnie, aby aplikacja mogła odwoływać się do nich po nazwie. Obie metody używają tego samego sterownika, metod uwierzytelniania oraz uprawnień bazy danych.

Method Kiedy należy go używać Co dostarcza aplikacja
Bez DSN Zachowaj konfigurację wraz z aplikacją, na przykład w konfiguracji wdrożeniowej lub kontenerze. Nie musisz tworzyć DSN dla każdego klienta. Driver, Server, Database, uwierzytelnianie i inne ustawienia połączenia. Sterownik musi być nadal zainstalowany.
DSN użytkownika Skonfiguruj aplikację desktopową dla jednego użytkownika systemu operacyjnego lub aplikację, która wymaga nazwanego źródła danych. DSN=<data_source_name> oraz wszelkie ustawienia podane podczas połączenia, w tym dane uwierzytelniające. Tylko aplikacje tego użytkownika mogą korzystać z DSN użytkownika.
System DSN Pozwól aplikacjom działającym pod różnymi tożsamościami, takimi jak konto usługi, korzystać z konfiguracji na poziomie maszyny. DSN=<data_source_name> oraz ustawienia czasu połączenia. Proces musi mieć dostęp do DSN systemu oraz jego sterownika.
Plik DSN Użyj aplikacji, która oczekuje ustawień połączenia w pliku .dsn . FileDSN=<file_path> oraz ustawienia podczas nawiązywania połączenia. Plik nie instaluje sterownika ani nie czyni swoich ścieżek przenośnymi między systemami operacyjnymi.

Użyj jednej metody wyboru dla każdego połączenia. Nie łącz DSN, Driver i FileDSN, aby spróbować zmienić sterownik DSN. Usługa nie korzysta automatycznie z DSN interaktywnego użytkownika.

W aplikacjach natywnych akceptuje SQLConnect DSN oraz oddzielne argumenty identyfikatora użytkownika i hasła. SQLDriverConnect akceptuje parametry połączenia, w tym formy DSN i bez DSN. Aplikacje i frameworki korzystające z ODBC decydują, jakie pola wejściowe udostępniają. Postępuj zgodnie z interfejsem konfiguracyjnym aplikacji, zamiast zakładać, że akceptuje ona każde słowo kluczowe ODBC jako opcję wiersza poleceń.

Rozpocznij od parametry połączenia

Najpierw wybierz typ połączenia, a następnie w kolejnych sekcjach wybierz uwierzytelnianie i wszelkie dodatkowe opcje. Te przykłady wykorzystują uwierzytelnianie SQL. Nie zachowuj UID, PWDani Authentication=SqlPassword podczas przełączania na niekompatybilną metodę uwierzytelniania.

Zastąp <server>, <database>, <user_id> i <password> własnymi wartościami. Dla Azure SQL Database użyj <server>.database.windows.net jako nazwy hosta. Przykłady używają portu protokołu kontroli transmisji (TCP) 1433; zastąp go portem skonfigurowanym dla Twojego punktu końcowego.

Połącz się bez DSN

Podaj bezpośrednio nazwę zainstalowanego sterownika oraz ustawienia połączenia:

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

Dla sterownika 17 zamień nazwę sterownika na ODBC Driver 17 for SQL Server. Pozostałe ustawienia w tym przykładzie działają z obiema głównymi wersjami.

Połącz się za pomocą DSN

Po utworzeniu DSN podaj jego nazwę oraz ustawienia uwierzytelniania aplikacji:

DSN=MSSQLTest;UID=<user_id>;PWD=<password>;Authentication=SqlPassword;Encrypt=yes;TrustServerCertificate=no;

DSN wybiera sterownik, serwer i bazę danych. Przykład powtarza ustawienia zabezpieczeń w sposób jawny, aby aplikacja żądała tej samej ochrony przy użyciu obu formularzy połączenia.

Nie zapisuj prawdziwych haseł w DSN, pliku DSN, odbc.ini, pliku źródłowym ani w poleceniu powłoki. Pobieraj sekrety za pomocą mechanizmu zarządzania poświadczeniami aplikacji i podawaj je przy nawiązywaniu połączenia. Traktuj każdy parametry połączenia zawierający hasło, token lub sekret magazynu kluczy jako dane wrażliwe, w tym w logach i przechwytach diagnostycznych.

Wybierz sterownik, serwer i bazę danych

Te ustawienia decydują o tym, co aplikacja ładuje i gdzie się łączy.

Setting Kiedy i jak go używać
Driver Wybierz zainstalowany sterownik według jego zarejestrowanej nazwy dla połączenia bez DSN. Sterowniki 17 i 18 mają różne nazwy i mogą być instalowane obok siebie. Instalacja sterownika 18 nie przekierowuje połączenia, które wyraźnie wybiera sterownik 17.
Server=tcp:<server>,1433 Użyj znanego punktu końcowego TCP i portu. Przecinek oddziela nazwę hosta od portu. Linux i macOS obsługują tylko TCP. Jawnie określony port eliminuje zależność od wykrywania nazwanych instancji.
Server=<server>\<instance> Połącz się z nazwaną instancją SQL Server, gdy dostępne jest wykrywanie instancji. W systemach Linux i macOS wymaga to sterownika w wersji 17.4 lub nowszej, w tym sterownika 18. Jeśli odnajdywanie jest niedostępne, pobierz port TCP instancji i użyj formy z jawnym portem.
Database=<database> Świadomie wybierz początkową bazę danych, szczególnie w przypadku użytkownika samodzielnej bazy danych lub aplikacji, która nie może zależeć od domyślnej bazy danych logowania. To ustawienie nie tworzy bazy danych ani nie przyznaje dostępu.
Address lub Addr Utrzymuj aplikację korzystającą z osobnego adresu sieciowego. Unikaj określania powodującego konflikt Server; używaj jednego celowego punktu końcowego zamiast polegać na precedencji między nazwami.
Network lub Net Utrzymuj konfigurację Windows, która jawnie wybiera bibliotekę sieciową. Preferuj tcp: prefiks serwera dla połączenia TCP międzyplatformowego. Nie łącz prefiksu protokołu z konfliktowym wyborem sieci.

Alias serwera, nazwa instancji, nazwa hosta systemu nazw domen (DNS) oraz port nie są wymienne. Użyj nazwy DNS odpowiadającej certyfikatowi dla zaszyfrowanego połączenia zdalnego. Adres protokołu internetowego (IP) nie eliminuje niezgodności nazwy certyfikatu.

Dla Azure SQL Database i innych usług zarządzanych użyj opublikowanego punktu końcowego usługi. Dla grupy dostępności użyj jej listenera, gdy chcesz przełączanie awaryjne lub routing tylko do odczytu, zamiast na stałe kodować nazwę hosta repliki.

Wybieranie uwierzytelniania

Uwierzytelnianie określa, która tożsamość się łączy. Nie przyznaje tej tożsamości uprawnień do bazy danych i nie zastępuje ustawień szyfrowania.

Method Ustawienia połączenia Kiedy go stosować i wymagania wstępne
Uwierzytelnianie SQL Authentication=SqlPassword, UIDi PWD. Serwer docelowy włącza uwierzytelnianie SQL i masz login SQL lub użytkownika bazy danych z hasłem. Zarówno sterownik 17, jak i sterownik 18 obsługują tę formę. UIDto nazwa użytkownika SQL, a nie konto Microsoft Entra ID.
Zintegrowane uwierzytelnianie systemu Windows Trusted_Connection=yes; pominąć UID i PWD. Użyj tożsamości Windows procesu dla zasobu docelowego skonfigurowanego do Windows authentication. Na systemie Linux i macOS skonfiguruj Kerberos i uzyskaj bilet dla tożsamości aplikacji. To nie jest uwierzytelnianie zintegrowane z Microsoft Entra.
Zintegrowane uwierzytelnianie Microsoft Entra Authentication=ActiveDirectoryIntegrated; pomiń dane uwierzytelniające SQL. Użyj istniejącej tożsamości Windows lub Kerberos w konfiguracji Microsoft Entra obsługującej zintegrowane uwierzytelnianie. Linux i macOS wymagają sterownika w wersji 17.6 lub nowszej, w tym sterownika 18.
Interakcyjne uwierzytelnianie Microsoft Entra Authentication=ActiveDirectoryInteractive; pomiń PWD. Osoba może wykonać logowanie i uwierzytelnianie wieloskładnikowe. Obsługiwane na Windows, w tym sterownik Driver 17.1 i nowsze wersje. Dla sterowników od 17.1 do 17.7 podaj nazwę użytkownika Microsoft Entra w UID. Sterownik 17.8 i nowsze, w tym sterownik 18, pozwalają pominąć UID. Nie wybieraj tej metody dla usługi bezobsługowej.
Tożsamość zarządzana firmy Microsoft Entra Authentication=ActiveDirectoryMsi. Uruchom na hoście, który udostępnia obsługiwany punkt końcowy zarządzanej tożsamości. Tożsamość przypisana przez system nie wymaga UID. Tożsamość przypisana przez użytkownika wymaga UID z identyfikatorem odpowiednim dla tego hosta. Dostępne w wersjach sterownika 17.3.1.1 i nowszych, w tym sterowniku 18.
Microsoft Entra service principal Authentication=ActiveDirectoryServicePrincipal; UID to identyfikator klienta aplikacji, a PWD jest jej sekretem klienta. Aplikacja bezobsługowa używa tożsamości aplikacji Microsoft Entra tam, gdzie tożsamość zarządzana nie jest odpowiednia. Dostępne w wersjach sterownika 17.7 i nowszych, w tym sterowniku 18. Chroń i rotuj sekret klienta.
Token dostępu Microsoft Entra dostarczany przez aplikację Ustaw SQL_COPT_SS_ACCESS_TOKEN atrybut połączenia przed połączeniem. Aplikacja sama pobiera token. Jest to atrybut interfejsu programowania aplikacji (API), a nie słowo kluczowe parametry połączenia. Pomiń UID, PWD, Trusted_Connection, oraz Authentication z konfiguracji połączenia.

Wybierz metodę Microsoft Entra tylko wtedy, gdy system docelowy ją obsługuje i skonfigurowałeś dostęp tożsamości do bazy danych. Metoda obsługiwana przez sterownik nie zawsze jest dostępna w każdym wdrożeniu SQL Server lub zarządzanej usłudze. Aby dowiedzieć się, jak skonfigurować identyfikatory zarządzanej tożsamości specyficzne dla hosta oraz ograniczenia platformy, zobacz Użyj Microsoft Entra ID ze sterownikiem ODBC oraz Użyj uwierzytelniania zintegrowanego na Linux i macOS.

Nie łącz Trusted_Connection=yes z wartością Authentication. Nie umieszczaj tokenu dostępu w PWD. Podczas zmiany metody uwierzytelniania DSN usuń niekompatybilne poświadczenia i atrybuty aplikacji oraz zmień słowo kluczowe.

ActiveDirectoryPassword używa nazw użytkowników i haseł Microsoft Entra i jest wycofana. Nie wybieraj go do nowej aplikacji. Wybierz metodę odpowiednią dla użytkownika interaktywnego lub tożsamości obciążenia.

Konfiguruj szyfrowanie i walidację certyfikatów

Użyj Encrypt=yes;TrustServerCertificate=no do połączenia Transport Layer Security (TLS), które weryfikuje certyfikat serwera za pomocą sterownika 17 lub sterownika 18. Klient musi ufać wystawiającemu urzędowi certyfikacji, a certyfikat musi odpowiadać oczekiwanej nazwie serwera.

Configuration Kiedy należy go używać Zachowanie sterownika 17 i sterownika 18
Encrypt=yes;TrustServerCertificate=no Wymagaj szyfrowania i zwykłej weryfikacji certyfikatów. Obsługiwane przez obie główne wersje. Sterownik 18 również przyjmuje mandatory jako synonim yes.
Encrypt=strict Wymagaj szyfrowania Tabular Data Stream (TDS) 8.0 w połączeniu z punktem końcowym, który je obsługuje. Tylko sterownik 18. Sterownik weryfikuje certyfikat i ignoruje TrustServerCertificate. Driver 17 nie ma odpowiednika.
Encrypt=yes;TrustServerCertificate=yes Celowo zatwierdzony wyjątek, który szyfruje ruch bez zwykłej weryfikacji certyfikatu. Nie używaj go jako standardowego sposobu rozwiązania problemu z certyfikatem. Nie potwierdza, że klient rozmawia z właściwym serwerem. Nie wyłącza walidacji w trybie Strict.
Encrypt=no Utrzymuj konfigurację, która nie wymaga pełnego szyfrowania sesji od klienta. To nie jest wartość bazowa dla zdalnych połączeń. Sterownik 18 również akceptuje optional. Serwer nadal może wymagać szyfrowania.

Sterownik 18 domyślnie żąda szyfrowania. Sterownik 17 zazwyczaj domyślnie nie żąda go, ale niepuste Authentication ustawienie lub dostarczony token dostępu zmieniają domyślne szyfrowanie sterownika 17. Ustaw Encrypt jawnie, zamiast polegać na domyślnych ustawieniach zależnych od uwierzytelniania.

Dla zwykłych, nieścisłych połączeń z Encrypt=no i TrustServerCertificate=no, żądanie szyfrowania tylko serwera powoduje walidację certyfikatu przez sterownik 18, ale nie wybiera normalnej walidacji certyfikatu w sterowniku 17. Nie polegaj wyłącznie na szyfrowaniu wymaganym przez serwer, aby uzyskać takie samo zachowanie walidacji w obu sterownikach. Pełną interakcję z ustawieniami serwera znajdziesz w tabelach zachowań szyfrowania.

Wybierz oczekiwaną tożsamość certyfikatu

Większość aplikacji wymaga jedynie zaufanego certyfikatu i prawidłowej nazwy Server. Użyj dodatkowych słów kluczowych certyfikatów dla konkretnego wymogu wdrożenia:

Keyword Kiedy należy go używać Zastosowanie i limity
HostnameInCertificate Wdrożenie wymaga, aby oczekiwana nazwa hosta certyfikatu była inna niż punkt końcowy połączenia, na przykład skonfigurowany alias. Tylko Driver 18. Nie buduje zaufania wobec niezaufanego organu wydającego. Jest ignorowany, gdy ServerCertificate jest używany.
ServerCertificate Dopasuj jawnie dostarczony plik certyfikatu serwera zamiast zwykłej weryfikacji łańcucha certyfikatów i nazw hosta. Sterownik 18.1 i nowsze wersje, tylko z Encrypt=strict. Użyj certyfikatu Privacy Enhanced Mail (PEM) lub certyfikatu Distinguished Encoding Rules (DER). Certyfikat musi dokładnie się zgadzać, a daty ważności są nadal sprawdzane. Zaplanuj, jak rozdystrybuować zamiennik przed rotacją certyfikatu serwera.
ClientCertificate i ClientKey Użyj specjalistycznego mechanizmu uwierzytelniania certyfikatów dla połączeń loopback z SQL Server on Linux. Nie są to ogólne substytuty uwierzytelniania SQL ani uwierzytelniania Microsoft Entra i nie są to ustawienia zaufania certyfikatu serwera.

Rozwiązuj problemy z łańcuchem certyfikatów, nazwami hosta i plikami certyfikatów zamiast wyłączać walidację. Na Linuksie i macOS sprawdź także obsługiwaną zależność OpenSSL sterownika oraz magazyn zaufania używany przez ten proces. Aby uzyskać więcej informacji, zobacz Rozwiązywanie problemów z szyfrowaniem połączenia.

Zaufanie do certyfikatów Linux i macOS

TLS na Linuksie i macOS korzysta z OpenSSL. Uzyskaj zatwierdzone materiały zaufania i postępuj zgodnie z procedurą zarządzania magazynem zaufanych certyfikatów na swojej platformie. Certyfikat pobrany z nieuwierzytelnionego punktu końcowego nie jest wystarczającym dowodem, by mu zaufać. Sprawdź wymagania systemowe dla bibliotek obsługiwanych przez Twój sterownik i platformę.

Poniższy historyczny wykaz platform zawiera minimalne wersje OpenSSL oraz domyślne lokalizacje magazynu zaufanych certyfikatów. Nie potwierdza to bieżącego wsparcia sterownika dla tych wersji platform. Potwierdź wersję OpenSSL oraz konfigurację magazynu zaufania używaną przez zainstalowany sterownik i platformę, zanim zdecydujesz się na podaną lokalizację.

Platforma Minimalna wersja OpenSSL Domyślna lokalizacja trust-store certyfikatu
Debian 10, 11, 12 1.1.1 /etc/ssl/certs
Debian 9 1.1.0 /etc/ssl/certs
Debian 8.71 1.0.1 /etc/ssl/certs
OS X 10.11, macOS 1.0.2 /usr/local/etc/openssl/certs
Red Hat Enterprise Linux 9 3.0.1 /etc/pki/tls/cert.pem
Red Hat Enterprise Linux 8 1.1.1 /etc/pki/tls/cert.pem
Red Hat Enterprise Linux 7 1.0.1 /etc/pki/tls/cert.pem
Red Hat Enterprise Linux 6 1.0.0-10 /etc/pki/tls/cert.pem
SUSE Linux Enterprise 15 1.1.0 /etc/ssl/certs
SUSE Linux Enterprise 11, 12 1.0.1 /etc/ssl/certs
Ubuntu 22.04, 23.04 3.0.2 /etc/ssl/certs
Ubuntu 20.04 1.1.1 /etc/ssl/certs
Ubuntu 18.04 1.1.0 /etc/ssl/certs
Ubuntu 16.04 1.0.2 /etc/ssl/certs
Ubuntu 14.04 1.0.1 /etc/ssl/certs
Alpine 3.17, 3.18 3.0.1 /etc/ssl/certs

Konfiguracja trasowania i przełączania awaryjnego

Wybierz te ustawienia zgodnie z docelową topologią i obciążeniem. Nie tworzą replik, nie konfigurują nasłuchiwacza ani nie udzielają dostępu do repliki pomocniczej.

Setting Kiedy należy go używać Ważne rozróżnienie
MultiSubnetFailover=Yes Połącz się z nasłuchiwaczem grupy dostępności, instancją klastra failover, Azure SQL Database, Azure SQL Managed Instance lub bazą danych SQL w Microsoft Fabric. Sterownik próbuje nawiązać połączenia TCP z rozwiązywanymi adresami równolegle. Działa to również, gdy nazwa rozwiązuje się do jednego adresu. Jest obsługiwany przez Driver 17 i Driver 18. Nie łącz tego z Failover_Partnermirroringiem baz danych.
ApplicationIntent=ReadOnly Zażądaj połączenia dla obciążenia tylko do odczytu, w tym routingu połączeń tylko do odczytu przez odpowiednio skonfigurowany nasłuchiwacz grupy dostępności. Określ uczestniczącą bazę danych i skonfiguruj routing po stronie serwera. To ustawienie nie zastępuje uprawnień tylko do odczytu bazy danych. Wartość domyślna to ReadWrite.
TransparentNetworkIPResolution Utrzymuj lub diagnozuj starszy mechanizm awaryjny sterownika dla wielu ustalonych adresów IP. Wartości to Enabled i Disabled; domyślnie to Enabled. Nie traktuj tego jako innej pisowni MultiSubnetFailover.
IpAddressPreference Wybierz opcję preferuj IPv4, preferuj IPv6 lub kolejność adresów systemu operacyjnego dla wdrożenia z określonym wymogiem dotyczącym rodziny adresów. Sterownik 18.1 i nowsze wersje. Wartości to IPv4First, IPv6First, oraz UsePlatformDefault. To nie zmienia rekordów DNS ani nie naprawia trasowania sieciowego.
Failover_Partner Utrzymanie istniejącego połączenia dublowania bazy danych SQL Server. Tylko system Windows. To nie jest opcja detektora grupy dostępności. Sterowniki 18.7 i nowsze również akceptują alias FailoverPartner; Sterownik 17 używa Failover_Partner.

Dla połączenia grupy dostępności tylko do odczytu dodaj ApplicationIntent=ReadOnly;MultiSubnetFailover=Yes do odpowiedniego uwierzytelnionego parametry połączenia i użyj listenera w Server. Bezpośrednie połączenie z dowolnym serwerem pomocniczym nie konfiguruje routingu tylko do odczytu.

Po przełączeniu awaryjnym aplikacja może potrzebować otworzyć nowe połączenie. Aby poznać wymagania wstępne serwera i zachowanie aplikacji, zobacz Wysoka dostępność i odzyskiwanie po awarii.

Ustaw limity czasu oraz zachowanie odzyskiwania po awarii i ponownych prób

Wybierz ustawienie dla operacji, którą chcesz kontrolować. Limit czasu logowania, limit czasu zapytania, polityka odzyskiwania bezczynnego połączenia oraz polityka ponownych prób polecenia mają zastosowanie do różnych operacji.

Requirement Setting Kiedy i jak go używać
Ogranicz ustanawianie połączenia. SQL_ATTR_LOGIN_TIMEOUT, lub ConnectTimeout z wersjami Driver 18.7 i nowszymi. W aplikacjach natywnych ustaw atrybut przed połączeniem. Sterownik 17 i wcześniejsze wydania sterownika 18 wymagają atrybutu zamiast tego słowa kluczowego. Jawnie ustawiony atrybut ma pierwszeństwo przed ConnectTimeout.
Ogranicz wykonywanie instrukcji. atrybut instrukcji SQL_ATTR_QUERY_TIMEOUT. Skonfiguruj go przez API aplikacji. ConnectTimeout nie ustawia limitu czasu zapytania.
Odzyskaj połączenie kwalifikujące się do odzyskania, które przerwało się podczas bezczynności. ConnectRetryCount i ConnectRetryInterval. Obsługiwane przez aktualne wersje Driver 17 i Driver 18. Domyślne wartości to jedna próba odzyskania i 10 sekund między próbami. Wartość 0 wyłącza odzyskiwanie. Te ustawienia nie ponawiają początkowego połączenia aplikacji ani nie odtwarzają jej poleceń.
Wykryj bezczynne połączenie TCP, które już nie odpowiada. KeepAlive i KeepAliveInterval. Dostrajaj tylko pod kątem zmierzonych wymagań sieciowych. Domyślne wartości to 30 sekund i 1 sekunda. Sterownik 17.4 wprowadził wsparcie konfiguracji; obsługa parametry połączenia wymaga sterownika 17.8 i nowszych, w tym sterownika 18. Wcześniejsze obsługiwane wersje korzystają z konfiguracji DSN lub konfiguracji sterownika.
Ponownie wykonaj wybrane nieudane polecenia. RetryExec. Sterownik 18.1 i nowsze wersje. Definiuj reguły dla konkretnych błędów i poleceń dopiero po ustaleniu, czy powtarzanie operacji jest bezpieczne. To nie jest odzyskiwanie bezczynnego połączenia.

Na przykład ConnectRetryCount=3;ConnectRetryInterval=2 wybiera do trzech prób odzyskiwania stanu spoczynku z 2-sekundowym odstępem. Nie sprawia, że początkowe niepowodzenie logowania kończy się powodzeniem, ani nie ponawia przerwanego zapisu.

ConnectRetryCount akceptuje wartości od 0 do 255, a ConnectRetryInterval akceptuje wartości od 1 do 60 sekund. W sterowniku 18.7 i nowszych wersjach ConnectTimeout=30 żąda 30-sekundowego limitu czasu logowania. Domyślnie to 15 sekund; 0 żąda nieokreślonego oczekiwania. Unikaj nieograniczonego oczekiwania na logowanie, gdy aplikacja potrzebuje ograniczonego czasu odpowiedzi.

Wprowadź ograniczoną politykę ponawiania aplikacji dla przejściowych błędów podczas początkowego nawiązywania połączenia. Nie ponawiaj prób z błędnymi danymi uwierzytelniającymi, brakującymi rejestracjami sterowników ani błędami walidacji certyfikatów, jakby były one przejściowymi awariami. W przypadku ponowień poleceń uwzględnij, czy serwer mógł już zakończyć zapis przed niepowodzeniem połączenia.

Aby poznać wymagania wstępne dotyczące odzyskiwania i obsługi błędów, zobacz Odporność połączeń. Składnia reguł znajduje się w sekcji RetryExec. Utrzymuj wybory limitu czasu połączenia i zapytania spójne z całkowitym opóźnieniem, jakie Twoja aplikacja może zaakceptować.

Konfiguracja Keep-alive na Linuksie i macOS

KeepAlive kontroluje, jak często TCP wysyła pakiet, aby sprawdzić, czy nieaktywne połączenie nadal działa. KeepAliveInterval kontroluje odstęp między ponownymi transmisjami, gdy nie nadejdzie odpowiedź. Ich domyślne wartości to odpowiednio 30 sekund i 1 sekunda.

W wersjach sterownika 17.4 i nowszych możesz skonfigurować te wartości w sekcji sterownika w odbcinst.ini lub w sekcji DSN w odbc.ini. W przypadku połączenia DSN ustawienia DSN mają pierwszeństwo przed ustawieniami sterownika. Bez DSN sterownik używa swojej sekcji w odbcinst.ini. Jeśli żadna z lokalizacji nie określa wartości, sterownik używa wartości domyślnej.

Sterowniki 17.8 i nowsze, w tym sterownik 18, również akceptują KeepAlive i KeepAliveInterval w parametry połączenia. Zastąp istniejące słowo kluczowe zamiast dodawać duplikat i sprawdź priorytet konfiguracji przy łączeniu ustawień czasu połączenia z DSN.

Konfiguruj zachowanie aplikacji i danych

Używaj tych opcji, gdy aplikacja potrzebuje takiego zachowania, zamiast dodawać je do każdego parametry połączenia.

Setting Kiedy należy go używać Zachowanie i limity
APP Zidentyfikuj aplikację w informacjach o sesji po stronie serwera. Użyj stabilnej nazwy aplikacji. To nie jest uwierzytelniona tożsamość ani kontrola autoryzacji.
WSID Podaj identyfikator stacji roboczej, gdy potrzebujesz go do identyfikacji sesji. Sterowniki 18.7 i nowsze również akceptują WorkstationID. Sterownik 17 korzysta z WSID. Nie używaj nazwy podanej przez klienta jako potwierdzenia tożsamości osoby dzwoniącej.
MARS_Connection=Yes Aplikacja potrzebuje wielu aktywnych zestawów wyników (MARS) na jednym połączeniu. Wartość domyślna to No. Sterowniki 18.7 i nowsze również akceptują MultipleActiveResultSets=Yes. Sterownik 17 używa MARS_Connection.
LongAsMax=Yes Wysyłaj długie parametry znakowe lub parametry binarne jako varchar(max), nvarchar(max) lub varbinary(max) zamiast starszych typów dużych obiektów. Tylko sterownik 18; domyślnie to No. Sprawdź parametr aplikacji oraz oczekiwania dotyczące schematu przed jego zmianą.
GetDataExtensions=Yes Utrzymuj aplikację, która musi pobierać dane kolumn z SQLGetData poza kolejnością. Tylko Driver 18. Takie zachowanie kompatybilności może zwiększyć zużycie pamięci i obniżyć wydajność. Preferuj pobieranie kolumn w kolejności rosnącej w nowych aplikacjach.
Language Wybierz język wiadomości serwera sesji. Użyj języka zainstalowanego na serwerze. Nie wybiera kodowania kodu źródłowego aplikacji.
AutoTranslate Sterowanie tłumaczeniem między stronami kodowymi klienta i serwera dla danych znakowych innych niż Unicode. Wartość domyślna to Yes. Przetestuj z rzeczywistymi danymi tekstowymi aplikacji przed ich zmianą; wyłączenie tłumaczenia może zmienić sposób interpretacji znaków.
Regional Zachowaj aplikację, która oczekuje regionalnego formatowania klienta podczas konwersji danych walutowych, datowych lub czasowych na dane znakowe. Wartość domyślna to No. Nie zakładaj, że zmiana formatowania wyjściowego sprawia, że te regionalne ciągi znaków znaków są prawidłowymi parametrami wejściowymi.
AnsiNPW Zachowaj zachowanie sesji dla obsługi wartości null, dopełniania znaków i ostrzeżeń. Wartość domyślna to Yes. Przed zmianą przejrzyj odpowiednie opcje sesji Transact-SQL (T-SQL) oraz zachowanie wersji serwera.
QuotedId Kontroluj, czy sesja używa podwójnych cudzysłowów do oznaczania identyfikatorów. Wartość domyślna to Yes. Zmień go tylko wtedy, gdy T-SQL aplikacji wymaga innego QUOTED_IDENTIFIER zachowania.
ConcatNullYieldsNull Kontroluj zachowanie konkatenacji wartości null tam, gdzie serwer obsługuje ten wybór sesji. Sterownik 18.6 i nowsze wersje. Sterownik 17 nie rozpoznaje tego słowa kluczowego.
UseFMTONLY Utrzymuj ścieżkę wykrywania metadanych, która wymaga SET FMTONLY zamiast standardowego wykrywania metadanych sterownika. Wartość domyślna to No. Nie jest to konieczne dla zwykłego połączenia.

Skonfiguruj pulowanie połączeń przez Menedżera sterowników lub środowisko ODBC aplikacji. Nie kopiuj parametru innego dostawcy Pooling do parametry połączenia tego sterownika. Informacje o natywnej konfiguracji ODBC zawiera temat pulowanie połączeń Menedżera sterowników. W przypadku zachowań ponownego użycia specyficznych dla Windows zobacz Pula połączeń uwzględniająca sterownik.

Konfiguruj funkcje specjalne

Poniższe opcje wymagają konfiguracji specyficznej dla funkcji, wykraczającej poza parametry połączenia.

Settings Kiedy ich używać Co jeszcze jest potrzebne
ColumnEncryption=Enabled Odczytywanie lub zapisywanie kolumn chronionych przy użyciu funkcji Always Encrypted. Dostęp do kluczy szyfrujących kolumn przez obsługiwany magazyn kluczy. Always Encrypted chroni wartości kolumn i jest oddzielne od szyfrowania sieciowego. W przypadku połączeń enklawy użyj ustawień połączeń specyficznych dla danej funkcji.
KeystoreAuthentication, KeystorePrincipalId, oraz KeystoreSecret Uwierzytelnij sterownik przy użyciu magazynu kluczy używanego przez Always Encrypted. Tożsamość i uprawnienia magazynu kluczy. Te dane uwierzytelniające nie są danymi logowania do bazy danych. Chroń sekrety magazynu kluczy tak, jak chronisz hasło.
ServerSPN Określ nazwę główną usługi (SPN) dla wdrożenia Kerberos, które wymaga wyraźnej wartości. Aktualne wersje sterowników 17 i 18 obsługują to ustawienie na Windows, Linux i macOS. Skonfiguruj rejestrację usługi Kerberos tak, aby odpowiadała dostarczonemu SPN. SPN nie jest nazwą hosta certyfikatu TLS.
FailoverPartnerSPN Utrzymuj wyraźny SPN Kerberos dla partnera do mirroringu baz danych. Tylko w systemie Windows, z odpowiednią konfiguracją dublowania.
AttachDBFileName Użyj przepływu pracy SQL Server, który dołącza plik bazy danych. Pasująca Database nazwa, plik dostępny dla serwera oraz wymagane uprawnienia. Nie używaj go do identyfikacji istniejącej bazy danych w Azure SQL Database.
Replication=Yes Użyj połączenia, które celowo wymaga zachowania agenta replikacji. Driver 17.8 i nowsze wersje, w tym Driver 18. Zmienia zachowanie obiektów oznaczonych NOT FOR REPLICATION, w tym wyzwalaczy; nie jest to ogólna opcja wydajności.
QueryLog_On, QueryLogFile, QueryLogTime, StatsLog_On, oraz StatsLogFile Diagnozuj istniejącą aplikację Windows za pomocą zapytania sterownika lub dzienników wydajności. Tylko Windows; te ustawienia połączenia wymagają DSN. Ustaw próg wolnego zapytania za pomocą QueryLogTime, w milisekundach. Używaj kontrolowanego celu rejestrowania, odpowiednich uprawnień oraz polityki retencji. Nie traktuj logów diagnostycznych jako wolnych od wrażliwych danych.

Konfigurację i limity znajdziesz w Always Encrypted, Kerberos SPN oraz odwołanie do słów kluczowych. Niektóre natywne funkcje, takie jak dołączanie do transakcji rozproszonych, wymagają atrybutów API zamiast słowa kluczowego w parametry połączenia.

Utwórz DSN

Utwórz DSN tylko wtedy, gdy wybierzesz połączenie oparte na DSN. DSN przechowuje konfigurację; jej zapisanie nie oznacza, że aplikacja może się uwierzytelnić lub uruchomić zapytanie.

DSN użytkownika Windows

Poniższa procedura tworzy DSN użytkownika dla przykładu uwierzytelniania SQL. Dla usługi celowo wybierz System DSN i zorganizuj dostęp pod tożsamością usługi.

  1. Otwórz administratora źródła danych ODBC, który odpowiada architekturze Twojej aplikacji.

  2. Na karcie User DSN wybierz Dodaj.

  3. Wybierz sterownik ODBC 18 dla SQL Server lub sterownik ODBC 17 dla SQL Server. Wybierz Zakończ, aby otworzyć kreator sterownika.

  4. Nazwij DSN MSSQLTest. Wprowadź tcp:<server>,1433 jako serwer i wybierz Dalej.

  5. Wybierz uwierzytelnianie SQL. Wyczyść Identyfikator logowania i hasło, a następnie wybierz Dalej.

  6. Włącz opcję „Zmień domyślną bazę danych na”. Wpisz <database> bez otwierania listy bazy danych i wybierz Dalej.

  7. Dla sterownika 18 wybierz Obowiązkowe szyfrowanie połączenia. Dla sterownika 17 wybierz Użyj silnego szyfrowania danych. Pozostaw opcję Ufaj certyfikatowi serwera niezaznaczoną.

  8. Wybierz Zakończ i przejrzyj podsumowanie konfiguracji.

  9. Wybierz OK , aby zapisać DSN bez uruchamiania testu połączenia kreatora. Potwierdź, że MSSQLTest pojawia się na karcie DSN użytkownika.

Aplikacja podaje dane uwierzytelniające SQL w momencie nawiązywania połączenia. Dla innych metod uwierzytelniania i pól kreatora zobacz opcje DSN w ODBC Data Source Administrator.

Użytkownik DSN Linux lub macOS

Uruchom, odbcinst -j aby znaleźć ścieżki USER DATA SOURCES i SYSTEM DATA SOURCES dla Twojej instalacji unixODBC. Dodaj następującą sekcję do pliku użytkownika, zastępując symbole zastępcze serwera i bazy danych:

[MSSQLTest]
Driver = ODBC Driver 18 for SQL Server
Server = tcp:<server>,1433
Database = <database>
Authentication = SqlPassword
Encrypt = yes
TrustServerCertificate = no

Dla sterownika 17 zmień nazwę sterownika. Nie zapisuj PWD w tym pliku. Rejestracja odbcinst.ini sterownika i DSN w odbc.ini służą różnym celom: jedna lokalizuje bibliotekę sterowników, a druga nazywa ustawienia połączenia.

Dla systemowego DSN dodaj te same ustawienia do wskazanego pliku SYSTEM DATA SOURCES z uprawnieniami administratora. Dla usługi skonfiguruj dostęp przy użyciu tożsamości usługi.

Wartość Driver może być zarejestrowaną nazwą sterownika lub ścieżką do biblioteki sterowników określonej w szablonie instalacji. W odbc.ini, użyj zarejestrowanej nazwy bez nawiasów klamrowych ciągu połączenia. Określ port serwera w Server; Port nie jest prawidłowym słowem kluczowym DSN dla tego sterownika w systemie Linux lub macOS.

Alternatywnie, zapisz sekcję DSN w pliku szablonu i zarejestruj DSN użytkownika za pomocą następującego polecenia:

odbcinst -i -s -h -f <template_file>

Zastąp <template_file> ścieżką szablonu. Szczegóły .ini dotyczące plików i rejestracji znajdziesz w dokumentacji unixODBC. Przetestuj połączenie przez aplikację korzystającą z DSN; sama rejestracja nie nawiązuje połączenia z bazą danych.

Plikowy DSN

Używaj FileDSN=<file_path> , gdy aplikacja oczekuje źródła danych pliku. Klient nadal potrzebuje zainstalowanego sterownika, który potrafi interpretować ustawienia. Nie przechowuj danych uwierzytelniających w pliku.

SaveFile żąda, aby ustawienia połączenia zostały zapisane w pliku po pomyślnym połączeniu. Używaj go tylko wtedy, gdy aplikacja celowo tworzy plik DSN. Aby poznać zawartość plików i reguły scalania, zobacz dokumentację SQLDriverConnect.

Poznaj pierwszeństwo konfiguracji

Aplikacja może otrzymywać ustawienia z DSN, z jego parametry połączenia i z atrybutów API. Przejrzyj wszystkie trzy, gdy skuteczne połączenie różni się od oczekiwanych parametrów połączenia.

Źródło lub składnia Rule
Pisownia słów kluczowych Sterownik dopasowuje nazwy słów kluczowych bez względu na wielkość liter. Akceptowane wartości są specyficzne dla słowa kluczowego; nie zakładaj, że każda opcja logiczna akceptuje true i false.
Powtarzające się słowo kluczowe Podczas analizy opcji sterownika sterowniki Driver 17 i Driver 18 zachowują pierwsze wystąpienie rozpoznanego słowa kluczowego. Aliasy tej samej opcji nie zapewniają osobnego nadpisania. Ta reguła nie reguluje wcześniejszego wyboru sterownika ani DSN przez Menedżera Sterowników: unixODBC używa na tym etapie ostatniego wystąpienia powtórzonej wartości Driver lub DSN. Zamień istniejące wartości zamiast dołączać duplikaty i określ słowo kluczowe wyboru tylko raz.
connection string a DSN Jawne wartości parametry połączenia zazwyczaj zastępują odpowiadające pola DSN. Ustawienie RegPrecedence DSN sterownika może odwrócić to pierwszeństwo. Sprawdź go, gdy istniejący DSN zachowuje się nieoczekiwanie.
Atrybuty API Atrybuty ustawione przez aplikację mogą zmieniać skuteczną konfigurację. Sprawdź kontrakt konkretnego atrybutu, zamiast zakładać, że każdy atrybut używa tej samej reguły scalania.
Wartości w nawiasach klamrowych Umieść wartość zawierającą średnik w nawiasach klamrowych i podwaj nawias zamykający w obrębie tej wartości. Na przykład podaje Database={database;name} jedną nazwę bazy danych. Cytowanie powłoki lub języka programowania jest oddzielne od escapingu ODBC.

Utrzymuj spójność ustawień uwierzytelniania i bezpieczeństwa w całym DSN i aplikacji. Podczas zmiany sterowników zaktualizuj sterownik wybrany w DSN lub wartość Driver bez DSN, w zależności od potrzeby. W przypadku kontroli migracji zobacz Główne różnice wersji.

Sprawdź połączenie w swojej aplikacji

Testuj z użyciem rzeczywistego konta systemowego aplikacji i konfiguracji wdrożenia aplikacji. Pomyślny test kreatora DSN nie dowodzi, że usługa może zobaczyć ten sam DSN lub uzyskać te same poświadczenia.

  1. Połącz się za pomocą wybranego ciągu DSN lub ciągu połączenia bez DSN oraz zamierzonej metody uwierzytelniania.
  2. Po pomyślnym połączeniu potwierdź, który sterownik i wersję aplikacja załaduje. W kodzie natywnym używaj SQLGetInfo z SQL_DRIVER_NAME i SQL_DRIVER_VER.
  3. Uruchom zapytanie w zamierzonej bazie danych i sprawdź jego wynik. Pełny przykład aplikacji znajdziesz w sekcji Połącz z bazą danych i zapytuj ją za pomocą C++.
  4. Sprawdź szyfrowanie i wymagane zachowanie aplikacji, takie jak routing tylko do odczytu lub odzyskiwanie. Przetestuj każdy formularz połączenia, który wdrażasz niezależnie.
  5. Przechwytuj niepowodzenia bez ujawniania poświadczeń. Wartości SQLSTATE, natywne kody błędów i chronione zbieranie danych diagnostycznych znajdziesz w diagnostyce ODBC.

Jeśli połączenie się nie powiedzie, sprawdź rejestrację sterownika i widoczność DSN przed zmianą uwierzytelniania. Sprawdź punkt końcowy i dostępność przed zmianą ustawień ponownej próby. W przypadku błędu certyfikatu napraw konfigurację zaufania lub nazwy, zamiast ustawiać TrustServerCertificate=yes, aby błąd zniknął.