[4.x] Document the pending tenants feature and the related commands

[lukinovec]

---

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 HasPending and PendingScope traits 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.

[stancl]

Adding a note to mention casting maintenace_mode to an array in the Tenant model https://discord.com/channels/976506366502006874/1043694788358189167/1077246349428396042

[lukinovec]

Thanks for the note @stancl, I mentioned that in the related issue

[stancl]

Ah nevermind, I opened the wrong thread here. It does belong to #214 yeah