Arcane Code » FILESTREAM

Full Text Searching a FILESTREAM VARBINARY (MAX) Column

arcanecode — Thu, 28 May 2009 06:04:00 +0000

In the past I’ve written that Full Text Searching has the ability to index documents stored in a VARBINARY(MAX) field. However, I have never really gone into any details on how to do this. Today I will remedy that by demonstrating how to Full Text Seach not only using a VARBINARY(MAX) field, but one that has been stored using FILESTREAM. Even though these examples will be done against the data we’ve stored with FILESTREAM over the lessons from the last few days, know that this technique is identical for binary objects stored in a VARBINARY(MAX) field without using FILESTREAM.

Let’s start by creating a catalog to hold our Full Text data.

CREATE FULLTEXT CATALOG FileStreamFTSCatalog AS DEFAULT;

Pretty normal, now we need to create a full text index on the “DocumentRepository” table we created in this series. When you look at the syntax though, you may notice a minor difference from the CREATE FULLTEXT INDEX examples I’ve shown in the past:

CREATE FULLTEXT INDEX ON dbo.DocumentRepository

(DocumentName, Document TYPE COLUMN DocumentExtension)

KEY INDEX PK__Document__3214EC277F60ED59

ON FileStreamFTSCatalog

WITH CHANGE_TRACKING AUTO;

Here you can see I am indexing two fields. The first is the “DocumentName”, which is passed in as the first parameter and looks like other examples. We won’t actually be using it in this example, however I included it to demonstrate you can index multiple columns even when one of them is a VARBINARY(MAX) column.

The second parameter indexes the VARBINARY(MAX) “Document” column itself, but notice the TYPE COLUMN after the column name. In order to Full Text Index a VARBINARY(MAX) column you must also have a column with the file extension in it. You then pass in the name of column after the TYPE COLUMN. In this example, the document extension is stored in the “DocumentExtension” column. Since the document extension can be stored in a column with any name, we let the Full Text engine know which column by passing it in after the TYPE COLUMN keyword. The remainder of the command is like other examples I’ve shown in the past.

Now we can run a normal SELECT…CONTAINS query against the “Document” field.

SELECT ID, DocumentName

FROM dbo.DocumentRepository

WHERE CONTAINS(Document, 'Shrew');

I’ll leave it to you to run, for me it returned one row, with “TheTamingOfTheShrew.doc”. If you want to try it again, use “Elinor”, and you should get back “KingJohn.doc”.

As you can see, performing a Full Text Search against a VARBINARY(MAX) column is quite easy, all you have to do is indicate the document type by using the TYPE COLUMN. There are two more things you should know. First, the column containing the document extension must be of type CHAR, NCHAR, VARCHAR, or NVARCHAR. Second, the document type must be recognized by SQL Server. To get a list of all valid document types, simply query the fulltext_document_types catalog view like so:

SELECT * FROM sys.fulltext_document_types;

This will give you a list of all file extensions understood by SQL Server. Each row actually represents a filter. Each filter represents a DLL that implements the IFilter interface. It is possible to add additional filters to the system. For example, Microsoft offers the “Microsoft Filter Pack”. You may have noticed that out of the box SQL Server 2008 supports the older Office 2003 documents, but not the more recent Office 2007 formats. To add these newer formats to your SQL Server, Microsoft provides the afore mentioned filter pack. While installing it is beyond the scope of this aritcle you can find complete instructions for downloand and installation at http://support.microsoft.com/default.aspx?scid=kb;en-us;945934 .

The Full Text Search features provided by SQL Server continue to amaze me with how powerful they are, yet how easy they are to implment. With the information here you can easily search through documents stored in a VARBINARY(MAX) field, even when those documents are actually stored via the new SQL Server 2008 FILESTREAM.

Accessing FILESTREAM Data From A Client .NET Application – Part 2 Downloading a File

arcanecode — Wed, 27 May 2009 06:03:00 +0000

In the previous entry we covered how to upload a file to SQL Server using the FILESTREAM, new to SQL Server 2008. In this post we will look at retrieving a file from SQL Server using FILESTREAM. If you missed yesterday’s installment, a simple front end was created, the full project can be found at the Code Gallery site http://code.msdn.microsoft.com/FileStreamFTS .

The interface is very simple:

The grid is a Data View Grid that shows the ID and Document information from the table we previously created. (If you want to see the code to populate the grid see the project.) The user picks a row, then clicks on the Get File button.

    private void btnGetFile_Click(object sender, EventArgs e)
    {
      // Reset in case it was used previously
      lblStatus.Text = "";
 
      if (dgvFiles.CurrentRow != null)
      {
        // Grab the ID (Primary Key) for the current row
        int ID = (int)dgvFiles.CurrentRow.Cells[0].Value;
        // Now Save the file to the folder passed in the second
        // paramter. 
        FileTransfer.GetFile2(ID, @"D:\Docs\Output\");
        // And let user know it’s OK 
        lblStatus.Text = "File Retrieved";
      }
    }

The code is very simple, the heart of it is the FileTransfer.GetFile static method. Two values are passed in, the integer ID, which is the primary key from the database, and the path to save the file to. Here I simply hard coded a path, in a real life application you will want to give the user the ability to enter a path. Let’s take a look at the GetFile routine.

    public static void GetFile(int ID, string outputPath)
    {
      // Setup database connection
      SqlConnection sqlConnection = new SqlConnection(
                "Integrated Security=true;server=(local)");
 
      SqlCommand sqlCommand = new SqlCommand();
      sqlCommand.Connection = sqlConnection;
 
      try
      {
        sqlConnection.Open();
 
        // Everything we do with FILESTREAM must always be in 
        // the context of a transaction, so we’ll start with 
        // creating one.
        SqlTransaction transaction 
          = sqlConnection.BeginTransaction("mainTranaction");
        sqlCommand.Transaction = transaction;
 
        // The SQL gives us 3 values. First the PathName() method of 
        // the Document field is called, we’ll need it to use the API
        // Second we call a special function that will tell us what
        // the context is for the current transaction, in this case 
        // the "mainTransaction" we started above. Finally it gives
        // the name of the document, which the app will use when it
        // creates the document but is not strictly required as 
        // part of the FILESTREAM.
        sqlCommand.CommandText
          = "SELECT Document.PathName()"
          + ", GET_FILESTREAM_TRANSACTION_CONTEXT() "
          + ", DocumentName "
          + "FROM FileStreamFTS.dbo.DocumentRepository "
          + "WHERE ID=@theID ";
 
        sqlCommand.Parameters.Add(
          "@theID", SqlDbType.Int).Value = ID;
 
        SqlDataReader reader = sqlCommand.ExecuteReader();
        if (reader.Read() == false)
        {
          throw new Exception("Unable to get BLOB data");
        }
 
        // OK we have some data, pull it out of the reader into locals
        string path = (string)reader[0];
        byte[] context = (byte[])reader[1];
        string outputFilename = (string)reader[2];
        int length = context.Length;
        reader.Close();
 
        // Now we need to use the API we declared at the top of this class
        // in order to get a handle. 
        SafeFileHandle handle = OpenSqlFilestream(
          path
          , DESIRED_ACCESS_READ
          , SQL_FILESTREAM_OPEN_NO_FLAGS
          , context
          , (UInt32)length, 0);
 
        // Using the handle we just got, we can open up a stream from 
        // the database.
        FileStream databaseStream = new FileStream(
          handle, FileAccess.Read);
 
        // This file stream will be used to copy the data to disk
        FileStream outputStream 
          = File.Create(outputPath + outputFilename); 
 
        // Setup a buffer to hold the streamed data
        int blockSize = 1024 * 512;
        byte[] buffer = new byte[blockSize];
 
        // There are two ways we could get the data. The simplest way
        // is to read the data, then immediately feed it to the output
        // stream using it’s Write feature (shown below, commented out.
        // The second way is to load the data into an array of bytes
        // (here implemented using the generic LIST). This would let
        // you manipulate the data in memory, then write it out (as
        // shown here), reupload it to another data stream, or do
        // something else entirely. 
        // If you want to go the simple way, just remove all the
        // fileBytes lines and uncomment the outputStream line.
        List<byte> fileBytes = new List<byte>();
        int bytesRead = databaseStream.Read(buffer, 0, buffer.Length);
        while (bytesRead > 0)
        {
          bytesRead = databaseStream.Read(buffer, 0, buffer.Length);
          //outputStream.Write(buffer, 0, buffer.Length);
          foreach (byte b in buffer)
            fileBytes.Add(b);
        }
 
        // Write out what is in the LIST to disk
        foreach (byte b in fileBytes)
        {
          byte[] barr = new byte[1];
          barr[0] = b;
          outputStream.Write(barr, 0, 1);
        }
 
        // Close the stream from the databaseStream
        databaseStream.Close();
 
        // Write out the file
        outputStream.Close();
 
        // Finally we should commit the transaction. 
        sqlCommand.Transaction.Commit();
      }
      catch (System.Exception ex)
      {
        MessageBox.Show(ex.ToString());
      }
      finally
      {
        sqlConnection.Close();
      }
      return;
 
    }

The routine kicks off by opening a connection, then establishing a transaction. Remember from the previous lesson that every time you work with a FILESTREAM it has to be in a transaction. Next we basically duplicate the SQL used in the previous lesson, returning the path name, transaction context, and document name. The only difference is we pass in the ID as a parameter. With that, just like with the previous example we call the OpenSqlFilestream API. Note a difference, in this example the second parameter is “DESIRED_ACCESS_READ” as opposed to the write access we indicated previosly.

Once we have the “handle” we can create a FileStream for reading from the database. In this example I loop through the file stream, loading the data into a LIST of bytes. Once in memory we are free to work with it as we need to. In this example I simply loop back through the generic List and write the data to the file stream we opened on the disk for writing. If all you are doing is writing, it would be somewhat more efficient to write the code like so:

        int bytesRead = databaseStream.Read(buffer, 0, buffer.Length);
        while (bytesRead > 0)
        {
          bytesRead = databaseStream.Read(buffer, 0, buffer.Length);
          outputStream.Write(buffer, 0, buffer.Length);
        }
 
        // Close the stream from the databaseStream
        databaseStream.Close();

I simply eliminate the local byte array and write the buffer directly to the disk. Either way, the remainder is simple, just closing all the streams, commiting the transaction and closing the database connection.

This concludes the series on how to use FILESTREAM, in future posts we look into how to do Full Text Search with FILESTREAM stored objects.

Accessing FILESTREAM Data From A Client .NET Application – Part 1 Uploading a File

arcanecode — Tue, 26 May 2009 06:02:00 +0000

The best way to work with documents in a database is via a .Net application. I created a simple Windows forms project to access the table I created in previous lessons. I named the application FileLoader, you can the entire project at the Code Gallery site http://code.msdn.microsoft.com/FileStreamFTS .

The interface is very simple:

As you can see there are two main functions, the upper half uploads a file to the SQL Server. The lower half displays the files already in the table, lets the user pick one and then click the GetFile button to save it locally. Today we’ll look at the Upload File functionality. Here is the code:

    private void btnUploadFile_Click(object sender, EventArgs e)
    {
      // Reset in case it was used previously
      lblStatus.Text = "";
 
      // Make sure user entered something
      if (txtFile.Text.Length == 0)
      {
        MessageBox.Show("Must supply a file name");
        lblStatus.Text = "Must supply file name";
        return;
      }
 
      // Make sure what user entered is valid
      FileInfo fi = new FileInfo(txtFile.Text);
      if (!fi.Exists)
      {
        MessageBox.Show("The file you entered does not exist.");
        lblStatus.Text = "The file you entered does not exist.";
        return;
      }
 
      // Upload the file to the database
      FileTransfer.UploadFile(txtFile.Text);
 
      // Refresh the datagrid to show the newly added file
      LoadDataGridView();
 
      // Let user know it was uploaded
      lblStatus.Text = fi.Name + " Uploaded";
    }

The real line of importance is the FileTransfer.UploadFile. This calls a static method in a class I named FileTransfer.cs. In order to use FILESTREAM there is an API call we have to make, so at the header area of the FileTransfer we have a lot of declarations. These are pretty much a straight copy from the MSDN help files.

    //These contants are passed to the OpenSqlFilestream()
    //API DesiredAccess parameter. They define the type
    //of BLOB access that is needed by the application.
 
    const UInt32 DESIRED_ACCESS_READ = 0×00000000;
    const UInt32 DESIRED_ACCESS_WRITE = 0×00000001;
    const UInt32 DESIRED_ACCESS_READWRITE = 0×00000002;
 
    //These contants are passed to the OpenSqlFilestream()
    //API OpenOptions parameter. They allow you to specify
    //how the application will access the FILESTREAM BLOB
    //data. If you do not want this ability, you can pass in
    //the value 0. In this code sample, the value 0 has
    //been defined as SQL_FILESTREAM_OPEN_NO_FLAGS.
 
    const UInt32 SQL_FILESTREAM_OPEN_NO_FLAGS = 0×00000000;
    const UInt32 SQL_FILESTREAM_OPEN_FLAG_ASYNC = 0×00000001;
    const UInt32 SQL_FILESTREAM_OPEN_FLAG_NO_BUFFERING = 0×00000002;
    const UInt32 SQL_FILESTREAM_OPEN_FLAG_NO_WRITE_THROUGH = 0×00000004;
    const UInt32 SQL_FILESTREAM_OPEN_FLAG_SEQUENTIAL_SCAN = 0×00000008;
    const UInt32 SQL_FILESTREAM_OPEN_FLAG_RANDOM_ACCESS = 0×00000010;
 
    //This structure defines the format of the final parameter to the
    //OpenSqlFilestream() API.
 
    //This statement imports the OpenSqlFilestream API so that it
    //can be called in the Main() method below.
    [DllImport("sqlncli10.dll", SetLastError = true, CharSet = CharSet.Unicode)]
    static extern SafeFileHandle OpenSqlFilestream(
                string Filestreamath,
                uint DesiredAccess,
                uint OpenOptions,
                byte[] FilestreamTransactionContext,
                uint FilestreamTransactionContextLength,
                Int64 AllocationSize);
 
    //This statement imports the Win32 API GetLastError().
    //This is necessary to check whether OpenSqlFilestream
    //succeeded in returning a valid / handle
 
    [DllImport("kernel32.dll", SetLastError = true)]
    static extern UInt32 GetLastError();

OK, with that out of the way, I’ve created a public, static method to upload the file. Here is the full routine:

    public static void UploadFile(string fileName)
    {
      // Establish db connection
      SqlConnection sqlConnection = new SqlConnection(
                "Integrated Security=true;server=(local)");
      SqlTransaction transaction = null;
 
      // Create a File Info object so you can easily get the
      // name and extenstion. As an alternative you could
      // choose to pass them in,  or use some other way
      // to extract the extension and name. 
      FileInfo fi = new FileInfo(fileName);
 
      try
      {
        // Open the file as a stream
        FileStream sourceFile = new FileStream(fileName
          , FileMode.OpenOrCreate, FileAccess.Read);
 
        // Create the row in the database
        sqlConnection.Open();
 
        SqlCommand cmd = new SqlCommand();
        cmd.Connection = sqlConnection;
        cmd.CommandText = "INSERT INTO "
          + "FileStreamFTS.dbo.DocumentRepository"
          + "(DocumentExtension, DocumentName) VALUES (‘" 
          + fi.Extension + "’, ‘" 
          + fi.Name + "’)";
        cmd.ExecuteNonQuery();
 
        // Now upload the file. It must be done inside a transaction.
        transaction = sqlConnection.BeginTransaction("mainTranaction");
        cmd.Transaction = transaction;
        cmd.CommandText = "SELECT Document.PathName(), "
         + "GET_FILESTREAM_TRANSACTION_CONTEXT() "
         + "FROM FileStreamFTS.dbo.DocumentRepository "
         + "WHERE ID=(select max(id) from FileStreamFTS.dbo.DocumentRepository)";
        SqlDataReader rdr = cmd.ExecuteReader();
        if (rdr.Read() == false)
        {
          throw new Exception("Could not get file stream context");
        }
 
        // Get the path
        string path = (string)rdr[0];
        // Get a file stream context
        byte[] context = (byte[])rdr[1];
        int length = context.Length;
        rdr.Close();
 
        // Now use the API to get a reference (handle) to the filestream
        SafeFileHandle handle = OpenSqlFilestream(path
          , DESIRED_ACCESS_WRITE
          , SQL_FILESTREAM_OPEN_NO_FLAGS
          , context, (UInt32)length, 0);
 
        // Now create a true .Net filestream to the database
        // using the handle we got in the step above
        FileStream dbStream = new FileStream(handle, FileAccess.Write);
 
        // Setup a buffer to hold the data we read from disk
        int blocksize = 1024 * 512;
        byte[] buffer = new byte[blocksize];
 
        // Read from file and write to DB
        int bytesRead = sourceFile.Read(buffer, 0, buffer.Length);
        while (bytesRead > 0)
        {
          dbStream.Write(buffer, 0, buffer.Length);
          bytesRead = sourceFile.Read(buffer, 0, buffer.Length);
        }
 
        // Done reading, close all of our streams and commit the file
        dbStream.Close();
        sourceFile.Close();
        transaction.Commit();
 
      }
      catch (Exception e)
      {
        if (transaction != null)
        {
          transaction.Rollback();
        }
        throw e;
      }
      finally
      {
        sqlConnection.Close();
      }
 
    }

First we open a connection to the SQL Server, then create a FileInfo object to make it simple to extract the file name and extension. Next a record is inserted into the database that will act as a place holder. It has the name of the file and the extension, but no file yet. I did go ahead and open a FileStream to the source file, located on the disk. We’ll need this later to upload the file.

Next you will see that I begin a transaction. Every time you work with a FILESTREAM it must always be in the context of a transaction. After that a SQL Data Reader is created that has three pieces of information. First, it calls the PathName() function for the Document field in our table. The PathName() will be needed later when we call the API. The second field is returned from the GET_FILESTREAM_TRANSACTION_CONTEXT function, and returns the transaction context for the transaction. Note this is not the name (in this example “mainTransaction”), but the context which is a special value. These two values are then copied into local variables which will be used in calling the OpenSqlFilestream API. In this example I also retrieve the DocumentName field, this is used by the code when it writes the file to the database, but is not strictly needed for the FILESTREAM.

Next you will see the call to the OpenSqlFilestream API, which returns a “handle”. This handle is then used to create a FileStream object. Using this newly created FileStream (here named dbStream) we can then upload the file. Now the main work begins. After setting up a buffer, we then simply read from the source file stream into the buffer, then write the exact same buffer to the database FileStream. The loop continues until there are no more bytes in the source.

At this point we are essentially done. We close the streams, commit the transaction, and in the finally block close the SQL database connection. The file should now be in the database. I do want to point out one thing. In the SQL to get the information to the row just uploaded, I use a subquery to get the max(id), essentially returning the last row just inserted. This is fine for this simple example, when the database has just one user. In your production systems where you are likely to have many users, however, you should use an alternate method to return the row you need. Otherwise two users could insert rows at the same time, and thus a conflict could occur with both of them getting back the same max(id). It will not happen often, but at some point it could happen and be very hard to debug.

This handled the uploading of files to the SQL Server via FILESTREAM, in the next installment we’ll look at how to retrieve the file we just uploaded.

Creating Tables and Inserting Rows With FILESTREAM

arcanecode — Wed, 20 May 2009 06:09:00 +0000

In previous lessons, we setup the server to handle FILESTREAM, then we looked at how to create or alter a database to work with FILESTREAM. In this lesson we will create a table to store a FILESTREAM, then insert a few rows into it.

Before we create our table, be aware of some requirements necessary for FILESTREAM to work. First, you must have a special column that FILESTREAM uses to uniquely identify the stream. It must be a unique non null identifier of type ROWGUIDCOL. If we specify a default of NEWSEQUENTIALID the column becomes self maintaining. When we insert a new value into the row, SQL Server takes care of creating a GUID for us and we essentially can ignore the column. Here is an example:

USE FileStreamFTS

GO

CREATE TABLE DocumentRepository(

  ID INT IDENTITY(1,1) NOT NULL PRIMARY KEY

, FileStreamID UNIQUEIDENTIFIER ROWGUIDCOL NOT NULL UNIQUE DEFAULT NEWSEQUENTIALID()

, DocumentExtension VARCHAR(10)

, DocumentName VARCHAR(256)

, Document VARBINARY(MAX) FILESTREAM DEFAULT(0x)

);

GO

Here the column “FileStreamID” will become the required column for FILESTREAM. Note the column name is not important, I could have called it “FSID”, “FSIdentity”, or even “Spock”. You’ll also note I created an ID column for our use in normal day to day operations. This is not a requirement of FILESTREAM, just good practice. There is a second requirement however. For the column that will be storing the documents, it must be VARBINARY(MAX), and it must add the FILESTREAM clause.

You will also note the default of “0x” (hex 0). This will be important if you wish to insert a new row without supplying the document at the time the row is created. It will create a file to act as a placeholder until such time as the real document is supplied.

You can also alter an existing table to add FILESTREAM capabilities. Simply use the ALTER TABLE command, add the unique identifier column (in this example “FileStreamID”) and the VARBINARY(MAX) column to hold your data (“Document” in the above example).

It’s time to insert some data. Normally the best way to insert data is using a client application, such as something written in .Net. It is possible to add documents though via T-SQL. To supply data for these examples, I decided a little culture was in order. I went to http://shakespeare.mit.edu/ and copied some of the plays into Microsoft Word documents. Note I used the older “.doc” format from 2003, not the 2007 “.docx”. This is not particularly important as far as FILESTREAM is concerned, but will come into play in later lessons when we look at doing Full Text Searches on this data.

INSERT INTO DocumentRepository(DocumentExtension, DocumentName, Document)

SELECT

 'doc' AS DocumentExtension

 , 'Hamlet.doc' AS DocumentName

 , * FROM OPENROWSET(BULK 'D:\Docs\Hamlet.doc', SINGLE_BLOB)

   AS Document;

GO

Here we’ve inserted a new row into the table, and have ignored the “ID” and “FileStreamID” letting SQL Server create the values. The “DocumentExtension” and “DocumentName” columns are straightforward. To supply the document however, we need to use an OPENROWSET. This will supply the data from a disk file as a single BLOB (Binary Large OBject).

Let’s verify what was just inserted with this query:

SELECT ID

     , FileStreamID

     , DocumentExtension AS Ext

     , DocumentName

     , CAST(Document AS VARCHAR) as DocumentData

FROM DocumentRepository;

Notice the CAST, its necessary in order to get a view into the stored document.

ID	FileStreamID	Ext	DocumentName	DocumentData
1	A54A8FFE-F742-DE11-AC61-002243CE0AAB	doc	Hamlet.doc	ÐÏà¡±á > þÿ

As mentioned previously, it is also possible to insert a new row, then add the document later. To insert a new row into our example table, we simply use:

INSERT INTO DocumentRepository(DocumentExtension, DocumentName)

VALUES ('doc', 'AMidsummerNightsDream.doc');

GO

Now that the row exists, we can update it.

UPDATE  DocumentRepository

SET     Document = ( SELECT *

                     FROM OPENROWSET(

                      BULK 'D:\Docs\AMidsummerNightsDream.doc',

                      SINGLE_BLOB) AS TheDocument

WHERE   ID = 2 ;

GO

While it is possible to add data in this format, it’s fairly rare. The majority of the time you will want to use a client side application, which is what we’ll look at in the next installment of this series.

Enabling FILESTREAM In The Database

arcanecode — Tue, 19 May 2009 06:09:00 +0000

Once you have your server configured for FILESTREAM, you will need to configure your database. The easiest way is to establish it when you first create the database.

CREATE DATABASE FileStreamFTS ON

PRIMARY ( NAME = FileStreamFTS_Data,

    FILENAME = 'd:\data\FileStreamFTS_Data.mdf'),

FILEGROUP FileStreamFTS_FileGroup1

  CONTAINS FILESTREAM( NAME = FileStreamFTS_FileGroup,

    FILENAME = 'd:\data\FileStreamFTS_FileGroup')

LOG ON  ( NAME = FileStreamFTS_Log,

    FILENAME = 'd:\data\FileStreamFTS_Log.ldf')

GO

In the above example, I created my database in a directory on my D drive named “D:\Data”. If you examine the folder you ’ll now see two files, the mdf and ldf files. There is also a folder “FileStreamFTS_FileGroup”. It is in this folder that your files will eventually be stored in.

You may be tempted to poking around in the folder, and perhaps even access the stored files directly. My advice to you: don’t. Microsoft has strongly advised against this practice. After all, you went to all the trouble of setting up FILESTREAM to let SQL Server handle this for you, so let it do the handling. If you are curious to dig deeper into how FILESTREAM works behind the scenes, I would recommend Paul Randal’s excellent white paper available at http://msdn.microsoft.com/en-us/library/cc949109.aspx.

The above example shows how to add FILESTREAM capability when you first create your database. That’s great, but what if you already have an existing database you want to add FILESTREAM to? I have just such an existing database, “ArcaneCode”. To add FILESTREAM I need to issue two ALTER DATABASE statements. First, we need to add a FILEGROUP and indicate that file group contains FILESTREAM objects.

ALTER DATABASE ArcaneCode

ADD FILEGROUP ArcaneFileStreamGroup1

  CONTAINS FILESTREAM

GO

In the second we have to indicate to the FILEGROUP where the FILESTREAM should be stored. Pass in the directory name where you want your files saved as the FILENAME parameter. As with the create statement the directory can not exist, if it does you’ll get an error.

ALTER DATABASE ArcaneCode

ADD FILE

  (NAME = 'ArcaneFS_Group'

   , FILENAME = 'D:\Data\ArcaneCodeFS'

TO FILEGROUP ArcaneFileStreamGroup1

GO

This completes the steps needed to create a database with FILESTREAM, or add it to an existing database. In the next lesson we will look at creating tables that use FILESTREAM.

Enabling FILESTREAM on SQL Server 2008

arcanecode — Mon, 18 May 2009 06:05:00 +0000

One of the newly touted features of SQL Server 2008 is file streaming. For some time now SQL Server has allowed users to store large binary objects in the database inside a varbinary(max) field. Performance began to suffer, however, when the binary object was over 1 megabyte or so in size.

SQL Server 2008 solves this through its new FILESTREAM feature. With FILESTREAM SQL Server lets the operating system, Windows Server, do what it does best: handle the storage of binary objects, better known as files. In the database, SQL Server simply stores a reference that will let it open and close the file from the disk. FILESTREAM gives us the best of all worlds. When the file group is backed up so are the files, they can also be made part of a transaction.

By default, FILESTREAM is not enabled when you install SQL Server 2008. Activating it is a simple, two step process. As always though make sure to do proper backups before making any changes to your SQL Server, and be sure to first implement on development, then test systems before making changes to any production server.

First, you will need to enable FILESTREAM for the Windows Server it is running on. Begin by opening the SQL Server Configuration Manager. Once inside click on “SQL Server Services” then highlight the server you want to activate. In this example we clicked on “SQL Server (MSSQLSERVER)”.

Now that it is highlighted, right click on it and pick properties from the menu. Click on the FILESTREAM tab in the dialog that appears.

If you have a default install, your dialog should appear with nothing enabled, as this one does. Check on the first line, “Enable FILESTREAM for Trancact-SQL access”. This turns on the FILESTREAM feature, but with a drawback. It only works from T-SQL, and then only on the server itself. To make it useful we need to go further.

Once the first line is checked on, the second line, “Enable FILESTREAM for file I/O streaming access” will become enabled. Check it on. At this point the server will allow FILESTREAM from a separate application, but only when run on the same Windows Server that SQL Server is running on.

Since most of your users will not be running on the SQL Server itself, you will want to check on the final option which is now available, “Allow remote clients to have streaming access to FILESTREAM data”. Once this is checked, you can click OK to save your changes.

Note there may be one exception to checking on the final option. If you are running SQL Server Express, it is quite possible your application and the database may all be running on the same computer, and that you do not want any other machine to get access to this database. While this would be an uncommon situation, please note that the capability does exist for you to set things up this way if needed.

Now that the Windows Server is ready to handle FILESTREAM we need to enable the SQL Server. Fortunately this winds up being a simple matter. Open up SQL Server Management Studio, and enter the following command:

  EXEC sp_configure filestream_access_level, 2

  RECONFIGURE

Note the number at the end of the first line. Valid values for this are “0”, “1”, and “2”. “0” will disable FILESTREAM completely. “1” will enable it, but only for T-SQL code. “2” will fully enable it and allow access via .NET or other code. Note that these are slightly different from the way the Windows Server rights are set. Here, in order to run anything other than T-SQL you must use a “2”, regardless of where the code is executed (local or remote).

It is also possible to change this setting in the GUI. Right click on the server in SQL Server Management Studio, in this case it is “(local)”, and pick “Properties” from the menu. Go to the “Advanced” page and the FILESTREAM is the top most item, you can see it here with all of its options.

Now your server has been properly configured to handle file streaming, you’ll want to create a database in a way to handle file streaming. We’ll do that in the next installment in this series.