Putting Directus on Top of an Existing SQL Database

Directus connects to an existing SQL database, introspects its schema, and layers REST and GraphQL APIs plus the Data Studio editing app over the tables you already have — without migrating, restructuring, or taking ownership of the data. The database remains authoritative, and other applications keep using it directly. That single property is why this pattern exists, and it makes the project a fundamentally different exercise from a content migration. Nothing moves. The work is in deciding what the layer exposes, and to whom.

Why This Is Not a Migration

Most headless CMS projects start with an export. Content is pulled out of one system, remodeled, transformed by script, and imported into another, and the old system is eventually switched off. That is the shape of a WordPress to Sanity migration, and every hard problem in it — URL parity, content fidelity, cutover risk — comes from the fact that data is moving.

This pattern inverts that. The database stays exactly where it is, in the structure it already has, still serving whatever already depends on it. Directus attaches to it, reads the schema, and generates an API and an admin interface from what it finds. There is no export, no transform, no cutover moment, and no second copy of the truth to keep in sync. The failure modes are different too: you are not going to lose content, but you can absolutely hand a marketing editor a friendly form that writes directly into the table your billing job reads from.

The typical situation is a company with a production database that has been running for years — an application schema in Postgres or MySQL, well understood by the engineering team, with a handful of tables that non-engineers genuinely need to edit. Product descriptions. Marketing copy. Feature flags for a promotional banner. Today those edits arrive as tickets, or as SQL run by whoever is comfortable running SQL. Directus turns that subset into a real editing interface without asking the business to give up the database that everything else already depends on.

The Five Phases

The ordering matters more than it looks. Installation is easy enough that teams do it first, discover the Data Studio showing every table in the database, and start configuring from there — which quietly makes the audit and the permissions model retroactive instead of foundational. Documenting before connecting is the same documented-baseline discipline we publish in our methodology, applied to a schema rather than a set of URLs, and it is the difference between a deliberate access model and one you inherit by accident. The detailed engagement shape is on our Directus development page.

The other thing worth internalizing early is that you are introducing a second writer to a database that previously had one. Your application's assumptions — that a status column only ever holds values its own code sets, that a row is never deleted outside a service method, that a timestamp is maintained by an ORM hook — were safe when only the application could write. They stop being safe the moment an editor has a form over that table. Constraints that lived in application code rather than in the schema are exactly where this bites, which is why the audit in phase 1 looks for them specifically, and why the honest answer is sometimes to push a rule down into a database constraint before exposing the table at all.

When This Is the Right Pattern

This is the right choice when you already have a production SQL schema that must stay portable and shared. If multiple systems read and write that database, if your team's expertise is in SQL and relational modeling, if compliance or data residency requires the data to stay in infrastructure you control, or if the requirement is explicitly "give the marketing team a way to edit these six tables without a migration project" — Directus fits the problem precisely. It is also a good fit when portability is a stated requirement, because the data continues to live in a standard database you could point any other tool at tomorrow.

It is the wrong choice when you are starting greenfield and content-first. If there is no existing database, the case for shaping your content model around relational tables is much weaker, and a document-oriented CMS will usually give editors a better experience with richer content structures — nested blocks, portable rich text, flexible page composition — with less configuration. Our Sanity vs Strapi comparison covers that decision, and Strapi vs Directus covers the narrower question of two database-backed options. If you are still deciding at the category level, start from the headless CMS platform guide. We would rather tell you this pattern is wrong for you now than bill for the discovery.

What Actually Goes Wrong

• Editors given write access to application-critical tables. The single most common failure, and it is always the same cause: permissions were designed after the install instead of before it. Directus faithfully surfaces every table it can see, so a default-permissive role hands someone a clean editing form over your orders table. Roles belong in phase 3, built from the phase 1 labels.
• Schema drift. Directus reads structure from the live database, so when your application ships its own migration — renaming a column, dropping a table, changing a type — the Directus configuration attached to it goes stale. Field metadata, interfaces, and permissions referencing the old shape need to move with it. Coordinate migrations; do not let two systems evolve the schema independently.
• Assuming Directus is a database migration tool. It is not. It will not restructure a badly normalized schema, consolidate duplicated tables, or clean your data. A schema that is painful for engineers to work with will be painful for editors too, because Directus shows them the same tables. Fix the model first if it needs fixing — that is a separate project with a separate plan.
• License misunderstanding. Directus is source-available under the Business Source License with a free community tier — not plain open source. Commercial use carries conditions, and the terms have changed across versions. Teams that skimmed a "open source CMS" listicle and budgeted accordingly get an unwelcome surprise. Read the current terms at directus.io before committing.

What the Layer Gives You

Once it is configured properly, three things arrive at once. Editors get a real interface with validation, relationships rendered as readable references, and revision history recording who changed what. Developers get REST and GraphQL endpoints over the same tables without writing or maintaining a bespoke API layer. And the database stays a database — still queryable, still backed up by your existing process, still the thing every other system connects to. You can read the platform's own account of introspection, permissions, and the SDK in the Directus documentation, and the licensing and cloud terms at directus.io.

The part we care about most is what a clean relational model does downstream. Tables with real foreign keys and consistent types map onto schema.org entities far more directly than a pile of rendered pages does, which makes structured data something you generate from the model rather than hand-maintain — the entity-level clarity that both classic search and AI answer engines reward, and the foundation of the entity SEO work we specialize in. Webvello is an independent development partner and is not affiliated with Directus or Monospace Inc.

Frequently Asked Questions