Anvyr Docs
Documentation menu Anvyr Loom 1.x
Anvyr Loom

Version 1.x

← All documentation

GuideAnvyr Loom 1.xDeveloper

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.

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.

Continue readingModels and persistence