Struct Tenant 

pub struct Tenant<DB: Database = DefaultTenantDb> {
    pub org: Org,
    /* private fields */
}

Finds the request’s tenant and gives the handler a connection scoped to it. DB defaults to Postgres, so fn handler(t: Tenant) means Tenant<sqlx::Postgres>. Borrow the connection with Tenant::conn for ORM calls.

pub async fn my_handler(mut t: Tenant) -> Result<Json<Vec<Post>>, StatusCode> {
    let posts = Post::objects().fetch_on(t.conn()).await?;
    Ok(Json(posts))
}

Fields

org: Org

Implementations

impl<DB: Database> Tenant<DB>

pub async fn pool_conn( &mut self, ) -> Result<&mut PoolConnection<DB>, TenancyError>

Borrow the tenant’s connection, taking one from the pool on first use in database mode. Use it with the sqlx query macros when the code must work on any backend. PG-only code can use Tenant::conn, which derefs to &mut PgConnection and so works with the _on helpers directly.

Errors

The pool acquire can fail when the connection was deferred.

pub async fn into_conn(self) -> Result<TenantConn<DB>, TenancyError>

Take the connection out, so the pool gets it back when it is dropped. Use it in a handler that is done with the database but still has slow work to do. Takes a connection first if the extractor deferred one.

Errors

The pool acquire can fail when the connection was deferred.

pub fn pool(&self) -> &Pool

Borrow the tenant’s crate::sql::Pool. Use it for ORM calls such as fetch or save_pool, which work the same on every backend.

The pool is tenant-scoped in both storage modes. In schema mode TenantPools::scoped_pool puts search_path in the connect options of a dedicated pool, so it never borrows from the shared registry pool and cannot pick up another tenant’s session state. Use Tenant::conn instead when you want the request’s one pinned connection. A handler that only uses the pool should take TenantScope, which holds no connection.

Cost in schema mode: one pool build on the first miss, then free — until the cache fills. scoped_pool caches per tenant slug up to max_cached_scoped_pools, 64 by default. Past that it warns and returns the new pool without caching it, so every tenant outside the cache rebuilds a pool on every request. Raise the cap if you have many tenants. Database mode reuses the tenant’s own pool throughout.

pub fn for_test(org: Org, conn: TenantConn<DB>, pool: Pool) -> Self

👎Deprecated since 0.61.6:

conn and pool can name different tenants; use Tenant::for_test_pools, Tenant::for_test_sqlite or Tenant::for_test_mysql

For tests only. Build a Tenant from an Org and a connection you already hold, skipping the extractor. It is behind the test_utils feature so a production build cannot reach it.

Nothing checks that conn and pool are the same tenant’s: prefer for_test_pools, for_test_sqlite or for_test_mysql.

impl Tenant<Sqlite>

pub fn for_test_sqlite(org: Org, pool: SqlitePool) -> Self

For tests only. org’s Tenant over its own pool, built as the extractor does, so its connection and pool() agree.

impl Tenant<MySql>

pub fn for_test_mysql(org: Org, pool: MySqlPool) -> Self

For tests only. As Tenant::for_test_sqlite, on MySQL.

impl Tenant<Postgres>

pub async fn for_test_pools( org: Org, pools: &TenantPools<Postgres>, ) -> Result<Self, TenancyError>

For tests only. org’s Tenant from pools, built as the extractor does, so its connection and pool() cannot disagree.

let mut t = Tenant::for_test_pools(org, &pools).await?;
my_function_under_test(&mut t).await?;

Errors

The pool lookup or acquire failing.

impl Tenant<Postgres>

pub fn conn(&mut self) -> &mut PgConnection

Borrow the connection as &mut PgConnection, the type sqlx and the fetch_on / get_on helpers want. Postgres only; on other backends use Tenant::pool_conn.

Trait Implementations

impl<'a, DB: Database> From<&'a Tenant<DB>> for LinkTarget<'a>

Available on crate features passwords and tenancy only.

fn from(tenant: &'a Tenant<DB>) -> Self

Converts to this type from the input type.

impl<DB: Database> From<&Tenant<DB>> for LinkScope

Available on crate feature tenancy only.

fn from(tenant: &Tenant<DB>) -> Self

Converts to this type from the input type.

impl<DB: Database> From<Tenant<DB>> for TenantScope

fn from(t: Tenant<DB>) -> Self

Converts to this type from the input type.

impl<S> FromRequestParts<S> for Tenant<Postgres>

where S: Send + Sync,

Available on crate feature postgres only.

type Rejection = TenantRejection

If the extractor fails it’ll use this “rejection” type. A rejection is a kind of error that can be converted into a response.

async fn from_request_parts( parts: &mut Parts, _state: &S, ) -> Result<Self, Self::Rejection>

Perform the extraction.

impl<S> FromRequestParts<S> for Tenant<Sqlite>

where S: Send + Sync,

Available on crate feature sqlite only.

type Rejection = TenantRejection

If the extractor fails it’ll use this “rejection” type. A rejection is a kind of error that can be converted into a response.

async fn from_request_parts( parts: &mut Parts, _state: &S, ) -> Result<Self, Self::Rejection>

Perform the extraction.

impl<S> FromRequestParts<S> for Tenant<MySql>

where S: Send + Sync,

Available on crate feature mysql only.

type Rejection = TenantRejection

If the extractor fails it’ll use this “rejection” type. A rejection is a kind of error that can be converted into a response.

async fn from_request_parts( parts: &mut Parts, _state: &S, ) -> Result<Self, Self::Rejection>

Perform the extraction.