Odczyt danych FILESTREAM

Odczyt danych FILESTREAM odbywa się przez API systemu plików albo standardowe zapytanie do kolumny binarnej.

Dwa sposoby odczytu obiektu FILESTREAM w SQL Server

FILESTREAM w Microsoft SQL Server pozwala przechowywać dane typu varbinary(max) z atrybutem FILESTREAM w systemie plików NTFS, przy zachowaniu transakcyjnej kontroli przez silnik bazy danych. Odczyt takiej wartości może odbywać się przez standardowe zapytanie Transact-SQL, na przykład przez pobranie kolumny z tabeli poleceniem SELECT. W tym trybie SQL Server zwraca zawartość jako wartość binarną, dlatego sposób przekazania danych do aplikacji zależy od używanego sterownika, biblioteki i bufora pamięci.

Druga metoda wykorzystuje strumieniowy dostęp do pliku przez API systemu Windows. Aplikacja pobiera logiczną ścieżkę obiektu za pomocą metody PathName(), a następnie otwiera strumień funkcją OpenSqlFilestream. Ten mechanizm nie oznacza bezpośredniego wejścia do katalogu kontenera FILESTREAM. SQL Server wydaje specjalny kontekst dostępu, a system plików realizuje odczyt z zachowaniem kontroli transakcji i uprawnień.

Przygotowanie ścieżki i kontekstu transakcji

Do użycia interfejsu FILESTREAM aplikacja potrzebuje wiersza zawierającego kolumnę typu uniqueidentifier oznaczoną jako ROWGUIDCOL oraz kolumnę binarną z atrybutem FILESTREAM. Zapytanie może pobrać ścieżkę logiczną w postaci zwracanej przez PathName(), na przykład SELECT file_data.PathName(). Ścieżka ta jest przeznaczona dla interfejsu FILESTREAM i nie powinna być traktowana jak zwykła ścieżka lokalnego pliku, którą można dowolnie otworzyć funkcjami systemu plików.

Odczyt przez OpenSqlFilestream wymaga aktywnej transakcji SQL Server. Aplikacja musi uzyskać kontekst transakcji metodą GET_FILESTREAM_TRANSACTION_CONTEXT(), a następnie przekazać go do funkcji otwierającej strumień razem ze ścieżką, trybem dostępu oraz odpowiednimi parametrami. Kontekst jest ważny tylko w ramach transakcji, w której został pobrany. Próba użycia go po zatwierdzeniu albo wycofaniu transakcji może zakończyć się błędem lub odmową dostępu.

W praktycznym przepływie aplikacja rozpoczyna transakcję, wybiera ścieżkę obiektu i kontekst transakcji, otwiera uchwyt FILESTREAM, odczytuje dane porcjami, zamyka uchwyt, a dopiero potem kończy transakcję. Przy odczycie należy obsłużyć przerwanie połączenia, zmianę stanu transakcji oraz błędy odczytu. Pozostawienie otwartego uchwytu lub niezamkniętej transakcji może utrzymywać zasoby dłużej, niż zakłada aplikacja.

Ograniczenia dostępu przez system plików

Strumieniowy interfejs FILESTREAM korzysta z mechanizmu SMB udostępnianego przez SQL Server, ale aplikacja nie powinna omijać SQL Server przez samodzielne przeglądanie fizycznego kontenera danych. Pliki znajdujące się w kontenerze są zarządzane przez silnik bazy i ich bezpośrednia modyfikacja poza obsługiwanym API może uszkodzić spójność danych. Prawidłowy odczyt odbywa się przez ścieżkę uzyskaną z kolumny FILESTREAM oraz kontekst wygenerowany w bieżącej transakcji.

Tryb dostępu może być ustawiony jako odczyt albo zapis, zależnie od operacji przekazanej do OpenSqlFilestream. Dla samego pobierania zawartości aplikacja używa trybu tylko do odczytu. Odczyt strumieniowy ogranicza konieczność kopiowania całej wartości do pamięci procesu, dlatego nadaje się do większych dokumentów, obrazów i innych obiektów binarnych. Nadal trzeba jednak kontrolować rozmiar bufora, liczbę jednoczesnych strumieni oraz czas trwania transakcji.

FILESTREAM musi być włączony na poziomie instancji SQL Server, a konkretna baza danych musi mieć skonfigurowaną obsługę FILESTREAM i odpowiednią grupę plików. Dostęp przez API systemu plików zależy również od ustawień poziomu dostępu FILESTREAM oraz od uprawnień konta używanego przez aplikację. Sam fakt posiadania ścieżki zwróconej przez PathName() nie daje prawa do niezależnego otwierania obiektu bez ważnego kontekstu transakcji.

Weryfikacja odczytu i typowe źródła problemów

Diagnostykę należy rozpocząć od sprawdzenia definicji tabeli, typu kolumny, obecności ograniczenia ROWGUIDCOL oraz poprawności konfiguracji FILESTREAM w SQL Server. Następnie warto wykonać kontrolny odczyt przez Transact-SQL i porównać go z odczytem strumieniowym, używając tej samej wartości identyfikatora wiersza. Różnica między wynikami może wskazywać na błąd w wyborze rekordu, niepełne odczytanie bufora albo nieprawidłowe zakończenie strumienia, a nie na problem z samym magazynem FILESTREAM.

Częstą przyczyną niepowodzenia jest rozpoczęcie odczytu bez transakcji, pobranie kontekstu w innej transakcji niż ta, która otwiera strumień, albo zamknięcie transakcji przed zakończeniem odczytu. Problem może również wynikać z niedostępności skonfigurowanego udziału FILESTREAM, braku wymaganych uprawnień, użycia nieobsługiwanego połączenia lub przekazania nieaktualnej ścieżki. W logach aplikacji powinny znaleźć się identyfikator rekordu, rozmiar oczekiwanych danych, tryb dostępu, etap transakcji i kod błędu, bez zapisywania całej zawartości binarnej.

W środowisku produkcyjnym należy zamykać uchwyty strumieni w bloku gwarantującym wykonanie operacji porządkowych oraz wycofywać transakcję po błędzie. Jeżeli obiekt ma być przesyłany dalej, aplikacja powinna sprawdzać liczbę odczytanych bajtów i poprawnie obsługiwać odczyt częściowy. Takie postępowanie pozwala odróżnić błąd konfiguracji SQL Server od usterki w kodzie klienta odpowiedzialnym za transakcję, obsługę uchwytu lub składanie danych.