1. C# Filestream Read Example

Storing and managing unstructured data was tricky prior to the release of SQL Server 2008. Before then, there were two approaches to storing unstructured data in SQL Server. One approach suggests storing the data in a VARBINARY or IMAGE column. This ensures transactional consistency and reduces management complexities, but is bad for performance. The other approach is to store the unstructured data as disk files and store the location of the file in the table along with the other structured data linked to it.

This approach was found to be good in terms of performance, but does not ensure transactional consistency. Moreover management (backup, restore, security etc) of the data will be a pain too.

FILESTREAM Feature FILESTREAM was introduced in SQL Server 2008 for the storage and management of unstructured data. The FILESTREAM feature allows storing BLOB data (example: word documents, image files, music and videos etc) in the NT file system and ensures transactional consistency between the unstructured data stored in the NT file system and the structured data stored in the table. Storing BLOB data in NT file system, allows SQL Server to take advantage of the NTFS I/O streaming capabilities and at the same time, maintain transactional consistency of the data. FILESTREAM uses NT System Cache for caching file data. This minimizes the effect that FILESTREAM data might have on the Database Engine performance.

When accessing FILESTREAM data through the streaming API, SQL Server buffer pool is not used and hence it does not reduce the amount of memory available for Database Engine query processing. The term ‘FILESTREAM data type’ or ‘FILESTREAM column’ is very commonly used and it gives an indication that the FILESTREAM feature is implemented as a data type. This is not true. FILESTREAM is not a data type; instead, it is an attribute that can be assigned to a VARBINARY (MAX) column. When the FILESTREAM attribute of a VARBINARY (MAX) column is set, it becomes a ‘FILESTREAM enabled’ column. Any data that you store in such columns will be stored in the NT file system as a disk files and a pointer to the disk file is stored in the table. A VARBINARY (MAX) column with FILESTREAM attribute is not restricted to the 2 GB limit SQL Server imposes on Large Value Types.

The size of the file is limited by the size of the disk volume only. When the FILESTREAM attribute is set, SQL Server stores the BLOB data in the NT file system and keeps a pointer the file, in the table. SQL Server ensures transactional consistency between the FILESTREAM data stored in the NT file system and the structured data stored in the tables. Installing and Configuring FILESTREAM The default installation of SQL Server 2008 disables FILESTREAM feature. It is quite easy to enable the FILESTREAM feature as part of a new SQL Server 2008 installation.

If the SQL Server 2008 instance is already installed without FILESTREAM feature, it can still be enabled following the steps explained later in this section. Enabling FILESTREAM as part of installation The easiest way to enable FILESTREAM feature is to do so as part of the installation process. You will see a new tab labeled “FILESTREAM” on the “Database Engine Configuration” page of the installation wizard. This tab allows you to specify the FILESTREAM configuration options that you wish to enable on your new SQL Server Instance. FILESTREAM feature may be enabled with three different levels of access to the FILESTREAM data, namely:.

Enable FILESTREAM for Transact-SQL access. Enable FILESTREAM for file I/O streaming access.

Allow remote clients to have streaming access to FILESTREAM data Enabling FILESTREAM during an Unattended installation If you are installing SQL Server 2008 in ‘Unattended mode’, you can use /FILESTREAMLEVEL and /FILESTREAMSHARENAME configuration options to configure FILESTREAM features. For more information about installing SQL Server 2008 in ‘Unattended mode’, see Enabling FILESTREAM after installation Enabling FILESTREAM feature on a SQL Server 2008 Instance, installed without FILESTREAM features, would require a little more work.

To enable FILESTREAM feature, go to ‘SQL Server configuration Manager’ and right click on instance of SQL Server Service and select ‘properties’. The property page will show an additional tab labeled ‘FILESTREAM’, which looks exactly the same as the FILESTREAM configuration page shown as part of the installation wizard.

The FILESTREAM feature can be enabled by setting the appropriate options on this page. If you wish to automate this process, you could try running the VBScript given at to do it.

Once FILESTREAM feature is enabled, the next step is to configure FILESTREAM Access Level. This is an additional step that is required only if you configure FILESTREAM after the installation of SQL Server. Open SQL Server Management Studio and open the properties of the SQL Server 2008 instance. Select the ‘Advanced’ tab and change the ‘FILESTREAM Access Level’ to ‘Transact-SQL Access enabled’ or ‘Full access enabled’. Alternatively, ‘FILESTREAM Access Level’ can be configured using TSQL by running the following statement. GO The last parameter to spconfigure specifies the Access Level, where 0 means ‘Disabled’, 1 means ‘Transact-SQL Access Enabled’ and 2 means ‘Full Access Enabled’ Using FILESTREAM Once you have an instance of SQL server 2008 with FILESTREAM feature enabled, you are ready to go ahead and create FILESTREAM enabled databases.

When you create a FILESTREAM enabled database, the FILESTREAM data should be placed in a separate file group having a special attribute that indicates that the file group contains FILESTREAM data. SQL Server allows FILESTREAM file groups to be on compressed volumes. If you are using FILESTREAM on a clustering environment, FILESTREAM file groups must be on shared disk resources.

Creating a FILESTREAM enabled database A basic FILESTREAM enabled database should have the following storage components:. MDF File. LOG File. FILESTREAM Data Container MDF File and LOG files are familiar to us and do not need any explanation. However, FILESTREAM Data Container may be new to some. FILESTREAM Data Container is a special folder in the NT File System where SQL Server will store FILESTREAM data as disk files. We will examine FILESTREAM Data container a little later in this article.

Here is the script that creates a FILESTREAM enabled database. GO Note the portion highlighted in yellow. That is the part that adds the FILESTREAM Data Container to the database. One important point to note here is that the last sub directory in the FILESTREAM Data Container path should not already exist. In the above example, “c: temp np” should exist, however, the root level folder “NorthPoleFS” should not exist in “c: temp np” at the time of creating the database. SQL Server will create the root folder and configure it.

If the folder already exists, the operation will fail with an error. Understanding FILESTREAM Data Container The root folder where FILESTREAM data of a database is stored is called FILESTREAM Data Container.

When you create a database with FILESTREAM feature enabled, the FILESTREAM Data Container will be created with the path you specify in your CREATE statement. The root directory in the FILENAME parameter will be configured as FILESTREAM Data Container. It is important that this folder should not exist at the time of creating the database. SQL Server will create this folder and will configure it as FILESTREAM Data Container. Reviewing the FILESTREAM Data Container Let us go ahead and take a look at the FILESTREAM data container. You may not do this every time you create a FILESTREAM enabled database or table. However, for the purpose of understanding the FILESTREAM Data Container structure, let us take a look at how the folder looks like.

When we created the database, we had specified the path to the location that we wanted to have configured as the FILESTREAM Data Container for our database. If you have not modified the location I specified in the code snippet, it will be “C: temp NP NorthPoleFS”.

Open windows explorer and navigate to the folder you specified as FILESTREAM Data Container while creating the database. You will see a folder named “$FSLOG” and a file “filestream.hdr” there. The folder “$FSLOG” is the FILESTREAM equivalent of the Database Transaction Log file. “filestream.hdr” contains important metadata information used by SQL Server internally. Make sure that you do not tamper with this file. Creating a table with FILESTREAM columns Once we have a FILESTREAM enabled database, we are ready to go ahead and create tables having FILESTREAM columns. A FILESTREAM column is a VARBINARY(MAX) column that has the FILESTREAM attribute enabled.

Remember, FILESTREAM is not a new DATA TYPE, it is a new attribute added to a VARBINARY(MAX) column. ) Note that every table that has a FILESTREAM column should have a UNIQUEIDENTIFIER column with ROWGUIDCOL and UNIQUE attributes. Reviewing the FILESTREAM Data Container Changes Let us go back to the FILESTREAM Data Container folder and see if we can detect any change since the last time we visited it. This time you will notice that a new folder is created in the root folder with a GUID value as its name. SQL Server will create a folder for each table that uses FILESTREAM enabled columns. Within this folder, a sub folder will be created for each FILESTREAM enabled column in the table.

Inserting FILESTREAM data We have got the table created. Let us now add a couple of rows to the table we created. As you must have figured out by looking at the column names, this table is intended for storing product information. Along with the item information (ItemNumber and ItemDescription) we will also store an image of the item. The image will be stored in the FILESTREAM enabled column. Let us add ‘Microsoft Mouse’ as the first item to this table. I have a cute image of a Microsoft Mouse on my hard disk and let us load the content of the image file and store that to the ‘ItemImage’ column.

For the purpose of this example, let us use OPENROWSET(BULK.) to load the content of the image file (jpg) from the disk to a VARBINARY(MAX) variable. Once the content of the image is loaded to the variable, we can store it to the FILESTREAM enabled column. Let us see the code that does it.

SELECT NEWID ( ), 'MS1001', 'Microsoft Mouse', @ img Before you run the above code, make sure that you change the name of the file (“c: temp MicrosoftMoust.jpg”) to a valid image file name that exists in your hard disk. Accessing FILESTREAM Data using TSQL Even though the actual data of a FILESTREAM enabled column is stored in the NT File System, it will be completely transparent to the TSQL code. You can access the data in the FILESTREAM enabled column just like any other column of the given table. The following example queries all the information from the “Items” table which returns the FILESTREAM data too. Close ( ) Accessing FILESTREAM data with Managed API Accessing FILESTREAM data using Win32 Streaming has a number of advantages over accessing it using TSQL. When accessing FILESTREAM data using TSQL, SQL Server reads the content of the FILESTREAM data file and serves it to the client.

SQL Server memory is used for reading the content of the data file. Accessing FILESTREAM data using Win32 Streaming does not use SQL Server memory. In addition it allows the application to take advantage of the Streaming capabilities of the NT File System. Though accessing FILESTREAM data using Win32 Streaming has a number of advantages, it is a bit complicated to use, compared to the syntax needed to access it from TSQL. Before a client application can access the FILESTREAM data, it needs to find out the logical path that uniquely identifies the given file in the FILESTREAM data store. This can be achieved by using the “ PathName” method of a FILESTREAM column.

C# Filestream Read Example

Note that the PathName function is Case Sensitive. The following example shows how to retrieve the PathName associated with the FILESTREAM data of a column. Close ( ) Updating FILESTREAM Data FILESTREAM data may be modified using either TSQL or using the FILESTREAM API. As mentioned earlier, modifying FILESTREAM data using the Streaming API has a number of advantages over accessing it using TSQL. Using TSQL to update one or more FILESTREAM columns is not different from updating regular columns.

Though a FILESTREAM column can store more than 2 GB of data, it is not possible to access more than 2 GB of FILESTREAM data using TSQL, because 2 GB is the maximum size of any Large Value Type (VARBINARY, VARCHAR, NVARCHAR, TEXT, NTEXT) can store. Modifying FILESTREAM data using streaming API is pretty much the same as what we saw in the previous example. Before accessing the data you need to access the PathName, start a transaction and obtain a transaction context before modifying the data using the SqlFileStream class.

Deleting FILESTREAM Data When a row is deleted from a table having FILESTREAM enabled columns, the record is removed from the table and the FILESTREAM data file is removed from the FILESTREAM Data Container. FILESTREAM data from the FILESTREAM data container is removed by the FILESTREAM garbage collector. Since this is done in a separate background thread, you may still see the deleted file in the FILESTREAM data container until the garbage collector runs again.

FILESTREAM Garbage Collector SQL Server triggers the FILESTREAM Garbage Collector thread when a CHECKPOINT occurs. So, after deleting FILESTREAM data using TSQL you might notice that the physical file is not removed from the FILESTREAM data container right away. The file will remain in the FILESTREAM data container until the next CHECKPOINT occurs and the garbage collector runs. FILESTREAM operations generate minimal log in the TRN log file and hence it might take longer for a CHECKPOINT to occur if the database is not highly transactional. In such a case, if you want to trigger the garbage collector thread, you should issue an EXPLICIT CHECKPOINT. FILESTREAM Feature Summary With FILESTREAM, the SQL Server team not only added a feature to handle unstructured data, but also made sure that it smoothly integrates with many of the existing features of SQL Server.

FILESTREAM feature is available with all versions of SQL Server 2008, including SQL Server Express. SQL Server Express database has a 4 GB limitation; however this limitation does not apply to the FILESTREAM data stored in a SQL Server Express database. FILESTREAM Columns can be replicated. FILESTREAM enabled databases can be used with LOG Shipping. FILESTREAM columns can be used in Full Text Indexes. FILESTREAM works with all recovery models.

FILESTREAM File Groups can be placed on compressed disk volumes. The maximum size of the file that can be stored into the FILESTREAM data storage is limited by the size of the disk volume only. Restrictions on existing features Though the FILESTREAM feature smoothly integrates with many of the existing features of SQL Server, it adds restrictions to or completely disables a few other important features of SQL Server. A FILESTREAM enabled database cannot be used for mirroring. This is one of the key restrictions that I dislike.

Mirroring is a very interesting feature and it cannot be used with FILESTREAM. FILESTREAM data is not available in database snapshots.

If you create database snapshots and run a “SELECT. FROM table” query on a table with FILESTREAM columns, you will get an error. All queries that you run on a FILESTREAM enabled table of a database snapshot should exclude FILESTREAM columns. FILESTREAM Limitations The FILESTREAM implementation in SQL Server 2008 comes with a few limitations.

The following limitations make complete sense to me and I have no complaints on them. FILESTREAM columns cannot be used in Index Keys. FILESTREAM columns cannot be used in the INCLUDED columns of a Non Clustered Index. FILESTREAM columns cannot be used in a Table Valued Parameter. FILESTREAM columns cannot be used in a memory table. FILESTREAM columns cannot be used in a global or local temp table.

Statistics cannot be created on FILESTREAM columns. Computed columns having reference to FILESTREAM columns cannot be indexed. When FILESTREAM Data is accessed through Win 32 APIs, only READ COMMITTED ISOLATION level is supported.

FILESTREAM data can be stored only on local disk volumes However the following limitations are little restrictive and I really wish to have them removed in the future versions of SQL Server. FILESTREAM data is not supported on Database Snapshots. Well, that is acceptable, however what is the real pain is the error that we get if we run a “SELECT. FROM table” query on a FILESTREAM enabled table in a database snapshot. SQL Server should ideally return NULL values for FILESTREAM enabled columns, if it cannot create snapshots of FILESTREAM data.

At present, it is a real pain to exclude all FILESTREAM enabled columns from all queries that runs on a Database Snapshot. Transparent Data Encryption (TDE) does not encrypt FILESTREAM data. It would be interesting to have this restriction removed in the future. FILESTREAM Feature – Points to Remember Take note of the following points if you intend to use FILESTREAM in your application.

You cannot do database mirroring if you use FILESTREAM features. If you replicate FILESTREAM enabled columns, make sure that all subscribers are running on SQL Server 2008 or later versions. If you intend to use LOG shipping, make sure that both primary and secondary servers are running on SQL Server 2008 or later versions. If you are on a FAILOVER CLULSTERING environment, make sure that you place the FILESTREAM file groups in a shared disk and FILESTREAM should be enabled on each node. You cannot access FILESTREAM data if you create database snapshots.

If you try to access a FILESTREAM enabled column, SQL Server will raise an error. Jacob Sebastian is a SQL Server Consultant based in Ahmedabad, India. He's a Microsoft SQL Server MVP, a Moderator at the MSDN and Technet Forums, and volunteers with the Professional Association for SQL Server as Regional Chapter Coordinator for Asia.

He also runs a SQL Server User Group in his home town and is a frequent columnist at SQLServerCentral.com. Jacob started his database career in the early nineties with Dbase and then moved to Clipper, Foxpro and finally settled on SQL Server. He's now been working with SQL Server for over 11 years and is a regular speaker at local User Groups and SQL Server events. He is also a well-known SQL Server trainer, and teaches at various SQL Server classes across the country. Getting “The Network path was not found” error I am getting the above error while trying to upload BLOB file to the SQL server, only if the application and database server are on separate machine. If they are in the same machine, it’s okay.That is only happen if I do the Integrated Security=true, but if I do the integrated security=false and use username/password, I am getting access denied error. So, does it mean, I can’t use SQL server 2008’s filestream feature on web farms, where I can’t use windows authentication or my supervisor doesn’t want to use impersonation?

Please, can you elaborate more on this. Getting “The Network path was not found” error I am getting the above error while trying to upload BLOB file to the SQL server, only if the application and database server are on separate machine. If they are in the same machine, it’s okay.That is only happen if I do the Integrated Security=true, but if I do the integrated security=false and use username/password, I am getting access denied error. So, does it mean, I can’t use SQL server 2008’s filestream feature on web farms, where I can’t use windows authentication or my supervisor doesn’t want to use impersonation? Please, can you elaborate more on this.

Getting “The Network path was not found” error I am getting the above error while trying to upload BLOB file to the SQL server, only if the application and database server are on separate machine. If they are in the same machine, it’s okay.That is only happen if I do the Integrated Security=true, but if I do the integrated security=false and use username/password, I am getting access denied error. So, does it mean, I can’t use SQL server 2008’s filestream feature on web farms, where I can’t use windows authentication or my supervisor doesn’t want to use impersonation?

Please, can you elaborate more on this. Great article, but. Hi Great article but can you answer this really important question please – is there any way to extract a physical file from Filestream and write it to a disk in its original format – using TSQL only? It seems we can upload a file using TSQL, but you need to use VB or C# ( I cant code in VB or C# but I’m a DBA so I dont need to.). I’m just worried I havent understood the limitations of accessing Filestream correctly. All I want to do is upload a PDF file into file stream, then extract it in its orioginal PDF format later USING ONLY TSQL – and be able to open it.

How do I do that please? Thanks in advance.

Great article, but. Hi Great article but can you answer this really important question please – is there any way to extract a physical file from Filestream and write it to a disk in its original format – using TSQL only? It seems we can upload a file using TSQL, but you need to use VB or C# ( I cant code in VB or C# but I’m a DBA so I dont need to.). I’m just worried I havent understood the limitations of accessing Filestream correctly. All I want to do is upload a PDF file into file stream, then extract it in its orioginal PDF format later USING ONLY TSQL – and be able to open it. How do I do that please? Thanks in advance.

Also in For many developers, database security and Access control is just something that gets in the way of development work. However, several recent security breaches have had devastating consequences and have caused a change in attitude about the value to any organisation of having database applications that meet industry standards for access control and security. The problem, however is in admitting that you have a problem and finding answers to those problems you are just too shy to ask in public.