[4.x] Document the pending tenants feature and the related commands #225
Description
title: Pending tenants
extends: _layouts.documentation
section: content
Pending tenants {#pending-tenants}
Too many tenant migrations can make creating new tenants very slow. To solve that, you can create ready to use pending tenants.
Pending tenants are tenants whose pending_since attribute is not null. Instead of creating new tenants, you can pull a pending tenant from the pending tenant pool (make them non-pending).
Pending tenants exclusion from queries
Pending tenants can get included or excluded from Tenant queries (e.g. Tenant::all()) depending on the value of the tenancy.pending.include_in_queries config key. To exclude the tenants from a query manually, add ->withoutPending() to the query, e.g. Tenant::where(...)->withoutPending() and to include them, add ->withPending() instead.
Note: See the
HasPendingandPendingScopetraits to learn more about the available methods.
Creating pending tenants
To create pending tenants, you can use the tenants:pending-create command, or the CreatePendingTenants job. By default, these create pending tenants until the maximum count (the pool size) is reached. The pool size can be changed using the 'tenancy.pending.count' config key. You can also use the Tenant::createPending() method defined in the HasPending trait.
Deleting pending tenants
To clear the pending tenant pool, you can use the tenants:pending-clear command, or the ClearPendingTenants job.
Note: Learn more about the commands on [the console commands page in the docs]({{ $page->link('console-commands') }}).
// CONSOLE COMMANDS PAGE
Tenant-aware commands and pending tenants
Tenant-aware commands respect your tenancy.pending.include_in_queries configuration. The commands also have the --with-pending option which makes the command run for pending tenants too. For example, tenants:migrate --with-pending runs tenants:migrate for the pending tenants too, even if the tenancy.pending.include_in_queries config is false.
Create pending tenants
The tenants:pending-create command creates pending tenants either until the pending tenant pool is full. You can specify how many pending tenants will be created by passing the count in the --count option.
php artisan tenants:pending-create --count=10
10 pending tenants created.
10 pending tenants ready to be used.
Clear pending tenants
The tenants:pending-clear command deletes all pending tenants. Passing the --older-than-days or the --older-than-hours option makes the command delete only the tenants that exist for more days/hours than the day/hour amount passed in the option. These two options can't be used simultaneously.
php artisan tenants:pending-clear --older-than-days=2
Removing pending tenants.
10 pending tenants deleted.