[11.x] Remove mentions of Eloquent truncate from docs

[vadimonus]

Rebasing #10116 for 11.x . (has some discussion)

There are some issues and long dicsussions around truncate method and PostgreSQL CASCADE behaviour.
some of them (and many more pull requests):

• Truncating tables in mysql, sqlite, sqlserver abstractions do not cascade, postgres does. This is unexpected and a leaky abstraction framework#35157
• Model::truncate() cleares all foreign key records in postgres framework#29506
• [11.x] Added useCascadeTruncate method for PostgresGrammar framework#53343
• Calrifying risks of using truncate #10118

Currently documentation says This means that all foreign key related records in other tables will be deleted as well.. This wording is very soft and does not highlight the full danger. Truncate cascade will fully truncate any tables, that has foreign keys pointing current table. Not only those records, that has foreign keys. Records, having null in foreign key columns will be also deleted.

While discussing if postgresql should use CASCADE in truncates, no one speaks, that using truncate is bad practice at all.

First of all, TRUNCATE SQL command is part of Data Definition Language (DDL), and DELETE is part of Data Manipulation Language (DML). So, using TRUNCATE is ok somewhere in migrations, but not in regular code. In other words, delete is for developers, truncate is for database administrators. More at https://stackoverflow.com/a/139633
Depending on sql server truncate may not respect transactions and many checks in database integrity. Delete always respects all currently enabled data integrity mechanisms (foreign keys, constraints, etc).

So, using Truncate in regular code (meaning code, that manipulates data) is bad pattern. Mentioning Truncate in the same context as Delete in the documentation gives new developers the incorrect impression that these commands are equivalent operations. We cannot change the behavior of the framework without breaking backward compatibility. But we can remove mention of truncate from the documentation, and we will save many novice developers from stupid mistakes. Experienced developers will easily find the truncate command in the source code and can use it at their own risk.

Following the rule that all undocumented methods are used at your own risk, removing the truncate method from the documentation will remove all further questions about how exactly this method should work, reducing the number of complaints to the framework developers about the fact that the method does not work as expected. This reduce need of support recently introduced PostgresGrammar::$cascadeTruncate and change it to false in future.

Introduce this change in documentation (and idea, that regular developers and new projects should not use truncate) together with release of Laravel 12 is the most gentle way to solve this complicated situation

[taylorotwell]

We need to mention how to delete all records.

[vadimonus]

We need to mention how to delete all records.

Now both pages have such examples

• Flights:: query()->delete()
• DB::table('users')->delete()