Como criar e usar Filestream em SQL Server: passo a passo

Este tutorial mostra como configurar e usar Filestream em SQL Server para armazenar ficheiros grandes no sistema de ficheiros com integridade transaccional. Filestream é útil quando precisa de guardar BLOBs grandes sem sobrecarregar a base de dados, mantendo ACID e desempenho.

Pré-requisitos

• Instância de SQL Server (Standard/Enterprise ou Express com suporte a Filestream).
• Permissões de administrador no servidor para activar Filestream e criar pastas.
• SQL Server Management Studio (SSMS) ou acesso ao sqlcmd.

Passo 1: Activar Filestream a nível de servidor

Filestream deve ser activado ao nível da instância. Isto envolve configurar a opção de arranque do SQL Server e activar o serviço de Filestream no Configuration Manager.

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

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

Depois de executar isto, abra o SQL Server Configuration Manager e, na instância, active o serviço de Filestream na aba de propriedades (se aplicável) e reinicie a instância do SQL Server.

Passo 2: Criar um Filegroup Filestream e pastas no sistema de ficheiros

É necessário um filegroup do tipo Filestream que referencia uma pasta no sistema de ficheiros. Crie primeiro a pasta com permissões adequadas e depois adicione o filegroup à base de dados.

-- Assumindo uma base de dados de exemplo:
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'
);

Se a pasta já existir, apenas assegure permissões NTFS para a conta do serviço do SQL Server.

Passo 3: Criar tabela com coluna Filestream

Crie uma tabela que inclua uma coluna VARBINARY(MAX) com a propriedade FILESTREAM e uma coluna ROWGUIDCOL que será usada para identificar cada registo (obrigatório).

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()
);

Passo 4: Inserir e ler ficheiros (exemplo com T-SQL)

Pode inserir dados usando OPENROWSET(BULK...) para carregar ficheiros do disco para a coluna FILESTREAM. Para leitura, pode exportar ou ler directamente com SELECT.

-- Inserir um ficheiro no Filestream (exemplo: C:\Upload\report.pdf)
INSERT INTO Documents (FileName, FileContent)
SELECT 'report.pdf', BulkColumn
FROM OPENROWSET(BULK 'C:\Upload\report.pdf', SINGLE_BLOB) AS x;

-- Ler meta-dados e tamanho do blob
SELECT DocumentId, FileName, DATALENGTH(FileContent) AS SizeBytes, UploadedAt
FROM Documents;

-- Exportar ficheiro usando T-SQL e comando adicional: usar fn_varbintohexstr ou ferramentas externas.

Nota: para exportar para ficheiro no servidor pode usar uma aplicação cliente ou um script PowerShell que leia a coluna e grave no disco. Também pode usar as Filestream APIs com código em C# para acesso Win32 eficiente.

Passo 5: Boas práticas e erros comuns

Use estas recomendações para evitar problemas comuns com Filestream: backups, manutenção e permissões são críticos.

• Inclua o filegroup Filestream nos backups FULL e RESTORE; sem isso perde os dados Filestream.
• Verifique permissões NTFS para a conta do serviço do SQL Server na pasta Filestream.
• Evite armazenar ficheiros pequenos (< 1 MB) em Filestream — para ficheiros pequenos um VARBINARY normal pode ser mais simples.
• Se vir erros como "The backup's filegroup does not contain the FILESTREAM data" verifique que fez backup do filegroup correcto.

Verificar o resultado

Para confirmar que Filestream funciona, execute um SELECT e verifique o tamanho dos BLOBs e a existência dos ficheiros na pasta do filegroup (os ficheiros não aparecem com nomes amigáveis). Faça um BACKUP DATABASE e depois um RESTORE em ambiente de teste para garantir que o filegroup foi incluído. Exemplo de verificação rápida:

-- Verificar registos e tamanho
SELECT DocumentId, FileName, DATALENGTH(FileContent) AS SizeBytes
FROM Documents;

-- Fazer backup (incluir filegroups automaticamente se for FULL)
BACKUP DATABASE DemoFilestream TO DISK = 'C:\Backups\DemoFilestream.bak';

Conclusão

Filestream em SQL Server permite armazenar ficheiros grandes de forma eficiente, mantendo integridade transaccional e melhorando o desempenho. Próximos passos: experimentar acesso via aplicação (C# ou PowerShell) para ler/gravar ficheiros directamente, e testar cenários de backup/restore. Dica: antes de produção, teste permissões NTFS e rotinas de backup para evitar perda de dados.