Database Migrations

This document describes the database migration file that creates the five permission tables required by the Hypervel Permission package. It covers the table structures, indexes, polymorphic relationships, and the is_forbidden mechanism for negative permissions.

For information about the Eloquent models that interact with these tables, see Role Model and Permission Model. For details on configuring the database connection, see Configuration Reference. For instructions on running the migration, see Installation and Setup.

---

Migration Overview

The permission system uses a single migration file located at database/migrations/2025_07_02_000000_create_permission_tables.php11-89 that creates five interrelated tables:

Table Name	Purpose	Type
roles	Stores role definitions with guard support	Entity table
permissions	Stores permission definitions with guard support	Entity table
role_has_permissions	Associates permissions with roles	Pivot table
owner_has_permissions	Directly assigns permissions to any entity	Polymorphic pivot table
owner_has_roles	Assigns roles to any entity	Polymorphic pivot table

The migration extends Hypervel\Database\Migrations\Migration and implements both up() and down() methods for proper rollback support.

Sources: database/migrations/2025_07_02_000000_create_permission_tables.php11-89

---

Database Connection Configuration

The migration uses a configurable database connection via the getConnection() method:

This method checks the configuration at permission.storage.database.connection and falls back to the default framework connection if not specified. This allows the permission tables to be stored in a separate database if needed.

Sources: database/migrations/2025_07_02_000000_create_permission_tables.php15-19

---

Table Structures

Roles Table

The roles table stores role definitions:

Key characteristics:

• Primary Key: id (auto-incrementing big integer) database/migrations/2025_07_02_000000_create_permission_tables.php29
• Unique Constraint: name must be unique across all roles database/migrations/2025_07_02_000000_create_permission_tables.php30
• Guard Support: guard_name allows roles to be scoped to different authentication contexts database/migrations/2025_07_02_000000_create_permission_tables.php31
• Composite Index: Index on (name, guard_name) for efficient lookups database/migrations/2025_07_02_000000_create_permission_tables.php34
• Timestamps: Automatic created_at and updated_at tracking database/migrations/2025_07_02_000000_create_permission_tables.php32

Sources: database/migrations/2025_07_02_000000_create_permission_tables.php28-35

Permissions Table

The permissions table stores permission definitions:

Key characteristics:

• Primary Key: id (auto-incrementing big integer) database/migrations/2025_07_02_000000_create_permission_tables.php38
• Unique Constraint: name must be unique across all permissions database/migrations/2025_07_02_000000_create_permission_tables.php39
• Guard Support: guard_name allows permissions to be scoped to different authentication contexts database/migrations/2025_07_02_000000_create_permission_tables.php40
• Composite Index: Index on (name, guard_name) for efficient lookups database/migrations/2025_07_02_000000_create_permission_tables.php42
• Timestamps: Automatic created_at and updated_at tracking database/migrations/2025_07_02_000000_create_permission_tables.php41

Sources: database/migrations/2025_07_02_000000_create_permission_tables.php37-43

Role-Has-Permissions Pivot Table

The role_has_permissions table creates many-to-many relationships between roles and permissions:

Key characteristics:

• Composite Primary Key: (permission_id, role_id) ensures unique permission-role pairs database/migrations/2025_07_02_000000_create_permission_tables.php50
• Foreign Keys: References both permissions.id and roles.id database/migrations/2025_07_02_000000_create_permission_tables.php45-46
• is_forbidden Flag: Boolean field enabling negative permissions (explicit denials) database/migrations/2025_07_02_000000_create_permission_tables.php47
• Dual Indexes: Separate indexes on role_id and permission_id for bidirectional queries database/migrations/2025_07_02_000000_create_permission_tables.php51-52
• Timestamps: Tracks when permission assignments occur database/migrations/2025_07_02_000000_create_permission_tables.php48

Sources: database/migrations/2025_07_02_000000_create_permission_tables.php44-53

Owner-Has-Permissions Polymorphic Pivot Table

The owner_has_permissions table enables direct permission assignment to any entity type:

Key characteristics:

• Polymorphic Relationship: morphs('owner') creates owner_type and owner_id columns database/migrations/2025_07_02_000000_create_permission_tables.php57
• Composite Primary Key: (permission_id, owner_id, owner_type) ensures unique assignments database/migrations/2025_07_02_000000_create_permission_tables.php61
• is_forbidden Flag: Allows explicit permission denial at the owner level database/migrations/2025_07_02_000000_create_permission_tables.php58
• Dual Indexes: Separate indexes on owner_id and permission_id database/migrations/2025_07_02_000000_create_permission_tables.php62-63
• Flexibility: Can assign permissions to Users, Teams, or any other entity type database/migrations/2025_07_02_000000_create_permission_tables.php57

Sources: database/migrations/2025_07_02_000000_create_permission_tables.php55-64

Owner-Has-Roles Polymorphic Pivot Table

The owner_has_roles table assigns roles to any entity type:

Key characteristics:

• Polymorphic Relationship: morphs('owner') creates owner_type and owner_id columns database/migrations/2025_07_02_000000_create_permission_tables.php68
• Composite Primary Key: (role_id, owner_id, owner_type) ensures unique role assignments database/migrations/2025_07_02_000000_create_permission_tables.php71
• No is_forbidden Flag: Roles cannot be explicitly denied, only granted or not granted database/migrations/2025_07_02_000000_create_permission_tables.php66-74
• Dual Indexes: Separate indexes on owner_id and role_id database/migrations/2025_07_02_000000_create_permission_tables.php72-73
• Flexibility: Can assign roles to any entity implementing the HasRole trait database/migrations/2025_07_02_000000_create_permission_tables.php68

Sources: database/migrations/2025_07_02_000000_create_permission_tables.php66-74

---

Complete Database Schema

The following entity-relationship diagram shows how all five tables interconnect:

Sources: database/migrations/2025_07_02_000000_create_permission_tables.php28-74

---

Indexing Strategy

The migration implements a comprehensive indexing strategy to optimize query performance:

Primary Indexes

Table	Index Type	Columns	Purpose
roles	Unique	name	Enforce unique role names
permissions	Unique	name	Enforce unique permission names
role_has_permissions	Composite Primary	(permission_id, role_id)	Unique permission-role pairs
owner_has_permissions	Composite Primary	(permission_id, owner_id, owner_type)	Unique owner-permission pairs
owner_has_roles	Composite Primary	(role_id, owner_id, owner_type)	Unique owner-role pairs

Secondary Indexes

Table	Columns	Purpose
roles	(name, guard_name)	Fast lookups by name and guard
permissions	(name, guard_name)	Fast lookups by name and guard
role_has_permissions	role_id	Efficient role → permissions queries
role_has_permissions	permission_id	Efficient permission → roles queries
owner_has_permissions	owner_id	Fast owner → permissions lookups
owner_has_permissions	permission_id	Fast permission → owners lookups
owner_has_roles	owner_id	Fast owner → roles lookups
owner_has_roles	role_id	Fast role → owners lookups

Sources: database/migrations/2025_07_02_000000_create_permission_tables.php34-73

---

Polymorphic Relationships

Both owner_has_permissions and owner_has_roles tables use polymorphic relationships via Laravel's morphs() method:

How it works:

• owner_type: Stores the fully-qualified class name of the entity (e.g., App\Models\User)
• owner_id: Stores the primary key value of that entity
• Together, they create a compound foreign key to any table

This design allows:

• Users to have permissions and roles
• Teams to have permissions and roles
• Organizations to have permissions and roles
• Any custom entity to have permissions and roles by using the HasPermission and HasRole traits

Sources: database/migrations/2025_07_02_000000_create_permission_tables.php57-68

---

The is_forbidden Mechanism

The is_forbidden boolean flag in role_has_permissions and owner_has_permissions enables negative permissions (explicit denials):

Key behaviors:

1. In role_has_permissions: A role can have a permission explicitly forbidden database/migrations/2025_07_02_000000_create_permission_tables.php47
2. In owner_has_permissions: An owner can have a permission explicitly forbidden, overriding role-based permissions database/migrations/2025_07_02_000000_create_permission_tables.php58
3. Precedence: Direct owner permissions (including forbidden) take precedence over role-based permissions
4. No forbidden roles: The owner_has_roles table does not have an is_forbidden flag—roles are either assigned or not

Use case example:

• A user has the "editor" role, which grants "edit-posts" permission
• The user is explicitly forbidden from "edit-posts" via owner_has_permissions with is_forbidden = true
• Result: The user cannot edit posts (direct denial overrides role permission)

Sources: database/migrations/2025_07_02_000000_create_permission_tables.php47-58

---

Migration Lifecycle

Up Migration

The up() method creates all five tables in sequence:

Process:

1. Retrieves the configured database connection database/migrations/2025_07_02_000000_create_permission_tables.php26
2. Creates entity tables first (roles, permissions) database/migrations/2025_07_02_000000_create_permission_tables.php28-43
3. Creates pivot tables that reference entity tables database/migrations/2025_07_02_000000_create_permission_tables.php44-74

Sources: database/migrations/2025_07_02_000000_create_permission_tables.php24-75

Down Migration

The down() method drops all tables in reverse order:

Process:

1. Retrieves the configured database connection database/migrations/2025_07_02_000000_create_permission_tables.php82
2. Drops pivot tables first (to avoid foreign key constraint issues) database/migrations/2025_07_02_000000_create_permission_tables.php83-85
3. Drops entity tables last database/migrations/2025_07_02_000000_create_permission_tables.php86-87
4. Uses dropIfExists() for safe idempotent rollback database/migrations/2025_07_02_000000_create_permission_tables.php83-87

Sources: database/migrations/2025_07_02_000000_create_permission_tables.php80-88

---

Migration Execution

To execute this migration after installation:

To rollback:

The migration file is automatically published when you run php bin/hyperf.php vendor:publish hypervel/permission, as configured in the package's service providers. For complete installation instructions, see Installation and Setup.

Sources: database/migrations/2025_07_02_000000_create_permission_tables.php1-90