# illuminate/database: the Laravel database layer as a standalone PHP toolkit

> A read-only subtree split of the Illuminate Database component, packaged for use outside Laravel through the Capsule manager. This article covers what it does, how to wire it up, and where it stops being the right tool.

**illuminate/database** — [READ ONLY] Subtree split of the Illuminate Database component (see laravel/framework)

- Repository: https://github.com/illuminate/database
- Stars: 2,774 · Forks: 603
- Language: PHP
- License: MIT
- Published: 2026-09-28 · Updated: 2026-09-28 · Language: en
- Canonical page: https://hysenlabs.com/projects/illuminate-database

## What illuminate/database actually is, and who reaches for it

The README describes the component as "a full database toolkit for PHP, providing an expressive query builder, ActiveRecord style ORM, and schema builder." It supports MySQL, Postgres, SQL Server and SQLite, and it also serves as the database layer of the Laravel framework. That last clause is the important one. This repository is a subtree split of the component that lives inside laravel/framework, so it exists so that non-Laravel projects can pull the database layer in without pulling the framework.

The audience is narrow but real. You have a PHP application, a CLI tool, a legacy codebase or a small service that is not built on Laravel, and you want Eloquent models or the fluent query builder rather than raw PDO. The README's usage instructions are written for exactly that case: they start from a Capsule manager instance, not from a Laravel application boot.

What this is not: a database abstraction layer that hides differences between engines. The repository contains separate MySqlConnection, PostgresConnection, SQLiteConnection and SqlServerConnection classes, plus a MariaDbConnection, and separate schema grammars. The toolkit gives you one fluent API, but engine-specific behaviour still surfaces in the connection and schema layers. The README does not claim portability beyond the four listed drivers.

## Capsule, connections and the Eloquent boot sequence

The mechanism is a container-backed manager. You instantiate Illuminate\Database\Capsule\Manager, register one or more connections through addConnection, and then decide how much of the ORM machinery to switch on.

The README marks three of those steps optional. setEventDispatcher attaches an event dispatcher, which the README says is used by Eloquent models. setAsGlobal exposes the Capsule instance through static methods so you can call Capsule::table() and Capsule::select() without passing the manager around. bootEloquent starts the ORM. The README notes that setEventDispatcher is a prerequisite for bootEloquent, and a separate note states that composer require "illuminate/events" is required when you need observers with Eloquent. So events are genuinely optional, but the moment you want model observers, they are not.

From there the data flow is conventional: the query builder compiles a fluent chain into SQL through a grammar, the connection executes it, and Eloquent maps rows onto model classes. The repository layout reflects that split, with Query/, Schema/, Eloquent/, Connectors/ and Grammar.php at the top level. A DatabaseManager and DatabaseServiceProvider also sit in the tree, but those are framework-facing pieces; the README's standalone path goes through Capsule instead.

## Installing illuminate/database and running a first query

Installation is through Composer. The README's usage section assumes the package is already present and does not print an install command, so the package name comes from the repository itself: illuminate/database. The README does give one explicit install step, for the events package, when observers are needed.

```bash
composer require illuminate/database
composer require "illuminate/events"
```

The second line is only required for observers with Eloquent, as the README states. Then create the Capsule and register a connection. This block is copied from the README's example, with the driver set to mysql.

```php
use Illuminate\Database\Capsule\Manager as Capsule;

$capsule = new Capsule;

$capsule->addConnection([
    'driver' => 'mysql',
    'host' => 'localhost',
    'database' => 'database',
    'username' => 'root',
    'password' => 'password',
    'charset' => 'utf8',
    'collation' => 'utf8_unicode_ci',
    'prefix' => '',
]);
```

After that, make the instance global and boot Eloquent if you want models. The README lists both as optional, and notes that bootEloquent should not be called when you have not used setEventDispatcher.

```php
use Illuminate\Events\Dispatcher;
use Illuminate\Container\Container;

$capsule->setEventDispatcher(new Dispatcher(new Container));
$capsule->setAsGlobal();
$capsule->bootEloquent();
```

With that in place, the README shows the query builder as Capsule::table('users')->where('votes', '>', 100)->get(), a raw statement as Capsule::select('select * from users where id = ?', [1]), and the schema builder as Capsule::schema()->create('users', ...) with increments, string and timestamps columns. Eloquent is a class extending Illuminate\Database\Eloquent\Model, queried as User::where('votes', '>', 1)->get(). If the connection config is wrong, expect a connection-level exception at the first query rather than at boot.

## Where the component stops being the right tool

The most concrete limitation is packaging. This repository is a read-only subtree split. There is no homepage, and the recent releases list is empty, so there is no component-level release history to follow here. If you need a changelog, an issue tracker or a version to pin against, you are working against laravel/framework, not against this repository. That is a real operational cost: your dependency's history lives somewhere else.

The second limitation is coupling. The README's setup imports Illuminate\Events\Dispatcher and Illuminate\Container\Container. The component does not stand alone in the sense of having no sibling dependencies; it is a slice of a framework, and the slice boundary is visible the moment you enable events. If your goal is a database library with no framework lineage, this is the wrong shape.

Third, the README does not document rollback, migration execution, connection pooling, retry behaviour or transaction handling. The repository tree contains Migrations/, DatabaseTransactionsManager and DeadlockException, so those concerns exist in the code, but the README points readers to the Laravel framework documentation for "further documentation on using the various database facilities this library provides." That is the honest state of things: the standalone README is a setup guide, not a reference. If you need documented behaviour for a production data path, you will be reading Laravel's docs and mapping them back onto this package yourself.

## illuminate/database against Doctrine DBAL and raw PDO

The closest alternative in the PHP ecosystem is Doctrine DBAL, and the difference in approach is worth stating plainly. DBAL is a standalone database abstraction layer with its own project, its own release cycle and its own documentation, and it is designed to be used without a framework. It gives you a connection layer, a schema abstraction and a query builder, but it does not ship an ActiveRecord ORM; that is a separate project in the same ecosystem.

illuminate/database takes the opposite route. It bundles query builder, schema builder and ActiveRecord ORM in one component, and it is extracted from a framework rather than designed as a library first. You get Eloquent, which is the reason most people come here, and you get the Capsule bootstrap that makes the extraction usable. You do not get a component-owned changelog or a component-owned support process.

Raw PDO is the other realistic option, and for a small service with a handful of queries it is not a bad one. PDO gives you prepared statements and nothing else. illuminate/database gives you a fluent builder, schema creation and model mapping, at the cost of a dependency graph that reaches into the container and event dispatcher. Choose based on how much query construction and row mapping you would otherwise write by hand.

## Licence, maintenance and what upgrading costs you

The licence is MIT, per the LICENSE.md file at the repository root. MIT is permissive: it allows use, modification and redistribution with the licence and copyright notice retained. That is the extent of what this article should say about it; whether MIT fits your organisation's policy is a question for your own review, not for a summary here.

On maintenance, the only facts available are that the repository is not archived and the last push was on 2026-09-23. That is five days before today's date, so the split is being kept in sync with the framework. It does not tell you anything about the component's own roadmap, because the component does not have one here.

Upgrade cost is the part people underestimate. Because this is a subtree split, version numbers and release notes belong to laravel/framework. A major framework release can change behaviour in this package without a corresponding entry in this repository. Practically, that means pinning illuminate/database to a constraint that matches the framework generation you have tested, and reading the framework's upgrade guide when you move. The README gives no migration path of its own, and the empty recent releases list means there is nothing here to diff between versions.

## Conclusion

Adopt illuminate/database when you want Laravel's query builder, Eloquent models and schema builder in a non-Laravel PHP codebase, and you accept that it is a read-only subtree split with no separate release history and no homepage. Do not adopt it if you need a framework-independent API surface or a component with its own issue tracker and changelog. Before writing code, verify the current composer.json constraint for illuminate/support and confirm which driver extensions your PHP build has enabled, because the README names MySQL, Postgres, SQL Server and SQLite but never lists the required extensions.

## FAQ

### What is illuminate/database?

It is the database component of the Laravel framework, distributed as a read-only subtree split. The README describes it as a full database toolkit for PHP with a query builder, an ActiveRecord style ORM and a schema builder, supporting MySQL, Postgres, SQL Server and SQLite.

### Can I use illuminate/database without Laravel?

Yes. The README's usage instructions start from a Capsule manager instance rather than a Laravel application, and show addConnection, setAsGlobal and bootEloquent as the setup steps. The README notes that the illuminate/events package is required when you need observers with Eloquent.

### Which databases does illuminate/database support?

The README lists MySQL, Postgres, SQL Server and SQLite. The repository also contains a MariaDbConnection class alongside the MySQL, Postgres, SQLite and SQL Server connection classes.

### How do I install illuminate/database?

Through Composer, using the package name illuminate/database. The README does not print an install command for the package itself; the only explicit install step it gives is composer require "illuminate/events" for Eloquent observers.

### Does illuminate/database have its own changelog or release notes?

Not in this repository. It is a read-only subtree split of the component in laravel/framework, the recent releases list is empty, and the README directs readers to the Laravel framework documentation for further documentation on the database facilities.

## Sources

- [illuminate/database on GitHub](https://github.com/illuminate/database)
- [Issues](https://github.com/illuminate/database/issues)
- [License: MIT](https://github.com/illuminate/database/blob/master/LICENSE)
- [README](https://github.com/illuminate/database/blob/master/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/illuminate-database