For Rails developers exploring Phoenix, understanding how Phoenix Scopes work requires grasping a fundamentally different approach to authorization. While both CanCan and Phoenix Scopes control data access, Phoenix leverages Elixir’s unique features—particularly pattern matching and compile-time guarantees—to create authorization patterns that may feel foreign but offer compelling advantages over Rails’ conventional approaches.

CanCan’s accessible_by Method: Query Scoping Through Hash Conditions

The heart of CanCan’s data access control is the accessible_by method, which transforms ability definitions into ActiveRecord scopes. This method returns a scoped collection that includes only records the current user can access.[1][2][3]

Hash Conditions: The Foundation of Query Scoping

CanCan’s most powerful feature for data access control relies on hash conditions that can be directly translated to SQL WHERE clauses:

# In Ability class
class Ability
  def initialize(user)
    can :read, Post, user_id: user.id, published: true
    can :manage, Post, user_id: user.id
  end
end

# In controller
@posts = Post.accessible_by(current_ability)
# Generates: SELECT * FROM posts WHERE user_id = ? AND published = true

The accessible_by method examines the ability definitions and constructs database queries that automatically filter results based on the hash conditions. This allows CanCan to push authorization logic down to the database level, ensuring efficient queries that only retrieve authorized records.[2][4]

The Block vs Hash Limitation

CanCan supports two types of ability definitions, but only hash conditions work with accessible_by:

# Hash conditions - WORKS with accessible_by
can :read, Post, user_id: user.id

# Block conditions - CANNOT be used with accessible_by
can :read, Post do |post|
  post.user_id == user.id && post.created_at > 1.week.ago
end

When block conditions are used, CanCan cannot generate SQL and will raise an error: “The accessible_by call cannot be used with a block ‘can’ definition. The SQL cannot be determined”. This is because blocks contain arbitrary Ruby logic that cannot be translated to database queries.[5][6]

Conditional Abilities for Record-Level Access Control

CanCan’s conditional abilities provide sophisticated record-level access control through several mechanisms:

# Hash-based Record Filtering
can :read, Post, organization_id: user.organization_id
can :manage, Project, status: 'active', user_id: user.id

# Association-based Authorization
can :read, Comment, post: { user_id: user.id }
can :manage, Task, project: { team: { members: { user_id: user.id } } }

# Range and Array Conditions
can :read, Post, created_at: 1.month.ago..Time.current
can :read, Post, category_id: [1, 2, 5, 8]

These conditional abilities allow CanCan to create complex WHERE clauses that ensure users only access records meeting specific criteria. The accessible_by method automatically combines multiple can statements with OR logic, creating comprehensive query scopes.

Phoenix Scopes: Leveraging Elixir’s Type System for Authorization

Phoenix Scopes represent a paradigm shift for Rails developers: instead of relying on developer discipline, they use Elixir’s type system and pattern matching to make authorization structurally impossible to bypass.[7][8]

Understanding Elixir Structs as Authorization Containers

For Rails developers familiar with classes and objects, Elixir structs are lightweight data containers—think of them as simplified Ruby classes that only hold data:

# Define a struct (similar to a Ruby class with attr_accessor)
defmodule MyApp.Accounts.Scope do
  defstruct [:user, :organization]  # These are the allowed fields
  
  # Factory function to build scopes (similar to a Rails factory)
  def for_user(%User{} = user) do
    %__MODULE__{user: user, organization: user.organization}
  end
end

The %User{} syntax is pattern matching—Elixir’s way of ensuring the parameter is actually a User struct, providing compile-time safety that Rails lacks.

Function Signatures Enforce Authorization

Unlike CanCan’s opt-in accessible_by, Phoenix Scopes make scoped access mandatory through function signatures. In Elixir, you must declare what types your function accepts:[7]

# The %Scope{} pattern REQUIRES a Scope struct - no exceptions
def list_posts(%Scope{} = scope) do
  # Ecto query syntax (Phoenix's ActiveRecord equivalent)
  Repo.all(from p in Post, where: p.user_id == ^scope.user.id)
  #        ^ "from" starts the query
  #                               ^ "^" injects Elixir variables into SQL
end

def get_post!(%Scope{} = scope, id) do
  # Repo.one! raises if no record found (like Rails' find!)
  Repo.one!(from p in Post, 
    where: p.id == ^id and p.user_id == ^scope.user.id)
end

def create_post(%Scope{} = scope, attrs) do
  %Post{}  # Create empty struct
  |> Post.changeset(Map.put(attrs, "user_id", scope.user.id))  # Validate
  |> Repo.insert()  # Save to database
  # ^ The |> "pipe operator" is like Ruby's method chaining
end

Key insight for Rails developers: Once you establish scopes via mix phx.gen.auth, Phoenix generators create only scoped functions by default. You literally cannot call these generated functions without a Scope struct, making unauthorized access structurally impossible. (You can opt out with --no-scope, but secure-by-default is the intended path.)

Pattern Matching: Elixir’s Super-Powered Case Statements

Pattern matching lets you define multiple function clauses that handle different authorization scenarios. Think of it as having multiple method definitions that Elixir chooses between automatically:

# Multiple function definitions with different patterns
# Elixir picks the first one that matches the input

# Match admin users specifically
def list_posts(%Scope{user: %User{role: "admin"}}) do
  Repo.all(Post)  # Admins see everything
end

# Match regular users (any non-admin User)
def list_posts(%Scope{user: %User{} = user}) do
  Repo.all(from p in Post, where: p.user_id == ^user.id)
end

# Match organization-scoped access
def list_posts(%Scope{organization: org}) when not is_nil(org) do
  Repo.all(from p in Post, 
    join: u in User, on: u.id == p.user_id,
    where: u.organization_id == ^org.id)
end

Rails equivalent would require multiple if/else statements inside one method, but Elixir’s pattern matching makes each authorization case a separate, testable function clause.

Key Architectural Differences: What Rails Developers Need to Know

1. Authorization Enforcement Philosophy

CanCan: Authorization is opt-in and relies on developer discipline. You must remember to use accessible_by everywhere, or risk exposing unauthorized data. It’s like having security as a linter rule—helpful but not enforced.

Phoenix Scopes: Authorization is structurally enforced through tooling. After running mix phx.gen.auth to establish a default scope, subsequent Phoenix generators (mix phx.gen.live, mix phx.gen.html, mix phx.gen.json) automatically generate scoped functions, making secure authorization the default path rather than an afterthought.[7]

2. Centralized vs. Distributed Query Logic

CanCan: Uses centralized ability definitions in one file that work for both individual record checks (can?) and query scoping (accessible_by). This feels familiar to Rails developers who like keeping related logic together.[4]

Phoenix Scopes: Each context function explicitly implements its own scoped queries. While this seems repetitive to Rails developers, it provides complete control over query optimization and makes authorization logic explicit at the point of data access.[8]

3. Handling Complex Authorization

CanCan: Limited to hash conditions for query scoping. Complex logic requiring blocks cannot be used with accessible_by, creating the frustrating choice between flexible authorization (blocks) and efficient queries (hashes).[6]

Phoenix Scopes: Every function has full Elixir/Ecto capabilities. Complex authorization logic can be implemented without losing query efficiency because you’re writing the queries directly:

def list_posts(%Scope{user: user}) do
  # Full query control means complex logic + efficiency
  Repo.all(from p in Post,
    where: p.user_id == ^user.id,
    where: p.created_at > ago(30, "day"),
    where: fragment("? @> ?", p.tags, ^["published"]),
    order_by: [desc: p.updated_at],
    limit: 50)
end

4. Multi-tenancy Support

CanCan: Multi-tenant applications typically require additional gems like acts_as_tenant or complex ability definitions that can become unwieldy.[9]

Phoenix Scopes: Multi-tenancy is natural because scope structs can hold any authorization context. Rails developers will appreciate how clean this feels:

defmodule MyApp.Accounts.Scope do
  defstruct [:user, :organization, :tenant_id, :permissions]
end

# Multi-tenant query is just another field access
def list_posts(%Scope{tenant_id: tenant_id}) do
  Repo.all(from p in Post, where: p.tenant_id == ^tenant_id)
end

Performance and Database Efficiency: A Rails Developer’s Perspective

CanCan’s Approach: Familiar but Limited

CanCan’s accessible_by method feels natural to Rails developers—it generates efficient SQL by translating hash conditions directly to WHERE clauses, just like ActiveRecord scopes:[2]

can :read, Post, user_id: user.id
can :read, Post, status: 'public'

# Generates familiar SQL: WHERE (user_id = ? OR status = 'public')

However, the inability to use blocks with accessible_by can force developers into inefficient workarounds when complex authorization is needed.[10]

Phoenix Scopes: Full Query Control

Phoenix Scopes give you complete control over query construction—like writing raw ActiveRecord queries but with built-in authorization context. This lets you optimize for specific use cases:

def list_user_posts(%Scope{user: user}) do
  # Simple scoped query (like a Rails scope)
  Repo.all(from p in Post, where: p.user_id == ^user.id)
end

def list_team_posts(%Scope{user: user}) do
  # Complex optimized query with joins and preloads
  # (like includes() in Rails but more explicit)
  Repo.all(from p in Post,
    join: tm in TeamMember, on: tm.user_id == ^user.id,
    join: t in Team, on: t.id == tm.team_id,
    where: p.team_id == t.id,
    preload: [:user, :team])  # Like Rails' includes()
end

For Rails developers: Think of each scoped function as having its own custom ActiveRecord scope, but with authorization built into the function signature rather than relying on controller-level filtering.

Conclusion

Understanding Phoenix Scopes becomes easier when viewed through the lens of CanCan’s familiar patterns, though they represent fundamentally different authorization philosophies:

CanCan provides a centralized, declarative approach where hash conditions enable efficient query scoping through accessible_by. Its conditional abilities offer powerful record-level access control, but the limitation that blocks cannot be used with query scoping can create architectural tensions in complex applications.

Phoenix Scopes implements structural authorization where secure access is the default through mandatory scope parameters. This approach offers complete flexibility in implementing authorization logic while maintaining query efficiency, making it particularly well-suited for multi-tenant applications and complex authorization scenarios.

For Rails developers learning Phoenix, the key insight is that Phoenix Scopes trade CanCan’s centralized ability definitions for compile-time safety and structural enforcement. Where CanCan relies on developer discipline to use accessible_by, Phoenix Scopes make secure data access the only option through function signatures, representing an evolution toward “secure by default” authorization patterns.

References

1. CanCan accessible_by - Stack Overflow
2. CanCan ModelAdditions Documentation
3. CanCanCan Rails Authorization Dance - SitePoint
4. CanCanCan Cheatsheet
5. CanCanCan Google Groups Discussion
6. CanCan and accessible_by SQL Error - Stack Overflow
7. Phoenix 1.8 Released
8. Phoenix Scopes Documentation
9. CanCan Multi-tenant Access - Stack Overflow
10. Authorization in Rails with CanCanCan