PathName()

PathName() to funkcja zwracająca ścieżkę do pliku FILESTREAM, wykorzystywaną przy dostępie przez API systemu plików.

PathName() w mechanizmie FILESTREAM

PathName() jest metodą używaną w Microsoft SQL Server dla wartości przechowywanych w kolumnie typu varbinary(max) z atrybutem FILESTREAM. Zwraca logiczną ścieżkę systemu plików wskazującą na konkretny obiekt binarny zapisany przez SQL Server w magazynie FILESTREAM. Nie jest to zwykła ścieżka do pliku, którą można samodzielnie odczytać z katalogu danych bazy ani bezpośredni adres fizycznego pliku w systemie NTFS.

Metoda jest wywoływana na kolumnie FILESTREAM powiązanej z konkretnym wierszem. Przykładowa postać zapytania to SELECT Dokument.PathName() FROM dbo.Pliki WHERE Id = 1;, gdzie Dokument oznacza kolumnę binarną FILESTREAM. Wynik ma typ nvarchar(4000). Jeżeli wskazana wartość jest równa NULL albo kolumna nie ma właściwości FILESTREAM, metoda nie dostarcza użytecznej ścieżki FILESTREAM.

Ścieżka logiczna a fizyczny magazyn danych

Wartość zwracana przez PathName() służy jako identyfikator lokalizacji logicznej dla dostępu do danych przez interfejs systemu plików. SQL Server kontroluje sposób mapowania tej ścieżki na plik przechowywany w kontenerze FILESTREAM. Z tego powodu nie należy traktować wyniku jako zwykłego pliku przeznaczonego do otwierania funkcjami Win32, kopiowania w Eksploratorze Windows albo modyfikowania bez udziału mechanizmów SQL Server.

FILESTREAM łączy relacyjny model SQL Server z przechowywaniem dużych obiektów binarnych w systemie plików. Wiersz tabeli nadal zawiera metadane i powiązanie z obiektem, natomiast sama zawartość może znajdować się poza typowymi stronami danych bazy. PathName() pozwala uzyskać ścieżkę potrzebną w scenariuszu strumieniowego dostępu do obiektu, ale nie zastępuje operacji odczytu wykonywanej przez SQL Server ani nie ujawnia użytkownikowi wewnętrznej organizacji kontenera FILESTREAM.

Ścieżka może mieć postać specjalnego adresu obsługiwanego przez usługę FILESTREAM, a jej poprawność zależy od konfiguracji FILESTREAM, udziału systemu plików oraz identyfikatora bazy i wiersza. Zmiana nazwy tabeli, przeniesienie bazy lub odtworzenie jej z kopii nie powinny być obsługiwane przez ręczne modyfikowanie zwróconego tekstu. Aplikacja powinna pobierać aktualną wartość PathName() z bieżącego wiersza.

Powiązanie PathName() z OpenSqlFilestream

Najważniejsze zastosowanie PathName() polega na przekazaniu zwróconej ścieżki do funkcji OpenSqlFilestream. Ta funkcja udostępnia dane FILESTREAM jako strumień systemu plików, lecz wymaga dodatkowego kontekstu transakcji. Aplikacja musi najpierw rozpocząć transakcję, pobrać ścieżkę przez PathName(), uzyskać token kontekstu transakcji za pomocą mechanizmu SQL Server, a następnie przekazać te informacje do OpenSqlFilestream.

Sam tekst zwrócony przez PathName() nie zapewnia dostępu do zawartości. Próba otwarcia go bez odpowiedniego tokenu transakcji może zakończyć się błędem dostępu albo odrzuceniem żądania przez usługę FILESTREAM. Token wiąże operację systemu plików z konkretną transakcją SQL Server i pomaga zachować spójność między odczytem metadanych wiersza a strumieniowym odczytem danych binarnych.

Transakcja ma znaczenie także wtedy, gdy aplikacja wykonuje zapis. Odczytanie PathName() dla jednego wiersza, zakończenie transakcji, a następnie próba użycia ścieżki w oderwaniu od tego kontekstu nie jest równoważne z poprawnym użyciem FILESTREAM. Procedura powinna zachować kolejność wymaganą przez API: identyfikacja wiersza, pobranie ścieżki, uzyskanie kontekstu transakcji, otwarcie strumienia i zamknięcie go przed zakończeniem transakcji.

Weryfikacja błędów przy pracy z PathName()

Diagnozę problemu warto rozpocząć od sprawdzenia definicji tabeli i kolumny. Należy potwierdzić, że kolumna ma typ varbinary(max) FILESTREAM, tabela posiada wymagany klucz ROWGUIDCOL oraz że baza i instancja SQL Server mają włączoną obsługę FILESTREAM. Samo przechowywanie danych binarnych w kolumnie varbinary(max) bez atrybutu FILESTREAM nie tworzy środowiska, w którym PathName() może pełnić swoją funkcję.

Jeżeli metoda zwraca NULL, trzeba sprawdzić wartość kolumny oraz identyfikator wiersza. Jeżeli ścieżka jest zwracana, ale OpenSqlFilestream nie może otworzyć strumienia, należy przeanalizować zakres transakcji, poprawność tokenu, uprawnienia konta oraz konfigurację udziału FILESTREAM. Nie należy naprawiać takiego problemu przez ręczną zmianę ścieżki lub dostęp do katalogu kontenera. W praktyce istotne jest także rozróżnienie błędu SQL Server od błędu warstwy systemu plików: PathName() może działać prawidłowo, podczas gdy problem wystąpi dopiero przy autoryzacji albo otwieraniu strumienia.

W środowisku produkcyjnym należy dodatkowo kontrolować obsługę wyjątków i zamykanie uchwytów strumieniowych. Pozostawienie otwartego uchwytu lub zbyt długie utrzymywanie transakcji może powodować blokady i niepotrzebne obciążenie. PathName() powinno być traktowane jako element większego przepływu FILESTREAM, a nie jako samodzielna metoda do pobierania fizycznego pliku z dysku.