Content Drivers

File, DB, Hybrid, and Auto content storage.

Content & Data

VelvetCMS Core supports multiple content drivers. Pick based on scale and query needs.

Drivers #

Driver	Description
File	Markdown files on disk
DB	Content stored in the database
Hybrid	Metadata in DB, content in files
Auto	Selects driver at boot based on page count

When to use #

Driver	Use case
File	Small sites, simple hosting, git-based content
DB	Content-heavy sites that query often
Hybrid	Fast listing/search with file-based content editing
Auto	Uncertain scale, want recommendations

Configure #

Set content.driver in config/content.php or user/config/content.php.

return [
    'driver' => 'auto',
    'drivers' => [
        'auto' => [
            'threshold' => 100,
            'small_site' => 'file',
            'large_site' => 'hybrid',
        ],
    ],
];

Auto driver behavior #

Auto driver evaluates your page count once at boot and selects the appropriate driver:

Below threshold: uses small_site driver (default: file)
At or above threshold: uses large_site driver (default: hybrid)

It does not migrate data between drivers. If you exceed the threshold, you'll see a log warning recommending manual migration:

./velvet content:migrate hybrid

This is intentional - automatic migration mid-request is risky. For zero-downtime auto-migration, see VelvetCMS (the full CMS product).

Environment variable #

You can also set the driver via environment:

CONTENT_DRIVER=hybrid

← Previous Directory Structure Next → Markdown & Frontmatter