Test-DbaConnection to polecenie modułu dbatools sprawdzające dostępność i parametry połączenia z instancją.
Test-DbaConnection jako test połączenia z SQL Server
Test-DbaConnection to polecenie modułu PowerShell dbatools przeznaczone do sprawdzania łączności z instancją Microsoft SQL Server oraz zebrania informacji potrzebnych do oceny połączenia. Nie służy do testowania dowolnych baz danych ani serwerów PostgreSQL, MySQL czy Oracle. Jego zakres dotyczy SQL Server i środowiska, z którego uruchamiany jest PowerShell.
Polecenie przyjmuje nazwę komputera, instancji lub adres SQL Server, na przykład Test-DbaConnection -SqlInstance sql01, Test-DbaConnection -SqlInstance 'sql01\PROD' albo Test-DbaConnection -SqlInstance 'sql01,51433'. Dla instancji domyślnej często wystarcza sama nazwa hosta. Zapis z przecinkiem wskazuje konkretny port TCP, dlatego nie należy zastępować go dwukropkiem używanym w adresach URL.
Wynikiem jest obiekt typu PSCustomObject, zwykle jeden dla każdej sprawdzanej instancji. W zależności od dostępności SQL Server i pozostałych mechanizmów zdalnego dostępu obiekt może zawierać między innymi nazwę komputera, nazwę instancji, wersję SQL Server, status nawiązania połączenia, użyte konto, typ uwierzytelniania, schemat uwierzytelniania, port TCP oraz adres IP.
Jakie informacje zbiera polecenie
Właściwość ConnectSuccess informuje, czy udało się nawiązać połączenie z instancją. Jej wartość należy interpretować razem z pozostałymi polami, ponieważ sam nieudany test nie wskazuje jeszcze, czy przyczyną jest błędna nazwa instancji, niedostępny port, zapora sieciowa, problem DNS, brak uprawnień czy odrzucenie uwierzytelniania. Polecenie może raportować także AuthType, na przykład Windows Authentication lub SQL Authentication, oraz AuthScheme, taki jak Kerberos albo NTLM, jeśli odpowiednie dane są dostępne.
Wynik może zawierać TcpPort i IPAddress, co pomaga porównać oczekiwaną konfigurację z rzeczywistym adresem, na który rozwiązuje się nazwa. Dla instancji nazwanych port nie musi być taki sam jak standardowy port 1433, ponieważ SQL Server może korzystać z portu dynamicznego albo z portu ustalonego przez administratora. Obecność portu w raporcie nie oznacza jednak, że wszystkie usługi SQL Server są poprawnie skonfigurowane.
Oprócz testu SQL Server polecenie może zbierać informacje o środowisku lokalnym, między innymi wersji systemu Windows, PowerShell, CLR i komponentu SMO. Raportowane są również wybrane wyniki pomocniczych kontroli, takich jak rozwiązywanie nazwy DNS, odpowiedź na ping oraz dostępność PowerShell Remoting. Pola IsPingable i PSRemotingAccessible opisują inne mechanizmy niż samo połączenie z SQL Server. Zablokowany ping lub WinRM nie musi więc oznaczać, że port SQL Server jest niedostępny.
Parametry, uwierzytelnianie i interpretacja wyniku
Podstawowym parametrem jest -SqlInstance, który może wskazywać jedną lub wiele instancji SQL Server. Do przekazania poświadczeń systemu Windows służy parametr -Credential, natomiast -SqlCredential służy do poświadczeń SQL Server. Oba parametry przyjmują obiekt PSCredential, który można uzyskać interaktywnie przez Get-Credential. Hasła nie powinny być wpisywane bezpośrednio w skrypcie ani umieszczane w historii poleceń.
Przykładowe użycie może wyglądać następująco:
$cred = Get-Credential
Test-DbaConnection -SqlInstance 'sql01\PROD' -SqlCredential $cred
Parametr -SkipPSRemoting pomija sprawdzanie dostępu przez PowerShell Remoting. Jest przydatny wtedy, gdy WinRM jest wyłączony lub filtrowany przez zaporę, ale nadal potrzebny jest test połączenia SQL Server i pozostałe informacje diagnostyczne. Domyślnie dbatools stara się przechwytywać błędy i przedstawiać je w formie komunikatu możliwego do szybkiej interpretacji. Przełącznik -EnableException zmienia to zachowanie, umożliwiając obsługę wyjątków przez własny blok try/catch.
Pozytywna wartość ConnectSuccess potwierdza możliwość wykonania konkretnego połączenia z użyciem przekazanych danych, ale nie jest pełnym audytem uprawnień. Nie dowodzi również poprawności zapytań aplikacji, działania wszystkich baz, dostępności udziałów plikowych ani poprawnego działania usług zależnych od SQL Server. Przy analizie problemu warto zachować cały obiekt wyniku, a nie tylko pojedynczy komunikat tekstowy, ponieważ korelacja nazwy, adresu IP, portu, typu uwierzytelniania i statusów pomocniczych ułatwia rozdzielenie problemu sieciowego od problemu z kontem.
Praktyczne zastosowanie w diagnostyce instancji
Test-DbaConnection jest użyteczny przed uruchomieniem skryptów administracyjnych dbatools, migracji, inwentaryzacji lub zadań wykonywanych na wielu instancjach SQL Server. Można przekazać kilka celów i zapisać wyniki do pliku, aby porównać środowiska:
$wynik = 'sql01','sql02','sql03' | Test-DbaConnection
$wynik | Export-Csv .\test-polaczen.csv -NoTypeInformation
Taki raport pozwala odszukać instancje z wartością ConnectSuccess równą False, różnymi portami TCP albo innym schematem uwierzytelniania niż oczekiwany. Gdy wynik wskazuje problem, kolejnym krokiem może być niezależne sprawdzenie portu poleceniem Test-NetConnection sql01 -Port 1433, weryfikacja rozwiązywania nazwy DNS oraz sprawdzenie, czy użyta nazwa odpowiada konfiguracji SQL Server i rejestracji SPN. Test-NetConnection bada jednak dostępność portu TCP, a nie logowanie do SQL Server, dlatego nie zastępuje Test-DbaConnection.
Polecenie jest udokumentowane jako działające w środowisku Windows. Przed użyciem warto sprawdzić wersję zainstalowanego modułu i lokalną składnię przez Get-Command Test-DbaConnection oraz Get-Help Test-DbaConnection -Full, ponieważ dostępne właściwości i szczegóły działania mogą zależeć od wersji dbatools. Diagnostyka powinna być wykonywana z hosta, z którego rzeczywiście działa skrypt lub aplikacja; pomyślny test z komputera administratora nie potwierdza automatycznie, że identyczne połączenie zadziała z innej maszyny i przy użyciu innego konta.
