Skip to main content
Learn how to use the File Storage Adapter for single-server deployments.

​
When to Use

Use FileStorageAdapter when:
  • Running on a single server
  • You have writable disk access
  • Embeddings should persist across restarts

​
Configuration

src/storage/file-adapter.ts
import { VectoriaDB, FileStorageAdapter, SerializationUtils } from 'vectoriadb';

const documents = collectToolDocuments();

const toolIndex = new VectoriaDB<ToolDocument>({
  storageAdapter: new FileStorageAdapter({
    cacheDir: './.cache/vectoriadb',
    namespace: 'tool-index',
  }),
  toolsHash: SerializationUtils.createToolsHash(documents),
  version: process.env.npm_package_version,
});

await toolIndex.initialize();

if (toolIndex.size() === 0) {
  await toolIndex.addMany(documents);
  await toolIndex.saveToStorage(); // Persist to disk
}

​
Options

OptionTypeDefaultDescription
cacheDirstring./.cache/vectoriadbDirectory for cache files
namespacestring'default'Namespace for isolation
fileNamestring'embeddings.json'Cache file name

​
File Structure

The adapter creates this structure: 
.cache/vectoriadb/
└── tool-index/              # namespace
    └── embeddings.json      # cache file

​
Directory Permissions

Ensure the cache directory is writable:
src/directory-setup.ts
import * as fs from 'fs/promises';

// Create cache directory if it doesn't exist
await fs.mkdir('./.cache/vectoriadb', { recursive: true });

const db = new VectoriaDB({
  storageAdapter: new FileStorageAdapter({
    cacheDir: './.cache/vectoriadb',
  }),
});

​
Error Handling

src/file-error-handling.ts
import { StorageError } from 'vectoriadb';

try {
  await db.saveToStorage();
} catch (error) {
  if (error instanceof StorageError) {
    console.error('Failed to save:', error.message);

    // Common issues:
    // - Permission denied
    // - Disk full
    // - Path doesn't exist
  }
}

​
Security Considerations

The adapter includes path traversal protection:
src/security.ts
// These are sanitized automatically:
const adapter = new FileStorageAdapter({
  namespace: '../../../etc/passwd', // Sanitized to safe string
});
Never pass untrusted user input directly to the namespace option. Always sanitize external input.

​
Docker Volumes

When using Docker, mount the cache directory as a volume:
docker-compose.yml
services:
  app:
    volumes:
      - vectoria-cache:/app/.cache/vectoriadb

volumes:
  vectoria-cache:

Storage Overview

Storage fundamentals

Redis Adapter

Multi-pod storage

Cache Invalidation

Cache control