Reference · Tenants

with_tenant

with_tenant(str, fn) -> any

What it does

Runs the function for a tenant, with its database, its live updates, and its rooms of channels and its media streams, and gives what the function gives. For code outside a request: a script, a scheduled job that loops over the tenants. Its database is made and migrated if there is none, so to sign a tenant up use new_tenant, which refuses a name that is taken. The name must be a valid tenant's name: lowercase letters, digits, - and _, at most 63, starting with a letter or a digit. See Many tenants.

Examples

schedule("@daily", () => {    for t in db.tenants() { with_tenant(t, () => db.exec("delete from tokens where expires < ?", now())) }})

print(with_tenant("acme", () => tenant()))print(with_tenant("acme", () => 1 + 1))

acme2

Edge cases

• The function's value comes back as it is, an error value included; ? and ?? work on the result.
• Calls nest: inside, tenant() is the innermost name; afterwards the outer tenant (or none) is back, also when the function fails.
• A valid name may start with a digit and be 63 characters long; 64 is too many, and a capital letter, a space or a leading - is refused, so a name from a form is checked here before it can become a file or database name.
• Global variables are the same for every tenant: the function sees them as any code does.
• In a job, channel.broadcast and media.close reach every tenant's rooms and streams; inside with_tenant they reach that tenant's alone (since 0.7).

print(with_tenant("acme", () => err("no such plan")) ?? "defaulted")print(with_tenant("9lives", () => with_tenant("a-b_c", () => tenant())), tenant())print(with_tenant("x" | repeat(63), () => len(tenant())))

defaulteda-b_c null63

Errors

A name that cannot be a tenant's, a name that is not a string, and a second argument that is not a function are runtime errors, not error values. A runtime error inside the function is the call's.

with_tenant("Acme Inc", () => 1)

line 1: `with_tenant`: "Acme Inc" cannot be a tenant's name (lowercase letters, digits, - and _)

with_tenant("x" | repeat(64), () => 1)

line 1: `with_tenant`: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" cannot be a tenant's name (lowercase letters, digits, - and _)

with_tenant("acme", 42)

line 1: `with_tenant` expects a function second, got int

Chaining

The name is the first argument, so a pipeline hands it in; db.tenants() lists the names to loop over:

print("acme" | with_tenant(() => tenant()))print(["acme", "beta"] | map((t) => with_tenant(t, () => upper(tenant()))))

acme["ACME", "BETA"]

See also

tenant, tenant_from, db.tenants, db.open, schedule

Edit this page on GitHub · every example's output was made by running it (tools/refcheck.mjs) · questions on Discord or r/quillo