​

Views

​

Minimal example

view ActiveCustomer from Customer, Order {
  id          Int       @id  @from(Customer.id)
  email       String         @from(Customer.email)
  orderCount  Int

  @@sql("""
    SELECT c.id, c.email, COUNT(o.id) AS order_count
    FROM   customer c
    LEFT JOIN "order" o ON o.customer_id = c.id
    GROUP  BY c.id, c.email
  """)

  @@allow("read", auth() != null)
}

​

Block header

view <Name> from <Model>, <Model>, …

• <Name> — PascalCase. Becomes the Rust struct name unchanged (ActiveCustomer) and the SQL view identifier as snake-cased + pluralized (active_customers), using the same pluralizer shared with model table names (cratestack_core::route_naming::pluralize): a trailing s gets es appended (Bus -> buses), a consonant + y becomes ies (Summary -> summaries, Category -> categories), and everything else gets a bare s (Day -> days) — your hand-written DDL or SQL body needs to use that exact identifier.
• from <Model>, … — the source-model dependency list. Each name must resolve to an existing model; the parser rejects unknown ones. The list also orders view DDL after source-model DDL during migration generation.

​

Fields

​

@id (required)

view RevenueByDay from Order {
  day      Date
  revenue  Decimal

  @@no_unique
  @@sql("…")
}

​

@from(Model.field)

view ActiveCustomer from Customer, Order {
  id          Int       @id  @from(Customer.id)   // bound
  email       String         @from(Customer.email) // bound
  orderCount  Int                                  // computed
}

​

SQL body attributes

​

@@server_sql("…") and @@embedded_sql("…")

​

@@sql("…")

​

@@allow("read", …)

@@allow("read", auth() != null)
@@allow("read", auth().role == "admin")

​

@@materialized (server-only)

view AccountBalance from Account, Transfer {
  accountId Uuid     @id  @from(Account.id)
  balance   Decimal

  @@materialized
  @@server_sql("""
    SELECT a.id AS account_id,
           a.opening_balance
           + COALESCE(SUM(t.amount), 0) AS balance
    FROM   account a
    LEFT JOIN transfer t ON t.account_id = a.id
    GROUP  BY a.id, a.opening_balance
  """)

  @@allow("read", auth().id == accountId)
}

• Calling refresh() on this view’s delegate succeeds, emitting REFRESH MATERIALIZED VIEW CONCURRENTLY <name>. refresh() itself is not conditionally generated — every ViewDelegate exposes pub async fn refresh(&self) -> Result<(), CratestackError> unconditionally, and the check is a runtime one: it returns CratestackError::Forbidden if the view isn’t @@materialized. (The separate ViewDelegateNoUnique used by @@no_unique views omits refresh() at the type level, as noted above — but that’s a distinct, unique-index-driven restriction, not how non-materialized-but-unique views are handled.)
• The migration emits CREATE MATERIALIZED VIEW <name> … plus CREATE UNIQUE INDEX <name>_pkey ON <name> (<id_column>) to back the concurrent refresh.
• @@no_unique is rejected: concurrent refresh requires a unique index, and CrateStack will not silently downgrade to a non-concurrent refresh that takes ACCESS EXCLUSIVE.

​

Generated surface

pub struct ActiveCustomer {
    pub id: i64,
    pub email: String,
    pub orderCount: i64,
}

pub const ACTIVE_CUSTOMER_VIEW: cratestack::ViewDescriptor<ActiveCustomer, i64> = /* … */;

let cool = cratestack_schema::Cratestack::builder(pool).build();

// find_many — read-only iteration with filter / order / limit.
let rows = cool
    .views()
    .active_customer()      // ViewDelegate<'_, ActiveCustomer, i64>
    .find_many()
    .run(&ctx)              // CratestackContext drives `@@allow` enforcement
    .await?;

// find_unique — single-row lookup by PK. Returns Option<ActiveCustomer>.
let one = cool.views().active_customer().find_unique(customer_id).run(&ctx).await?;

​

Parse-time validation summary

​

Read Next

1. Materialized views guide — when and how to call refresh()
2. ADR 0003: SQL views as projections of models — design rationale
3. Migrations — how view DDL flows through the migration runner