Database Migration Generators

Purpose and Scope

This document provides an overview of the database migration generator subsystem within the Hypervel/Devtool package. These generators create migration files for framework-level infrastructure tables required by various system features including caching, sessions, queues, and notifications. Unlike application-level model migrations, these generators produce standardized table schemas for core framework functionality.

For information about generating application models and their migrations, see Model System Generators. For details about the generator command architecture that these commands extend, see Generator Command Architecture.

Sources: src/ConfigProvider.php1-82

Overview

The database migration generator subsystem provides seven specialized commands that generate timestamped migration files for framework infrastructure tables. Each command:

1. Retrieves the table name from application configuration (or uses a sensible default)
2. Reads a corresponding stub template containing the table schema
3. Replaces placeholders with the configured table name
4. Generates a timestamped migration file in database/migrations/

These generators are distinct from make:migration (for custom migrations) and create predefined schemas optimized for specific framework features.

Sources: src/ConfigProvider.php55-68 src/Generator/CacheTableCommand.php1-106

Available Migration Generators

Command	Table Name (Default)	Purpose	Configuration Key
make:cache-table	cache	Database cache storage	cache.stores.database.table
make:cache-locks-table	cache_locks	Atomic cache locks	cache.stores.database.locks.table
make:session-table	sessions	Session storage	N/A (hardcoded)
make:notifications-table	notifications	Database notifications	N/A (hardcoded)
make:queue-table	job_queue	Queued jobs	queue.default.table
make:queue-batches-table	job_batches	Job batching metadata	queue.batching.table
make:queue-failed-table	failed_jobs	Failed job records	queue.failed.table

Sources: src/ConfigProvider.php55-68

Command Registration

All database migration generators are registered in the ConfigProvider class alongside other devtool commands. The registration includes a fail-safe check for the GeneratorCommand base class:

This ensures the package gracefully degrades if Hyperf's devtool dependency is not installed.

Sources: src/ConfigProvider.php43-80

Architecture and Flow

Generation Pipeline

The following diagram illustrates the typical execution flow for any database migration generator:

Sources: src/Generator/CacheTableCommand.php29-59

Class Structure and Relationships

Sources: src/ConfigProvider.php10-36 src/Generator/CacheTableCommand.php15-106

Common Implementation Patterns

All database migration generators follow a consistent implementation pattern. Using CacheTableCommand as the reference implementation:

Command Constructor

Each command registers itself with a specific name:

src/Generator/CacheTableCommand.php17-20

The command name follows the convention make:{feature}-table.

Execute Method

The execute() method orchestrates the generation process:

1. Retrieve table name via migrationTableName() src/Generator/CacheTableCommand.php34
2. Generate filename with Carbon timestamp src/Generator/CacheTableCommand.php35
3. Check for existing file with alreadyExists() src/Generator/CacheTableCommand.php41-44
4. Create directory structure with makeDirectory() src/Generator/CacheTableCommand.php49
5. Process stub template with buildMigration() src/Generator/CacheTableCommand.php51-52
6. Write output file src/Generator/CacheTableCommand.php52
7. Open in IDE (optional) src/Generator/CacheTableCommand.php56

Configuration Retrieval

Commands that support configurable table names use the ConfigInterface to retrieve values:

src/Generator/CacheTableCommand.php100-105

The get() method's second parameter provides the default fallback if the configuration key is not set.

Stub Processing

The buildMigration() method performs simple string replacement:

src/Generator/CacheTableCommand.php61-64

The %TABLE% placeholder is replaced with the actual table name from configuration.

Sources: src/Generator/CacheTableCommand.php29-106

Stub Templates

Each generator has a corresponding stub file that defines the migration schema. Stub templates use:

• %TABLE% placeholder for dynamic table names
• Hyperf's Blueprint class for schema definition
• Hypervel's Migration base class and Schema facade
• Standard Laravel-style migration structure with up() and down() methods

Cache Table Stub Structure

The cache table stub src/Generator/stubs/cache-table.stub1-29 defines a simple key-value store with expiration:

Column	Type	Constraints	Purpose
key	string	Primary Key	Cache key identifier
value	mediumText	-	Serialized cached value
expiration	integer	-	Unix timestamp for TTL

Cache Locks Table Stub Structure

The cache locks stub src/Generator/stubs/cache-locks-table.stub1-29 defines atomic lock storage:

Column	Type	Constraints	Purpose
key	string	Primary Key	Lock key identifier
owner	string	-	Lock owner identifier
expiration	integer	-	Unix timestamp for lock TTL

Sessions Table Stub Structure

The sessions stub src/Generator/stubs/sessions-table.stub1-33 defines comprehensive session storage:

Column	Type	Constraints	Purpose
id	string	Primary Key	Session identifier
user_id	foreignId	Nullable, Indexed	Associated user
ip_address	string(45)	Nullable	Client IP (IPv4/IPv6)
user_agent	text	Nullable	Browser user agent
payload	longText	-	Serialized session data
last_activity	integer	Indexed	Unix timestamp

Notifications Table Stub Structure

The notifications stub src/Generator/stubs/notifications-table.stub1-33 defines database-backed notifications:

Column	Type	Constraints	Purpose
id	uuid	Primary Key	Notification UUID
type	string	-	Notification class name
notifiable_type	string	Morph Index	Polymorphic type
notifiable_id	bigInteger	Morph Index	Polymorphic ID
data	text	-	Serialized notification data
read_at	timestamp	Nullable	Read timestamp
created_at	timestamp	-	Creation timestamp
updated_at	timestamp	-	Update timestamp

The morphs() method creates both notifiable_type and notifiable_id columns with a composite index.

Jobs Queue Table Stub Structure

The jobs table stub src/Generator/stubs/jobs-table.stub1-35 defines the queue table schema:

Column	Type	Constraints	Purpose
id	bigIncrements	Primary Key	Auto-incrementing job ID
queue	string	Indexed	Queue name
payload	longText	-	Serialized job data
attempts	unsignedTinyInteger	-	Retry attempt count
reserved_at	unsignedInteger	Nullable	Job lock timestamp
available_at	unsignedInteger	-	Job availability time
created_at	unsignedInteger	-	Creation timestamp

Sources: src/Generator/stubs/cache-table.stub1-29 src/Generator/stubs/cache-locks-table.stub1-29 src/Generator/stubs/sessions-table.stub1-33 src/Generator/stubs/notifications-table.stub1-33 src/Generator/stubs/jobs-table.stub1-35

Command Options

Database migration generators support a minimal set of options compared to other generators:

Option	Shorthand	Type	Description
--force	-f	Boolean	Overwrite existing migration files
--path	-p	Optional	Custom output path (default: database/migrations/)

The path option is redefined in these commands src/Generator/CacheTableCommand.php83-89 to allow custom migration locations while filtering out the inherited default path option from GeneratorCommand.

Sources: src/Generator/CacheTableCommand.php81-90

Generated Migration Structure

All generated migrations follow a consistent structure:

database/migrations/
└── YYYY_MM_DD_000000_create_{table}_table.php

Filename Format

The filename consists of:

1. Timestamp prefix: Carbon::now()->format('Y_m_d_000000') src/Generator/CacheTableCommand.php35
2. Descriptive name: _create_{$tableName}_table
3. Extension: .php

File Contents

Each generated migration file contains:

• Strict type declaration
• Imports for Blueprint, Migration, and Schema
• Anonymous class extending Migration
• up() method with table creation logic
• down() method with table drop logic

The migration uses Schema::create() for the up() method and Schema::dropIfExists() for the down() method.

Sources: src/Generator/CacheTableCommand.php35 src/Generator/stubs/cache-table.stub1-29

Configuration Integration

Cache-Related Tables

Cache migration generators read table names from the cache configuration:

cache.stores.database.table → CacheTableCommand
cache.stores.database.locks.table → CacheLocksTableCommand

Source: src/Generator/CacheTableCommand.php100-105

Queue-Related Tables

Queue migration generators read table names from the queue configuration:

queue.default.table → QueueTableCommand
queue.batching.table → BatchesTableCommand
queue.failed.table → QueueFailedTableCommand

Hardcoded Table Names

Some generators use hardcoded table names as they follow framework conventions:

• SessionTableCommand: Always uses sessions
• NotificationTableCommand: Always uses notifications

Sources: src/Generator/CacheTableCommand.php100-105 src/Generator/stubs/sessions-table.stub15 src/Generator/stubs/notifications-table.stub15

Usage Examples

Generating Cache Tables

Generating Session Table

Generating Queue Infrastructure

Generating Notification Table

Sources: src/Generator/CacheTableCommand.php24

Relationship to Other Systems

The database migration generators interact with several other parts of the framework:

Sources: src/Generator/CacheTableCommand.php100-105 src/ConfigProvider.php55-68

Extension and Customization

Custom Stub Files

Developers can override the default stub templates by configuring custom stub paths. The getStub() method checks for a configured stub path before falling back to the default:

src/Generator/CacheTableCommand.php66-69

This allows teams to customize table schemas while maintaining the same command interface.

Custom Table Names

To use custom table names, modify the appropriate configuration file:

The generators will automatically use these configured names when creating migrations.

Sources: src/Generator/CacheTableCommand.php66-69 src/Generator/CacheTableCommand.php100-105

Summary

The database migration generator subsystem provides specialized commands for creating framework infrastructure tables. These generators:

1. Follow consistent patterns across all seven commands
2. Read configuration for table names with sensible defaults
3. Use stub templates with placeholder replacement
4. Generate timestamped migrations in standard Laravel format
5. Support customization via configuration and custom stubs
6. Integrate seamlessly with framework services that require database storage

For implementation details of specific migration generators, see:

• Cache System Table Migrations
• Session Table Migration
• Queue System Table Migrations
• Notification Table Migration

Sources: src/ConfigProvider.php1-82 src/Generator/CacheTableCommand.php1-106