After this lesson you can create the books table through a versioned migration and explain the consequences of reversing it. A migration describes a schema change in code. It gives another installation a repeatable way to reach the same structure instead of relying on remembered manual database edits.
Describe structure, not demonstration content
Our first table needs an identifier and a title. Keep the schema small enough to explain completely. Purchasing, inventory and author records are outside this project's scope. Adding columns because they might be useful later creates rules you have not yet designed or tested.
Create app/Database/Migrations/2026-11-14-000001_CreateBooks.php with the following class. This fixed filename makes the written course reproducible; Spark-generated migration timestamps would differ between learners. Do not create both a generated duplicate and this file.
<?php
namespace App\Database\Migrations;
use CodeIgniter\Database\Migration;
class CreateBooks extends Migration
{
public function up()
{
$this->forge->addField([
'id' => ['type' => 'INTEGER', 'auto_increment' => true],
'title' => ['type' => 'VARCHAR', 'constraint' => 120],
]);
$this->forge->addKey('id', true);
$this->forge->createTable('books');
}
public function down()
{
$this->forge->dropTable('books');
}
}The class passed PHP lint and ran against the temporary SQLite database. The up method defines fields, makes id the primary key and creates the table. The down method drops that table. Dropping a table removes its records; a reversible schema operation is not a backup of its data.
The title constraint expresses the intended schema shape, but database drivers differ in how they enforce length declarations. In particular, do not depend on a VARCHAR length alone as the application's title validator with SQLite. A later lesson checks the title at the request boundary. Schema design and application validation complement each other.
Apply and inspect the change
From the disposable project root, run the migration and inspect its status. These commands were executed in the isolated verification application, never against this repository's database.
php spark migrate
php spark migrate:statusExample output captured on 2026-11; yours will differ. These selected lines omit the timestamped banner and the status table.
Running all new migrations...
Running: (App) 2026-11-14-000001_App\Database\Migrations\CreateBooks
Migrations complete.The migration system records applied versions. Running migrate again should not create a second books table from the same already-applied migration. That behavior differs from a simple inserting seeder, which we will discuss next. Understanding which operations are tracked prevents accidental assumptions about repeatability.
Treat migration history as shared state
Once a migration has been applied in an environment you care about, changing its old up method does not automatically update the existing table. The migration is already recorded as applied. A new schema change should normally be represented by a new migration, with a plan for existing data.
During local experimentation you can discard a disposable database and rebuild it, but that is not an operational migration strategy for real records. The same command can be harmless in a fresh learning directory and destructive in a production environment. Always identify the connection before touching schema state.
The official Database Migrations guide documents migration discovery and commands. Its rollback guidance must be read with the installed version and command help: do not assume an unqualified rollback means “undo only my last line of code”. This course does not ask you to run rollback on an existing database.
Plan failure and recovery
A schema change may fail because of permissions, unsupported syntax or data incompatible with a new constraint. Preserve the error and determine whether anything was applied before retrying. Do not respond to every failure by dropping the database. Real applications need backups and a recovery plan before destructive schema work.
Our initial migration is intentionally easy to inspect. Even so, you should be able to explain the effect of both methods. If down would remove data that cannot be reconstructed, write that down as a deployment risk. The final project review asks you to separate restoring application code from restoring database state.
The fetched official Database Migrations guide supports the migration mechanism. The two-column books design is an instructional decision, not an official shop schema. It does not include uniqueness or stock constraints because those are not current requirements.
Common mistakes
Editing an already-applied migration and expecting migrate to replay it confuses source files with migration history. Running refresh as a generic troubleshooting command risks removing records. Assuming VARCHAR length replaces validation is unreliable across database drivers. Finally, creating the same table manually and through a migration can leave the migration tracker inconsistent with actual schema ownership.
Exercise
Explain why adding a field to an already-applied up method does not necessarily change an existing database. Then identify the information lost when this migration's down method runs, even if you can later recreate the table.
Show an answer
The migration runner tracks versions already applied, so it does not automatically replay the modified method. Add a new migration for a new shared schema change. Dropping books removes the rows as well as the structure. Recreating an empty table restores the schema, not the previous catalogue data.
Previous lesson · Next lesson · Related: explicit routes · Related: security boundaries
Key points
- Migrations version schema operations.
- An applied migration is not automatically replayed after editing.
- Recreating a dropped table does not restore its records.