Migrations in BowPHP

• Introduction
• Adding a migration
• Migration structure
• Running migrations
• Rolling back migrations
• Creating a table
• Database connection and table options
• Renaming / Dropping tables
• Creating columns
• Migration API
  • Let's take a look together
  • List of helpers

Introduction

Migrations are a way to version your database, which often evolves along with changes to your application.

Migrations are stored in the migration folder.

Adding a migration

To add a migration, use php bow with the add:migration command followed by the name of the migration (e.g. createTodosTable). Bow will create a file with the same name, prefixed with a creation date.

php bow add:migration create_todos_table

The --table and --create options can also be used to specify the table name and to indicate whether the migration will create a new table. These options pre-fill the generated migration stub file with the specified table:

If you want to add the table name directly in the migration, add the --create=table_name or --table=table_name flag.

php bow add:migration create_todos_table --create=todos

php bow add:migration create_todos_table --table=todos

Migration structure

A migration class contains two methods: up and rollback. The up method is used to add new tables, columns, or indexes to your database, while the rollback method should reverse the operations performed by the up method.

For example, the migration created previously:

use Bow\Database\Migration\Migration;
use Bow\Database\Migration\SQLGenerator;

class Version20190929153939CreatTodosTable extends Migration
{
  /**
   * Create Table
   */
  public function up()
  {
    $this->create("users", function (SQLGenerator $table) {
      $table->addIncrement('id');
      $table->addTimestamps();
    });
  }

  /**
   * Drop Table
   */
  public function rollback()
  {
    $this->dropIfExists("users");
  }
}

Running migrations

To run all of your pending migrations, run the migration:migrate Bow command:

php bow migration:migrate

You can also use the migrate shortcut.

php bow migrate

Rolling back migrations

To undo the latest migration operation, you can use the rollback command. This command rolls back the last "batch" of migrations, which may include several migration files:

php artisan migration:rollback

The migration:reset command rolls back all of your application's migrations:

php artisan migration:reset

Creating a table

To create a new database table, use the create method. The create method accepts two arguments. The first is the name of the table, while the second is a closure that receives a \Bow\Database\Migration\SQLGenerator::class object that can be used to define the new table:

$this->create("users", function (SQLGenerator $table) {
  $table->addIncrement('id');
  $table->addTimestamps();
});

Database connection and table options

If you want to perform a schema operation on a database connection other than the default connection, use the following connection method:

$this->connection('name')->create("users", function (SQLGenerator $table) {
  $table->addIncrement('id');
  $table->addTimestamps();
});

You can use the following commands in the schema generator to define the table options:

Parameter	Description
$table->withEngine('InnoDB')	Here, we change the storage engine
$table->withCharset('utf8')	Here, we change the encoding
$table->withCollation('utf8_unicode_ci')	Here, we specify a default collation for the table

Renaming / Dropping tables

To rename an existing database table, use the renameTable method:

public function up()
{
  $this->renameTable($from, $to);
}

To drop an existing table, you can use the drop or dropIfExists methods:

public function rollback()
{
  $this->drop('users');
  
  $this->dropIfExists('users');
}

Before renaming a table, you should verify that all foreign key constraints on the table have an explicit name in your migration files instead of letting BowPHP assign a name based on a convention. Otherwise, the foreign key constraint name will refer to the old table name.

Creating columns

The alter method on Bow\Database\Migration\Migration::class can be used to update existing tables. Like the create method, the alter method accepts two arguments: the name of the table and a closure that receives an instance of \Bow\Database\Migration\SQLGenerator::class that you can use to add columns to the table:

public function up()
{
  $this->alter('users', function (SQLGenerator $table) {
    $table->addString('name');
  });
}

Migration API

For now, note that all of these methods are in fact helpers for the addColumn method of \Bow\Database\Migration\SQLGenerator::class.

Let's take a look together

Prototype of the addColumn method.

$table->addColumn(string $column_name, string $column_type, array $column_attributes);

Parameter	Type	Description
$column_name	String	The name of the table column
$column_type	String	The type of the table column
$column_attributes	Array	The various column attributes depending on the type

List of attributes: unique, primary, index, increment, default, size, nullable, unsigned.

Parameter	Type	Description
unique	Boolean	Adds UNIQUE to the column definition
primary	Boolean	Defines the column as a primary key. Adds PRIMARY AUTO to the column definition
index	Boolean	Defines the column as an INDEX
increment	Boolean	Defines the column as AUTO INCREMENT
size	Integer	Defines the size of the column
nullable	Boolean	The column can have a null value
unsigned	Boolean	Only for numeric columns. It defines the column as unsigned
default	Mixed	Adds a default value to the column if no value is provided

Let's take a look at this example together:

$table->addColumn('id', 'int', [
  'primary' => true,
  'increment' => true,
  'size' => 11
]);

$table->addColumn('price', 'int', [
  'size' => 11,
  'unsigned' => true
]);

$table->addColumn('name', 'string', [
  'nullable' => true,
  'default' => 'Franck DAKIA',
  'size' => 200
]);

List of helpers

Of course, the schema generator contains various column types that you can specify when building your tables:

Command	Description
$table->addIncrement('id')	Auto-incrementing column equivalent to INTEGER (primary key).
$table->addBigIncrement('id')	Auto-incrementing column equivalent to BIGINT (primary key).
$table->addMediumIncrement('id')	Auto-incrementing column equivalent to MEDIUMINT (primary key).
$table->addString('name', $attr = [])	Column equivalent to VARCGAR.
$table->addInteger('price', $attr = [])	Column equivalent to INTEGER.
$table->addBigInteger('price', $attr = [])	Column equivalent to BIGINT.
$table->addDouble('price', $attr = [])	Column equivalent to DOUBLE.
$table->addTinyInteger('status', $attr = [])	Column equivalent to TINYINT
$table->addMediumInteger('status', $attr = [])	Column equivalent to MEDIUMINT
$table->addBoolean('column')	Column equivalent to BOOLEAN
$table->addFloat('column')	Column equivalent to FLOAT
$table->addFloatPrimary('column')	Column equivalent to FLOAT (primary key)
$table->addDouble('column')	Column equivalent to DOUBLE
$table->addDoublePrimary('column')	Column equivalent to DOUBLE (primary key)
$table->addUuid('uuid')	Column equivalent to UUID
$table->addBinary('uuid')	Column equivalent to BINARY
$table->addIpAddress('uuid')	Column equivalent to IP
$table->addMacAddress('uuid')	Column equivalent to MAC
$table->addDatetime('date_column')	Column equivalent to DATETIME
$table->addDate('date_column')	Column equivalent to DATE
$table->addTime('date_column')	Column equivalent to TIME
$table->addYear('date_column')	Column equivalent to YEAR
$table->addTimestamp('date_column')	Column equivalent to TIMESTAMP
$table->addTimestamps()	Adds the updated_at and created_at columns as TIMESTAMP

Is something missing?

If you run into problems with the documentation or have suggestions to improve the documentation or the project in general, please open an issue for us, or send a tweet mentioning the Twitter account @bowframework or directly on github.