Migrations and schema
Configure the connection, create tables, run versioned changes, and understand recovery limits.
On this page
Configure the database
Application overrides belong in user/config/db.php. A minimal SQLite configuration is:
<?php
return [
'default' => 'sqlite',
'connections' => [
'sqlite' => [
'driver' => 'sqlite',
'database' => storage_path('database.sqlite'),
],
],
];
The package also supplies MySQL and PostgreSQL connection defaults. Install the appropriate PDO driver and provide host, database, username, and password through your application's configuration and process environment. This guide's runnable examples use SQLite in memory; they do not connect to your deployed database.
Write a PHP migration
Create database/migrations/2026_10_19_000001_create_notes.php:
<?php
use Anvyr\Loom\Database\Schema\Blueprint;
use Anvyr\Loom\Database\Schema\Schema;
return new class {
public function up(Schema $schema): void
{
$schema->create('notes', static function (Blueprint $table): void {
$table->id();
$table->string('title', 180);
$table->text('body')->default('');
$table->boolean('archived')->default(false);
$table->json('settings')->nullable();
$table->bigInteger('author_id')->unsigned()->nullable();
$table->timestamp('deleted_at')->nullable();
$table->timestamps();
$table->index('title');
});
}
};
The file must return an object with an up(Schema $schema) method. A class declaration alone is not the migration contract. Names sort lexicographically, so use ordered, unique filenames. A migration is recorded by its name, not a content checksum; edit future migrations rather than rewriting a change already applied elsewhere.
Run pending changes
php loom migrate
Without --path, Loom discovers package migrations, the application's database/migrations, and migration paths from enabled modules. A module's default path is database/migrations relative to its own directory. Applied names are stored in the migrations table; running the same set again skips recorded migrations.
To select specific paths, relative to the application root:
php loom migrate --path=database/migrations
php loom migrate --path=database/migrations,user/modules/Notes/database/migrations
An explicit path list replaces automatic package/module path discovery. Keep migration names unique across paths because they share the same repository. In production, the command asks for confirmation; use --force only in your deliberate non-interactive release process.
Add related tables
For the relationship examples, put this inside a later migration's up() method, where $schema is available:
use Anvyr\Loom\Database\Schema\Blueprint;
$schema->create('authors', static function (Blueprint $table): void {
$table->id();
$table->string('name');
$table->timestamps();
});
$schema->create('author_profiles', static function (Blueprint $table): void {
$table->id();
$table->bigInteger('author_id')->unsigned();
$table->text('bio');
$table->unique('author_id');
$table->foreign('author_id')->references('id')->on('authors')->onDelete('cascade');
$table->timestamps();
});
$schema->create('tags', static function (Blueprint $table): void {
$table->id();
$table->string('name')->unique();
$table->timestamps();
});
$schema->create('note_tag', static function (Blueprint $table): void {
$table->bigInteger('note_id')->unsigned();
$table->bigInteger('tag_id')->unsigned();
$table->unique(['note_id', 'tag_id']);
$table->foreign('note_id')->references('id')->on('notes')->onDelete('cascade');
$table->foreign('tag_id')->references('id')->on('tags')->onDelete('cascade');
});
Move the use import to the file header when inserting the statements into a method. The notes table deliberately leaves author_id without a foreign key in the first migration; a relationship declaration does not add one. For SQLite, enable foreign-key enforcement on the connection if you rely on its constraints; Loom's SQLite connection does not enable that pragma automatically.
Know the schema surface
Blueprint column methods include id, string, text, longText, integer, bigInteger, json, boolean, timestamp, and timestamps. Chain nullable(), default(), unsigned(), or useCurrent() where the selected driver supports the modifier. Index definitions include index, unique, primary, and foreign.
Schema exposes create(), drop(), and dropIfExists(). It does not currently expose Schema::table() or a column-alteration API. Use a reviewed driver-appropriate SQL migration for changes outside that surface, and test against the database you deploy.
SQL files and recovery
The migrator accepts PHP and SQL files, including generic .up.sql and driver-specific forms such as .sqlite.up.sql, .mysql.up.sql, and .pgsql.up.sql. For example, database/migrations/2026_10_19_000003_index_notes.up.sql can contain:
CREATE INDEX notes_archived_idx ON notes (archived);
The matching driver's up file takes precedence, then generic up SQL, then PHP. Keep alternatives for a migration deliberate: candidate selection can fall back to remaining files, so a file for another driver must not be your only available alternative. The SQL reader is a basic statement splitter; complex stored routines need separate validation.
There is no migrate:rollback command or automatic down() execution in this implementation. Do not place .down.sql files in the scanned directory expecting the runner to distinguish rollback-only work. Treat deployed changes as forward migrations and keep a tested backup/recovery procedure.
Migration execution is not automatically wrapped in a transaction. A partially failed migration may leave changes applied without a completed repository entry; inspect the actual schema before retrying.
Verified against MigrateCommand, Migrator, Schema, and Blueprint.