PHPackages                             mattkingshott/waterfall - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Database & ORM](/categories/database)
4. /
5. mattkingshott/waterfall

Abandoned → [caneara/waterfall](/?search=caneara%2Fwaterfall)ArchivedLibrary[Database & ORM](/categories/database)

mattkingshott/waterfall
=======================

A package that performs cascading deletes in batches to ease database strain

v2.0.2(4y ago)6917MITPHPPHP ^8.0

Since Jan 14Pushed 3y ago1 watchersCompare

[ Source](https://github.com/caneara/waterfall)[ Packagist](https://packagist.org/packages/mattkingshott/waterfall)[ Docs](https://github.com/mattkingshott/waterfall)[ RSS](/packages/mattkingshott-waterfall/feed)WikiDiscussions main Synced today

READMEChangelog (7)Dependencies (2)Versions (8)Used By (0)

Waterfall
=========

[](#waterfall)

This package enables a Laravel application to perform database cascading delete operations in staggered batches. The primary benefit of this approach, is that it avoids overwhelming the database with a massive amount of record deletion tasks when operating large-scale applications e.g. analytic platforms.

Who is this for?
----------------

[](#who-is-this-for)

If you're building a small application, or your database is unlikely to ever see cascade deletions exceeding a few thousand records, then you can probably make do without this package. Simply enforce cascade deleting in your migrations as you normally would.

If your database contains or will contain hundreds of thousands, millions or even billions of records, and the deletion of a record will cause a cascade involving a similar number of records, then it is likely to overwhelm your database. In this scenario, Waterfall can be a good choice.

The package is also a good choice if you're using a so-called 'NewSQL' platform that doesn't offer cascade deletion (e.g. because of a lack of foreign key constraints).

How does it work?
-----------------

[](#how-does-it-work)

The process is fairly simple. You define a job e.g. `DeleteUserJob` that extends Waterfall's own `Waterfall\Jobs\Job`. Within this job, you configure the cascade tasks that need to be performed. When you're ready to delete a 'user' record, you dispatch `DeleteUserJob` and provide it with the ID of the 'user'.

Waterfall will then perform the following tasks

1. Soft delete the main record (user).
2. Iterate through the cascade tasks.
    1. Delete a batch of related records (1000).
    2. If more records are available, sleep for a short time, then dispatch another job to repeat (i).
    3. If no more records are available, sleep for a short time, then dispatch another job to continue 2.
3. When all tasks have been completed, hard delete the main record (user).

Installation
------------

[](#installation)

Pull in the package using Composer:

```
composer require caneara/waterfall
```

Upgrading
---------

[](#upgrading)

Version 2 introduces a completely different way of configuring tasks. In version 1, tasks were configured using a series of parameters on the `create` factory method, however with the addition of hooks, this became quite cumbersome.

As a result, the `Task` class was refactored to provide a series of setter methods that can be chained together to build up the task. It is recommended that you re-read all of the readme when upgrading.

Configuration
-------------

[](#configuration)

Waterfall includes a configuration file that allows you to:

1. Set the queue name to use for the cascade deletion jobs (defaults to 'deletion').
2. Set the batch size / number of records to delete per query (defaults to 1000).
3. Set the rest time in seconds to give the database between batches (defaults to 5).

If you wish to change any of these values, publish the configuration file using Artisan:

```
php artisan vendor:publish
```

Note that as of version 2, you can override the batch size and rest time within individual tasks. Therefore, if you intend to set custom values for your tasks and are happy with the default queue name, there is no need to publish the configuration file.

Queues
------

[](#queues)

Make sure to only create a small number of workers for the queue e.g. 2 or 3. Too many workers risks overwhelming the database, which completely negates the purpose of the package.

Usage
-----

[](#usage)

In order for Waterfall to delete records without triggering a cascade, the associated `Model` class must implement Laravel's built-in soft deleting. Begin by adding the `SoftDeletes` trait to the model class e.g.

```