database-structure.md

Table Structure

• Updates files
• Update process
• Migration files
• Data seeding files

October provides a simple way of managing the database structure and contents with the database scripts (migrations and seed files). The database scripts can be provided by plugins.

Update files

Database tables and seed data is managed using a version information file version.yaml found in the updates subdirectory of a plugin directory. An example plugin updates folder:

plugins/
  acme/
    blog/
      updates/                    <=== Updates folder
        version.yaml              <=== Version Information File
        create_posts_table.php    <=== Database scripts
        create_comments_table.php <=== Migration script
        some_seeding_file.php     <=== Seeding script
        some_upgrade_file.php     <=== Seeding script

The version information file defines the plugin version and refers to the migration and seeding files. All migration and seeding files should be associated with a plugin version. Example of the version.yaml file:

1.0.1:
    - Added some upgrade file and some seeding
    - some_upgrade_file.php
    - some_seeding_file.php
1.0.2:
    - Create blog post comments table
    - create_comments_table.php
1.0.3: Bug fix update that uses no scripts
1.0.4: Another fix
1.0.5:
    - Create blog settings table
    - create_blog_settings_table.php

For updates that refer to migration or seeding files, the first line is always the comment, then subsequent lines are script file names.

Note: The plugin initialization process is disabled during the update process, this should be a consideration in migration and seeding scripts.

Update process

Any given update file will only be applied once after a successful execution. October executes the update process automatically when any of the following occurs:

1. When an administrator signs in to the back-end.

2. When the system is updated with the built-in Update feature in the back-end.

3. When the console command php artisan october:up is called in the command line from the application directory.

Updates are applied in a specific order, based on the defined dependencies in the plugin registration file. Plugins that are dependant will not be updated until all their dependencies have been updated first.

Migration files

October migrations use the Laravel's Schema Builder. The migration file should define a class that extends the October\Rain\Database\Updates\Migration class. The class should define two public methods - up() and down(). The class name should match the script file name written in CamelCase. Inside the migration files the Author\Plugin\Updates namespace should be used. An example of a structure file:

namespace Acme\Blog\Updates;

use Schema;
use October\Rain\Database\Updates\Migration;

class CreatePostsTable extends Migration
{
    public function up()
    {
        Schema::create('october_blog_posts', function($table)
        {
            $table->engine = 'InnoDB';
            $table->increments('id');
            $table->string('title');
            $table->string('slug')->index();
            $table->text('excerpt')->nullable();
            $table->text('content');
            $table->timestamp('published_at')->nullable();
            $table->boolean('is_published')->default(false);
            $table->timestamps();
        });
    }

    public function down()
    {
        Schema::drop('october_blog_posts');
    }
}

Data seeding files

Use the the data seeding files to add, update or remove records in the database when a plugin changes its version. The file should define a class that extends the Seeder class. The class should define the public method run(). The class name should match the script file name written in CamelCase. Inside the seeding files the Author\Plugin\Updates namespace should be used. An example of a seeding file:

namespace Acme\Users\Updates;

use Seeder;
use Acme\Users\Models\User;

class SeedUsersTable extends Seeder
{
    public function run()
    {
        $user = User::create([
            'email'                 => '[email protected]',
            'login'                 => 'user',
            'password'              => 'user',
            'password_confirmation' => 'user',
            'first_name'            => 'Adam',
            'last_name'             => 'Person',
            'is_activated'          => true
        ]);
    }
}