Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Loading…

Added Foreign Key section to Schema.md #115

Closed
wants to merge 14 commits into from

8 participants

@arvidbjorkstrom

As reported by @billmn

schema.md
@@ -108,3 +109,38 @@ Command | Description
`$table->dropPrimary('users_id_primary');` | Dropping a primary key from the "users" table
`$table->dropUnique('users_email_unique');` | Dropping a unique index from the "users" table
`$table->dropIndex('geo_state_index');` | Dropping a basic index from the "geo" table
+
+<a name="foreign-keys"></a>
+## Adding Columns
+
+When building your database you're very likely have columns in one table referencing primary keys of another table, for instance when you're using [Eloquent's Relationships](/docs/eloquent#relationships) features. If you let your database engine know this you can leverage it's capacity for keeping this data consistent and working smothly.
+
+> **Note:** Both columns muse be of the same type. Primary keys are unsigned integers so referencing columns need to be `->unsigned()` aswell.

"muse" => "must"
"aswell" => "as well"

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
schema.md
@@ -108,3 +109,38 @@ Command | Description
`$table->dropPrimary('users_id_primary');` | Dropping a primary key from the "users" table
`$table->dropUnique('users_email_unique');` | Dropping a unique index from the "users" table
`$table->dropIndex('geo_state_index');` | Dropping a basic index from the "geo" table
+
+<a name="foreign-keys"></a>
+## Adding Columns
+
+When building your database you're very likely have columns in one table referencing primary keys of another table, for instance when you're using [Eloquent's Relationships](/docs/eloquent#relationships) features. If you let your database engine know this you can leverage it's capacity for keeping this data consistent and working smothly.
+
+> **Note:** Both columns muse be of the same type. Primary keys are unsigned integers so referencing columns need to be `->unsigned()` aswell.
+
+> **Note:** The referenced table must created before the referencing table.

"must created" => "must be created"

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@arvidbjorkstrom

Thank you Gary!

schema.md
@@ -108,3 +109,38 @@ Command | Description
`$table->dropPrimary('users_id_primary');` | Dropping a primary key from the "users" table
`$table->dropUnique('users_email_unique');` | Dropping a unique index from the "users" table
`$table->dropIndex('geo_state_index');` | Dropping a basic index from the "geo" table
+
+<a name="foreign-keys"></a>
+## Adding Columns
+
+When building your database you're very likely have columns in one table referencing primary keys of another table, for instance when you're using [Eloquent's Relationships](/docs/eloquent#relationships) features. If you let your database engine know this you can leverage it's capacity for keeping this data consistent and working smothly.
+
+> **Note:** Both columns must be of the same type. Primary keys are unsigned integers so referencing columns need to be `->unsigned()` as well.

PKs need not be unsigned ints. They could be anything.

True, I'll correct the line. Thanks for the feedback! =)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@conradkleinespel

:+1: This is a must have IMO. Especially since the Fluent query builder is a bit weird to understand for newcomers (it's not in the DB component, it creates properties on the fly, etc) so looking through the source is not the easiest I guess.

@arvidbjorkstrom

Hmm. After som merge related issues (as you can see in the commits tab.. :-/ ) I managed to push some changes based on the feedback of @conradkleinespel

@alexandre-butynski

There are still few typos but the content is great and this section could be really helpful (I think I would have saved one hour this morning if I had access to this section).

Why this pull request isn't accepted and how could I help you to improve your work ?

@taylorotwell

Frankly I'm going to keep foreign keys an "underground" feature for now as they usually cause more trouble for people who go crazy with adding them then complain their seeds don't work.

@GaryJones

That would be a poor solution IMHO.

If people are getting it wrong, write better documentation, write better code. Not documenting what is a great feature means that some folks will be missing out, and those who are clueless but still want FKs will be creating even more support tickets because there wasn't even a bit of documentation to guide them.

@conradkleinespel

:+1: @GaryJones. This is like saying "People are stupid, let's not try to confuse them.". If their seeds don't work because of the FKs, it means that their tests make no sense since they don't even take FKs into account.

@GaryJones

Right - if a developer is using L4, and trying to seed a database with it, then there's a good chance they are competent enough know what a FK is, and may want to use it. Not having it documented just means it's harder for them to get up to speed with the syntax.

When others complain because their seeds don't work (and there will be some, regardless of whether FKs are documented or not), being able to point them to the correct information about FKs is handier than having various people try and explain it to them individually.

There's not really a thing such as "underground" when the code is open and going to get a lot of natural exposure, so document the hell out of each feature instead.

@betawax

In my opinion, foreign keys are an important aspect when modeling your database and therefore must be documented. Omit this just because some people maybe run into problems disadvantages all developers who understand foreign keys and use it to build their apps.

Why not just note the foreign keys vs. seeding topic in the docs?

@billmn

Agree with @betawax ... Document a functionality is always important and a developer must know how FK works before using it ...

A warning box that inform for possible problems with seeding I think is better

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
This page is out of date. Refresh to see the latest.
Showing with 40 additions and 2 deletions.
  1. +1 −1  routing.md
  2. +38 −0 schema.md
  3. +1 −1  security.md
View
2  routing.md
@@ -113,7 +113,7 @@ If a response is returned from a filter, that response will be considered the re
**Specifying Filter Parameters**
- Route::filter('age', function($value)
+ Route::filter('age', function($route, $request, $value)
{
//
});
View
38 schema.md
@@ -6,6 +6,7 @@
- [Dropping Columns](#dropping-columns)
- [Adding Indexes](#adding-indexes)
- [Dropping Indexes](#dropping-indexes)
+- [Foreign Keys](#foreign-keys)
<a name="introduction"></a>
## Introduction
@@ -108,3 +109,40 @@ Command | Description
`$table->dropPrimary('users_id_primary');` | Dropping a primary key from the "users" table
`$table->dropUnique('users_email_unique');` | Dropping a unique index from the "users" table
`$table->dropIndex('geo_state_index');` | Dropping a basic index from the "geo" table
+
+<a name="foreign-keys"></a>
+## Adding Columns
+
+When building your database you're very likely have columns in one table referencing primary keys of another table, for instance when you're using [Eloquent's Relationships](/docs/eloquent#relationships) features. If you let your database engine know this you can leverage it's capacity for keeping this data consistent and working smothly.
+
+**Creating The Referencing Column**
+
+ $table->integer("user_id")->unsigned()->index();;
+
+Make sure the new column matches the data type of referenced column. The column needs to be able to store any data the referenced column can store, otherwise you will probably run into trouble at some point.
+
+> **Note:** The referenced table must be created before the referencing table.
+
+**Add A Foreign Key Constraint**
+
+ $table->foreign("user_id")->references('id')->on('users');
+
+But to really leverage the database engine you'll probably want to specify what you want it to do when the referenced column is updated or deleted
+
+ $table->foreign("user_id")->references('id')->on('users')->onDelete('restrict');
+
+ $table->foreign("user_id")->references('id')->on('users')->onUpdate('cascade')->onDelete('restrict');
+
+Option | Description
+------------- | -------------
+`restrict` | Prevents deletion of the referenced row or updates of the foreign key
+`cascade` | The action replicates - the new value is adopted, or the row is deleted along with the referenced row
+`set null` | The value is set to null when the foreign key is updated or deleted
+`no action` | Error is raised, but the action is performed **This is the default option**
+`set default` | The value is set to the default for the column when the foreign key is updated or deleted
+
+> **Note:** `set default` is not supported by MySQL InnoDB!
+
+**Dropping Foreign Key Constraints**
+
+ $table->dropForeign("user_id");
View
2  security.md
@@ -70,7 +70,7 @@ Once a user is authenticated, you may access the User model / record:
$email = Auth::user()->email;
-The `validate` method allows you to validate a user's crednetials without actually logging them into the application:
+The `validate` method allows you to validate a user's credentials without actually logging them into the application:
**Validating User Credentials Without Login**
Something went wrong with that request. Please try again.