laravel migrations

[sneakyimp]

Hoping someone with laravel experience can help me get off the ground with migrations. I've been reading the docs on migrations and I feel like there's no description of a workflow or any real description of how to use these thigns.

I've also been using the artisan command line to get help:

php artisan help make:migration

But the results are curiously uninformative:

Usage:
  make:migration [options] [--] <name>

Arguments:
  name                   The name of the migration.

Options:
      --create[=CREATE]  The table to be created.
      --table[=TABLE]    The table to migrate.
      --path[=PATH]      The location where the migration file should be created.
  -h, --help             Display this help message
  -q, --quiet            Do not output any message
  -V, --version          Display this application version
      --ansi             Force ANSI output
      --no-ansi          Disable ANSI output
  -n, --no-interaction   Do not ask any interactive question
      --env[=ENV]        The environment the command should run under
  -v|vv|vvv, --verbose   Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug

Help:
  Create a new migration file

What is the significance of a migration's name? Is it the database table's name? Is it the name given to the file created?

Also, there were two files in database/migrations -- I don't recall creating these myself so I think they were somehow created during the initialization phase:

database/migrations/2014_10_12_000000_create_users_table.php
database/migrations/2014_10_12_100000_create_password_resets_table.php

I also created a couple with these commands I ran across in the configuration documents:

php artisan cache:table
php artisan session:table

which added these two files:

database/migrations/2017_02_23_222755_create_cache_table.php
database/migrations/2017_02_23_222435_create_sessions_table.php

However, despite the obvious existence of these migration files, this command says I have no migrations:

$ php artisan migrate:status
No migrations found.

I'm sitting here with a database full of tables and would like to get started with the process but lack any real overview of the process. I'm aware that these migration files:
track database changes for the purpose of collaborating with other devs via version control
are sequentially named with timestamps which permit versioning/ordering rollbacks
* when run, will actually perform the necessary database changes
However, I don't know which commands to run first, I don't know how to run these php migration files to perform the changes they contain, etc.

If anyone could suggest how I might get acquainted with the workflow, I'd greatly appreciate it.

[NogDog]

It's been awhile since I've touched Laravel (I'm now doing similar stuff in Ruby/Rails, which seems to be what Laravel patterned itself after in this respect.)

Anyway, it's possible that it thinks there are no new migrations to run? You could test that theory by doing whatever the Laravel command would be to do a migration rollback. (Either just rolling back the latest, or using whatever the arguments are to roll it all the way back and start from nothing.)

[sneakyimp]

Thanks for your response.

NogDog;11060447 wrote:

Anyway, it's possible that it thinks there are no new migrations to run?

The cache and sessions migrations have never been run. Or rather I mean to say that neither table currently exists in the database. I'm assuming that 'running' a migration will perform database changes like defining tables and stuff.

NogDog;11060447 wrote:

You could test that theory by doing whatever the Laravel command would be to do a migration rollback.

I'm not sure at all what you mean by this, but am guessing you mean this command:

php artisan migrate:rollback

which also doesn't have a very informative help entry:

$ php artisan help migrate:rollback
Usage:
  migrate:rollback [options]

Options:
      --database[=DATABASE]  The database connection to use.
      --force                Force the operation to run when in production.
      --path[=PATH]          The path of migrations files to be executed.
      --pretend              Dump the SQL queries that would be run.
      --step[=STEP]          The number of migrations to be reverted.
  -h, --help                 Display this help message
  -q, --quiet                Do not output any message
  -V, --version              Display this application version
      --ansi                 Force ANSI output
      --no-ansi              Disable ANSI output
  -n, --no-interaction       Do not ask any interactive question
      --env[=ENV]            The environment the command should run under
  -v|vv|vvv, --verbose       Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug

Help:
  Rollback the last database migration

Does 'last database migration' mean a single file? Or many files? Could really use some specificity here. I'm really reluctant to start running commands that are just going to generate more migration files and/or make unwanted changes to my database -- note that while these migration PHP files are under version control, my precious database is not.

NogDog;11060447 wrote:

(Either just rolling back the latest, or using whatever the arguments are to roll it all the way back and start from nothing.)

Having painstakingly constructed my database, I am starting from the beginning. Obviously I want migration files so that my dev partner will receive them when he does a git pull. I'm guessing I'll need at least one table creation migration file for each table. I don't know if these artisan commands will include the data or the structure only in these files? So many questions....I'm not even sure where to begin.

[sneakyimp]

So I ran make:migration with the word "fart" supplied for the name parameter (this does not correspond to any existing table) and the command did not complain.

php artisan make:migration fart

It generates migration file which I presume is pretty useless:

<?php

use Illuminate\Support\Facades\Schema;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Database\Migrations\Migration;

class Fart extends Migration
{
    /**
     * Run the migrations.
     *
     * @return void
     */
    public function up()
    {
        //
    }

/**
 * Reverse the migrations.
 *
 * @return void
 */
public function down()
{
    //
}
}

Running the command with name set to a table name that actually exists also creates a php file that does nothing:

php artisan make:migration groups

<?php

use Illuminate\Support\Facades\Schema;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Database\Migrations\Migration;

class Groups extends Migration
{
    /**
     * Run the migrations.
     *
     * @return void
     */
    public function up()
    {
        //
    }

/**
 * Reverse the migrations.
 *
 * @return void
 */
public function down()
{
    //
}
}

[NogDog]

I started to write a possibly confusing reply, then got lucky and realized that this Laracasts tutorial appears to be available for free, so I'd recommend letting Jeffrey provide what is probably a much better explanation I'd give you. 🙂

https://laracasts.com/series/laravel-5-fundamentals/episodes/7

PS: buying a month or two of a paid subscription may be well worth your time. He does a great job, IMHO.

[sneakyimp]

NogDog;11060469 wrote:

I started to write a possibly confusing reply, then got lucky and realized that this Laracasts tutorial appears to be available for free, so I'd recommend letting Jeffrey provide what is probably a much better explanation I'd give you. 🙂

https://laracasts.com/series/laravel-5-fundamentals/episodes/7

Thank you, NogDog. A month paid subscription is less than $10 I think -- surely worth it, given how much time I'm spending on wheel-spinning. My inner curmudegon (is he really inner at this point?) is furious about paying anyone for such a thing. I'm reminded of the time when I wanted to get started programming but Microsoft would gouge you several hundred bucks for Visual Studio and developer's "license" or something like that.

To be honest, I'm also having some super peevish and irritable thoughts at the Laravel zealots. "The PHP Framework For Web Artisans?" Gimme a break. :rolleyes:

[NogDog]

Wait until you have to do Ruby on Rails. Its fanboys are, well, fanatical about doing everything the Rails way. 🙂

[dalecosp]

Do you think that giving some arguments might produce some content in the output file?

[sneakyimp]

NogDog's video link is very helpful. I was laboring under the quite mistaken impression that these commands would somehow read the tables I've defined in my db and auto-generate the migration files for me. This is not the case at all I see, having watched the video. I especially like the part in the video where quickly points out some circumstance where the commands don't work and you have to install another composer (doctrine dbal) in order for the system to work. These teetering towers of tools that are supposed to make your life easier programming-wise become their own time-wasting nightmares.

dalecosp, providing a create="table_name" parameter or table="table_name" parameter will provide a little more info, but not much. Apparently these commands just create an empty boilerplate class as a starting point.

Anyways, I did find this other tool which will ostensibly generate these migration files: Laravel Migrations Generator. However, when I try to run it (it will only run after installing the php xml extension and some more composer stuff) it fails:

$ php artisan migrate:generate
Using connection: mysql

Generating migrations for: group_product_assoc, groups, product_hierarchy_assoc, product_product_assoc, products, replist, sessionsOLD, stores, tree, users, zipcode_coordinates

 Do you want to log these migrations in the migrations table? [Y/n] :
n

Setting up Tables and Index Migrations


  [Way\Generators\Filesystem\FileNotFound]                                               

  /var/www/my-project/vendor/way/generators/src/Way/Generators/templates/migration.txt  

                                                                                         

I created a github issue here.

[sneakyimp]

NogDog;11060473 wrote:

Wait until you have to do Ruby on Rails. Its fanboys are, well, fanatical about doing everything the Rails way. 🙂

UGH. I was on a project once and some overpaid clown in a NY design firm tried to strike up a conversation about how great Rails was and I disagreed with him. I didn't last long on the project, which ultimately failed.

[sneakyimp]

Alrighty I managed to get the migration generator running. The solution was to just put the migration template file in the location where the code was hoping to find it. I did these steps:

# cd into my project directory
cd /var/www/my-project
# create the directory where the file is expected
mkdir -p vendor/way/generators/src/Way/Generators/templates
# fetch the raw source code of the template file and save it in migration.txt in that folder:
curl https://raw.githubusercontent.com/Xethron/Laravel-4-Generators/master/src/Way/Generators/templates/migration.txt > vendor/way/generators/src/Way/Generators/templates/migration.txt

I was then able to run the migration generator which created a migration file for each of my tables:

php artisan migrate:generate

As I mentioned above, those few make:migration commands I ran never resulted in laravel being aware that a migration needed to be performed when I ran migrate:status. Running the cache:table and session:table commands also did not result in any change in migrate:status. However, now that I've run this generate command (and opted YES when prompted Do you want to log these migrations in the migrations table?), I finally see that migrate:status has some output:

$ php artisan migrate:status
+------+--------------------------------------------------------+
| Ran? | Migration                                              |
+------+--------------------------------------------------------+
| N    | 2014_10_12_000000_create_users_table                   |
| N    | 2014_10_12_100000_create_password_resets_table         |
| Y    | 2017_02_25_032728_create_group_product_assoc_table     |
| Y    | 2017_02_25_032728_create_groups_table                  |
| Y    | 2017_02_25_032728_create_product_hierarchy_assoc_table |
| Y    | 2017_02_25_032728_create_product_product_assoc_table   |
| Y    | 2017_02_25_032728_create_products_table                |
| Y    | 2017_02_25_032728_create_replist_table                 |
| Y    | 2017_02_25_032728_create_sessionsOLD_table             |
| Y    | 2017_02_25_032728_create_stores_table                  |
| Y    | 2017_02_25_032728_create_tree_table                    |
| Y    | 2017_02_25_032728_create_usersOLD_table                |
| Y    | 2017_02_25_032728_create_zipcode_coordinates_table     |
| N    | 2017_02_25_032801_create_cache_table                   |
| N    | 2017_02_25_032813_create_sessions_table                |
+------+--------------------------------------------------------+

Now that I have these migration files, I'm wondering a few things. Forgive me if this is a little whingey. I'm stumbling up a learning curve.

1) How does the timestamp thing work?
I'm very excited that things seem to be going somewhere, but also disappointed that I have very little idea how this process works. The documentation talks about the ability to refresh/reset/rollback, but the documentation on migrations offers no specifics at all beyond this rather useless sentence:

Each migration file name contains a timestamp which allows Laravel to determine the order of the migrations.

What would happen if I copied one of those migration files and just gave its filename a newer timestamp? Would it try to create the data table twice? What is the mechanism which tracks which migrations have been run and which have not? Is it the 'migration' table that the migrate:generate process created in my database? Is this migration table or the filenames more important when determining sequence of operations?

2) How does rollback work?
The docs are somewhat helpful here in that they explain that I can run multiple migrations with this command:

php artisan migrate

and roll back "the latest migration operation" with this command:

php artisan migrate:rollback

This is starting to make sense but I'm not really sure what the mechanism is that tracks our current migrate/rollback "counter" or whatever. My guess is that the current migration status is tracked by the migration table in the database and that the batch value in that table is some kind of cursor in the whole migration scheme. On the other hand, there might be some value cached somewhere? The whole thing is a black box and the docs do nothing to clear things up.

3) What about my data?
My database table has a lot of records in it. Looking at these migration files, I get the feeling that none of them will be preserved if I were to do a reset:

php artisan migrate:reset

[Derokorian]

sneakyimp;11060483 wrote:

This is starting to make sense but I'm not really sure what the mechanism is that tracks our current migrate/rollback "counter" or whatever. My guess is that the current migration status is tracked by the migration table in the database and that the batch value in that table is some kind of cursor in the whole migration scheme. On the other hand, there might be some value cached somewhere? The whole thing is a black box and the docs do nothing to clear things up.

It creates a migrations table in your db that tracks what migrations have been completed. I uses this to determine what the last one was, you can issue the rollback command many times in a row, to rollback many migrations.

[Derokorian]

Also, I feel like you're starting to get the feeling I had when using Laravel that made me hate it.

[NogDog]

For a bit of counter-argument, I will say this: those people I know who have more or less mastered Laravel or Rails can be very productive with it. Need a new table in your database with a many-to-one relationship to an existing one? Create a new migration (or rollback and edit an existing one) with a few lines of code, and in a minute or two, they have a new table. Use one command line entry to create the model. Add a few lines of code to create the has-many relationship, and the model is basically done. However, learning it is not necessarily easy/quick.

[sneakyimp]

Derokorian;11060499 wrote:

It creates a migrations table in your db that tracks what migrations have been completed. I uses this to determine what the last one was, you can issue the rollback command many times in a row, to rollback many migrations.

The laravel doc page on migrations is bad. For starters, this document offers a very basic introduction to the concept of migrations but at the same time seems to tacitly assume that everyone has prior experience with rails migrations.

This document does not explain that migrations are really just an alternate language describing how to construct your database. As with SQL, you end up with files of code (PHP code instead of SQL statements) and this code is executed when you run the various commands:

php artisan migrate -- runs the UP method in all of the migrations for which there is no record in the migrations table
php artisan migrate:rollback -- runs the DOWN method in all the migrations recorded in the migrations table with the highest batch number
php artisan migrate:reset -- run the DOWN method on every single migration file that has ever been run all the way back to the beginning; ordering presumably done first by batch in migrations table, then by the name of the migration
php artisan migrate:refresh -- run all the DOWN methods for every single migration, then run all the UP methods for every single migration. THIS CAN DESTROY ANY DATA YOU HAVE, depending on how the migrations were constructed.

This document does not once mention the need for and existence of a migrations table in your database. This table is apparently critical for determining which migrations have been run and in what sequence.

This document offers no guidance at all about what to do if you already have existing data. After a lot of searching, I finally located the aforementioned Laravel Migrations Generator, which has a bug one must fix before you can run it and it will also fail on older versions of MySQL unless you make additional changes to your laravel installation.. Installing it requires composer. With this tool, you can auto-generate migration files for an existing database, but these files do absolutely nothing to preserve one's data. They deal only with file structures. No mention is made with this tool of the migrations table either, so when/how that gets created (or dealt with if one already exists) is so far completely undocumented.

This document does not mention that in addition to learning the laravel-specific language for defining db tables in order to write an UP method for each migration file, one must also write a DOWN method to reverse this changes -- or rollbacks are out of the question.

MIGRATION PROS:
changes to database structures can be stored using version control system like git
helps a team of developers keep their databases in sync
command line tools to roll back and migrate again
db construction code is ostensibly independent of DBMS so project should be easily switched from one to another

MIGRATION CONS:
POOR documentation makes the learning curve hard
native tools offer no means to bootstrap migration files from existing database structure
native tools and related tools require extra configuration/debugging/troubleshooting/bug fixes to get working
not especially advantageous for lone developers
have to learn new laravel-specific syntax for table construction/destruction commands
must write code not just to create tables and make changes, but also to rollback/reverse those same changes
* no provision is made to manage actual data records. e.g., if you are migrating some large existing db to laravel.

[sneakyimp]

Derokorian;11060501 wrote:

Also, I feel like you're starting to get the feeling I had when using Laravel that made me hate it.

Does it show? Feel free to vent on your own feelings. It's always good to have anecdotal sound bites in the inevitable flame war I'll eventually have with some zealot.

[sneakyimp]

NogDog;11060503 wrote:

For a bit of counter-argument, I will say this: those people I know who have more or less mastered Laravel or Rails can be very productive with it. Need a new table in your database with a many-to-one relationship to an existing one? Create a new migration (or rollback and edit an existing one) with a few lines of code, and in a minute or two, they have a new table. Use one command line entry to create the model. Add a few lines of code to create the has-many relationship, and the model is basically done. However, learning it is not necessarily easy/quick.

I'm only just beginning to get my head around migrations, so I can't quite imagine the circumstances where the rollback/migrate back-and-forth could be very helpful but I think I know what you mean. I'm picturing benefits a bit like how non-destructive/non-linear editing has helped with audio recording. I think the laravel heart is in the right place, if that makes any sense.

So far, migrations seem possibly great for teams, except for the buggy bits with the tools. It also seems handy if one has to frequently shift one's project from one DBMS to another. For an individual (or pair of guys), it seems like a pointless chore that doubles the amount of work for no good reason. I don't recall ever having any trouble creating a new table with many-to-one relationship using good old-fashioned phpMyAdmin -- although I'm not in the habit of defining foreign key relationships. I do recall having my local copy of a site broken because I lack recent db changes made by someone else. This seems very helpful for that kind of thing.