Cómo crear y usar Filestream en SQL Server: paso a paso

Este tutorial muestra cómo configurar y usar Filestream en SQL Server para almacenar archivos grandes en el sistema de archivos con integridad transaccional. Filestream es útil cuando necesita guardar BLOBs grandes sin sobrecargar la base de datos, manteniendo ACID y rendimiento.

Requisitos previos

• Instancia de SQL Server (Standard/Enterprise o Express con soporte para Filestream).
• Permisos de administrador en el servidor para activar Filestream y crear carpetas.
• SQL Server Management Studio (SSMS) o acceso a sqlcmd.

Paso 1: Activar Filestream a nivel de servidor

Filestream debe activarse a nivel de instancia. Esto implica configurar la opción de inicio de SQL Server y activar el servicio de Filestream en el Configuration Manager.

-- 1. Verificar estado (ejecutar en SSMS):
EXEC sp_configure 'show advanced options', 1;
RECONFIGURE;
EXEC sp_configure 'filestream access level';

-- 2. Definir acceso (0 = off, 1 = Transact-SQL, 2 = T-SQL + Win32):
EXEC sp_configure 'filestream access level', 2;
RECONFIGURE;

Después de ejecutar esto, abra el SQL Server Configuration Manager y, en la instancia, active el servicio de Filestream en la pestaña de propiedades (si procede) y reinicie la instancia de SQL Server.

Paso 2: Crear un Filegroup Filestream y carpetas en el sistema de archivos

Es necesario un filegroup de tipo Filestream que haga referencia a una carpeta en el sistema de archivos. Cree primero la carpeta con permisos adecuados y luego añada el filegroup a la base de datos.

-- Suponiendo una base de datos de ejemplo:
CREATE DATABASE DemoFilestream
ON PRIMARY (
    NAME = DemoFilestream_Data,
    FILENAME = 'C:\SQLData\DemoFilestream.mdf'
), FILEGROUP FGFilestream CONTAINS FILESTREAM(
    NAME = DemoFilestream_FS,
    FILENAME = 'C:\SQLData\DemoFilestream_FS'
)
LOG ON (
    NAME = DemoFilestream_Log,
    FILENAME = 'C:\SQLData\DemoFilestream.ldf'
);

Si la carpeta ya existe, simplemente asegure permisos NTFS para la cuenta del servicio de SQL Server.

Paso 3: Crear tabla con columna Filestream

Crear una tabla que incluya una columna VARBINARY(MAX) con la propiedad FILESTREAM y una columna ROWGUIDCOL que se usará para identificar cada registro (obligatoria).

USE DemoFilestream;
GO
CREATE TABLE Documents (
    DocumentId UNIQUEIDENTIFIER ROWGUIDCOL NOT NULL UNIQUE DEFAULT NEWSEQUENTIALID(),
    FileName NVARCHAR(260) NOT NULL,
    FileContent VARBINARY(MAX) FILESTREAM NULL,
    UploadedAt DATETIME2 NOT NULL DEFAULT SYSUTCDATETIME()
);

Paso 4: Insertar y leer archivos (ejemplo con T-SQL)

Puede insertar datos usando OPENROWSET(BULK...) para cargar archivos del disco a la columna FILESTREAM. Para lectura, puede exportar o leer directamente con SELECT.

-- Insertar un archivo en el Filestream (ejemplo: C:\Upload\report.pdf)
INSERT INTO Documents (FileName, FileContent)
SELECT 'report.pdf', BulkColumn
FROM OPENROWSET(BULK 'C:\Upload\report.pdf', SINGLE_BLOB) AS x;

-- Leer metadatos y tamaño del blob
SELECT DocumentId, FileName, DATALENGTH(FileContent) AS SizeBytes, UploadedAt
FROM Documents;

-- Exportar archivo usando T-SQL y comando adicional: usar fn_varbintohexstr o herramientas externas.

Nota: para exportar a archivo en el servidor puede usar una aplicación cliente o un script PowerShell que lea la columna y guarde en disco. También puede usar las Filestream APIs con código en C# para acceso Win32 eficiente.

Paso 5: Buenas prácticas y errores comunes

Use estas recomendaciones para evitar problemas comunes con Filestream: backups, mantenimiento y permisos son críticos.

• Incluya el filegroup Filestream en los backups FULL y RESTORE; sin esto se pierden los datos Filestream.
• Verifique permisos NTFS para la cuenta del servicio de SQL Server en la carpeta Filestream.
• Evite almacenar archivos pequeños (< 1 MB) en Filestream — para archivos pequeños un VARBINARY normal puede ser más sencillo.
• Si ve errores como "The backup's filegroup does not contain the FILESTREAM data" verifique que hizo backup del filegroup correcto.

Verificar el resultado

Para confirmar que Filestream funciona, ejecute un SELECT y verifique el tamaño de los BLOBs y la existencia de los archivos en la carpeta del filegroup (los archivos no aparecen con nombres amigables). Haga un BACKUP DATABASE y luego un RESTORE en un entorno de pruebas para garantizar que el filegroup fue incluido. Ejemplo de verificación rápida:

-- Verificar registros y tamaño
SELECT DocumentId, FileName, DATALENGTH(FileContent) AS SizeBytes
FROM Documents;

-- Hacer backup (incluir filegroups automáticamente si es FULL)
BACKUP DATABASE DemoFilestream TO DISK = 'C:\Backups\DemoFilestream.bak';

Conclusión

Filestream en SQL Server permite almacenar archivos grandes de forma eficiente, manteniendo integridad transaccional y mejorando el rendimiento. Próximos pasos: probar acceso vía aplicación (C# o PowerShell) para leer/grabar archivos directamente, y testear escenarios de backup/restore. Consejo: antes de producción, pruebe permisos NTFS y rutinas de backup para evitar pérdida de datos.