Get-SqlInstance to polecenie modułu SqlServer PowerShell zwracające obiekt reprezentujący wskazaną instancję serwera.
Rola Get-SqlInstance w module SqlServer
Get-SqlInstance jest poleceniem PowerShell dostarczanym przez moduł SqlServer. Służy do uzyskania reprezentacji wskazanej instancji Microsoft SQL Server w postaci obiektu używanego dalej przez polecenia PowerShell i biblioteki SQL Server Management Objects, czyli SMO. Nie jest to zapytanie języka T-SQL i nie odczytuje danych z tabel. Jego zadaniem jest nawiązanie kontekstu z określoną instancją silnika oraz udostępnienie informacji o tym obiekcie.
Instancję wskazuje się zwykle nazwą serwera i instancji, na przykład localhost dla instancji domyślnej albo HOST01\SQLEXPRESS dla instancji nazwanej. W środowisku korzystającym z niestandardowego portu można użyć zapisu obejmującego port, takiego jak HOST01,51433, o ile konfiguracja SQL Server i sieci pozwala na takie połączenie. Wynik polecenia można przypisać do zmiennej, aby używać go w kolejnych operacjach administracyjnych lub diagnostycznych.
Obiekt instancji i informacje dostępne w PowerShell
Wynik Get-SqlInstance nie powinien być traktowany jak zwykły tekst zawierający nazwę serwera. Jest to obiekt opisujący połączenie z instancją i jej właściwości udostępniane przez SMO. W zależności od wersji modułu, sterowników oraz uprawnień można odczytywać między innymi nazwę instancji, nazwę serwera, wersję silnika, edycję, poziom zgodności określonych elementów administracyjnych oraz stan połączenia. Dostępne właściwości zależą także od tego, czy odczyt wymaganej informacji wymaga dodatkowego zapytania do serwera.
Przykładowe użycie może wyglądać następująco: $instance = Get-SqlInstance -ServerInstance "HOST01\SQLEXPRESS". Następnie właściwości obiektu można obejrzeć poleceniem $instance | Format-List *, a informacje o wersji lub edycji wyświetlić przez odwołanie do konkretnej właściwości zwróconej przez dany obiekt. Do bezpiecznego rozpoznania typu wyniku służą polecenia Get-Member oraz $instance.GetType().FullName. Takie sprawdzenie jest istotne, ponieważ skrypt nie powinien zakładać typu wynikowego wyłącznie na podstawie nazwy cmdletu.
Połączenie, uwierzytelnianie i typowe błędy
Skuteczne wykonanie Get-SqlInstance zależy od poprawnej nazwy celu, dostępności usługi SQL Server oraz sposobu uwierzytelniania. Przy połączeniu lokalnym można korzystać z bieżących poświadczeń systemu Windows, natomiast w innych warunkach moduł może wymagać jawnego przekazania poświadczeń za pomocą parametru -Credential. To, czy dane poświadczenia zostaną zaakceptowane, zależy od konfiguracji trybu uwierzytelniania SQL Server, konta użytkownika i uprawnień przyznanych na serwerze.
Błąd wykonania nie musi oznaczać uszkodzenia samego silnika. Przyczyną może być literówka w nazwie instancji, zatrzymana usługa SQL Server, niedostępny port TCP, wyłączony protokół TCP/IP w SQL Server Configuration Manager, problem z SQL Server Browser przy instancji nazwanej albo brak uprawnień. Jeżeli używana jest nazwa instancji zamiast portu, wykrywanie właściwego portu może zależeć od usługi SQL Server Browser. Diagnostyka powinna obejmować treść wyjątku, nazwę celu, sposób uwierzytelniania i wynik testu połączenia, a nie tylko ponowne uruchamianie tego samego polecenia.
W skryptach warto kontrolować błędy za pomocą -ErrorAction Stop i obsługi try/catch. Przykładowa konstrukcja try { $instance = Get-SqlInstance -ServerInstance "HOST01\SQLEXPRESS" -ErrorAction Stop } catch { $_.Exception.Message } pozwala odróżnić nieudane połączenie od dalszego błędu przetwarzania wyniku. Nie należy zapisywać haseł bezpośrednio w kodzie. Obiekt PSCredential powinien być przekazywany w sposób zgodny z zasadami konfiguracji danego środowiska.
Znaczenie polecenia przy sprawdzaniu instalacji SQL Server
Get-SqlInstance jest przydatne wtedy, gdy trzeba potwierdzić, z jaką instancją skrypt rzeczywiście pracuje. Ma to znaczenie na komputerze, na którym działa jednocześnie instancja domyślna i jedna lub więcej instancji nazwanych, albo gdy nazwa komputera, alias SQL Server i rzeczywisty punkt połączenia nie są takie same. Samo znalezienie usługi Windows o nazwie związanej z SQL Server nie daje jeszcze pewności, że skrypt używa właściwej instancji. Wynik cmdletu można zestawić z parametrem -ServerInstance oraz z informacjami zapisanymi w konfiguracji aplikacji.
Podczas diagnostyki należy rozdzielić trzy kwestie: wykrycie celu, uwierzytelnienie oraz uprawnienia do odczytu właściwości. Jeżeli polecenie zwraca obiekt, ale późniejsze odwołanie do bazy kończy się błędem, problem może dotyczyć nazwy bazy, praw użytkownika albo konkretnej operacji, a nie samego Get-SqlInstance. Jeżeli cmdlet nie zwraca obiektu, należy najpierw zweryfikować dostępność instancji, sposób adresowania i zgodność zainstalowanej wersji modułu SqlServer z używanymi poleceniami.
W praktyce wynik można przekazać do dalszych cmdletów modułu SqlServer, o ile dany cmdlet obsługuje obiekt wejściowy odpowiedniego typu. Przed automatyzacją warto sprawdzić składnię konkretnej wersji polecenia przez Get-Help Get-SqlInstance -Full. Dokumentacja lokalnie zainstalowanego modułu pokazuje dostępne parametry, ponieważ ich zestaw może różnić się między wydaniami. Dzięki temu można uniknąć sytuacji, w której skrypt zakłada obsługę parametru dostępnego w innej wersji modułu lub innym środowisku PowerShell.
