What’s the difference between Statamic’s flat-file and database modes?

Statamic can store content in two ways: as flat files on disk, or in a relational database. The choice affects performance characteristics and operational setup, but not how you use the CMS day-to-day.

In flat-file mode, every entry — a blog post, a product, a team member — is a Markdown or YAML file stored in your project’s content/ directory. The file contains the entry’s fields in YAML front matter and any long-form content in the body. Because content lives alongside your code, you can commit everything to version control. Roll back a bad content edit with git revert. See exactly what changed and when with git log. Deploy a complete site (code and content together) with a single push. For development teams already working in Git, this feels natural.

Flat-file mode also simplifies hosting. There’s no database to provision, back up separately, or tune for performance. The tradeoff is that querying large amounts of content requires reading from the filesystem rather than from an indexed database, which gets slower as entry counts grow. The practical ceiling varies, but sites with more than roughly 5,000–10,000 entries start to feel it, particularly on complex filtered queries.

Database mode stores content in a MySQL or PostgreSQL database, queried through Laravel’s Eloquent ORM. Queries are fast regardless of content volume, and you can index fields you’re filtering on. For large sites, high-traffic pages, or any situation where you’re doing complex queries across many entries, this is the right choice. The tradeoff is that content is no longer in version control by default — you’re back to database backups and restores for content changes.

There’s also a hybrid approach: some teams use flat files for structured content types they want version-controlled (pages, team members, static resources) while running specific high-volume collections (like a news archive) in the database. Statamic allows this at the repository level — you choose the storage driver per collection, not for the whole site. This is actually our preferred approach for a lot of projects, because it gives you the best of both: version-controlled content where it matters, database performance where you need it.

When migrating from WordPress, the decision is usually between database mode (if your site is large or performance-sensitive) or flat-file mode (if the site is moderate in size and you want the developer experience benefits). We walk through this during the audit and make a recommendation based on your content volume and query patterns.

One thing that’s sometimes misunderstood: flat-file doesn’t mean "static site." The PHP application still runs on each request and can generate dynamic output — user-specific content, search results, form handling. What flat-file means is that the content store is files, not that the site is pre-rendered HTML.