license
This commit is contained in:
Oussama Douhou
211
api/MIGRATION_README.md
Normal file
211
api/MIGRATION_README.md
Normal file
@@ -0,0 +1,211 @@
|
||||
# API Module Database Migrations
|
||||
|
||||
This directory contains scripts and tools for managing database migrations for the Perfex CRM API module.
|
||||
|
||||
## 📁 Files Overview
|
||||
|
||||
- `run_migrations.php` - Basic migration runner script
|
||||
- `migration_runner.php` - Advanced migration runner with rollback support
|
||||
- `migration_web_interface.php` - Web-based migration interface
|
||||
- `migration_template.php` - Template for creating new migrations
|
||||
- `MIGRATION_README.md` - This documentation file
|
||||
|
||||
## 🚀 Quick Start
|
||||
|
||||
### Option 1: Web Interface (Recommended)
|
||||
1. Access `https://yourdomain.com/modules/api/migration_web_interface.php`
|
||||
2. Login as administrator
|
||||
3. Click "Run Upgrade" to apply all pending migrations
|
||||
|
||||
### Option 2: Command Line
|
||||
```bash
|
||||
cd /path/to/perfex/modules/api
|
||||
|
||||
# Run all pending migrations
|
||||
php migration_runner.php
|
||||
|
||||
# Run migrations up to specific version
|
||||
php migration_runner.php --target=205
|
||||
|
||||
# Rollback to specific version
|
||||
php migration_runner.php --rollback --target=200
|
||||
```
|
||||
|
||||
### Option 3: Basic Runner
|
||||
```bash
|
||||
cd /path/to/perfex/modules/api
|
||||
php run_migrations.php
|
||||
```
|
||||
|
||||
## 📋 Available Migrations
|
||||
|
||||
| Version | Description | Status |
|
||||
|---------|-------------|--------|
|
||||
| 101 | Initial API setup | ✅ Applied |
|
||||
| 102 | Basic API tables | ✅ Applied |
|
||||
| 103 | User authentication | ✅ Applied |
|
||||
| 200 | Rate limiting system | ✅ Applied |
|
||||
| 201 | API logging improvements | ✅ Applied |
|
||||
| 202 | Custom fields support | ✅ Applied |
|
||||
| 203 | Webhook system | ✅ Applied |
|
||||
| 204 | API key management | ✅ Applied |
|
||||
| 205 | Performance optimizations | ✅ Applied |
|
||||
| 206 | Security enhancements | ✅ Applied |
|
||||
| 207 | Error handling improvements | ✅ Applied |
|
||||
| 208 | Documentation updates | ✅ Applied |
|
||||
| 209 | Testing framework | ✅ Applied |
|
||||
| 210 | API metrics dashboard | ✅ Applied |
|
||||
| 211 | Rate limiting columns | ✅ Applied |
|
||||
|
||||
## 🔧 Creating New Migrations
|
||||
|
||||
1. Copy `migration_template.php` to a new file
|
||||
2. Name it `{version}_version_{version}.php` (e.g., `212_version_212.php`)
|
||||
3. Replace `{VERSION}` with the actual version number
|
||||
4. Implement the `up()` and `down()` methods
|
||||
5. Test the migration on a development environment
|
||||
6. Run the migration using one of the scripts above
|
||||
|
||||
### Migration Template Structure
|
||||
|
||||
```php
|
||||
<?php
|
||||
class Migration_Version_{VERSION} extends App_module_migration
|
||||
{
|
||||
protected $db;
|
||||
|
||||
public function __construct()
|
||||
{
|
||||
parent::__construct();
|
||||
$CI = &get_instance();
|
||||
$CI->load->database();
|
||||
$this->db = $CI->db;
|
||||
}
|
||||
|
||||
public function up()
|
||||
{
|
||||
// Your upgrade logic here
|
||||
// - Create tables
|
||||
// - Add columns
|
||||
// - Insert data
|
||||
// - Create indexes
|
||||
}
|
||||
|
||||
public function down()
|
||||
{
|
||||
// Reverse the up() changes
|
||||
// - Drop tables
|
||||
// - Remove columns
|
||||
// - Delete data
|
||||
// - Drop indexes
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 🛠️ Migration Best Practices
|
||||
|
||||
### Database Operations
|
||||
- Always check if fields/tables exist before creating/altering
|
||||
- Use `db_prefix()` for all table names
|
||||
- Include both `up()` and `down()` methods
|
||||
- Test migrations on development data first
|
||||
|
||||
### Version Numbering
|
||||
- Use incremental version numbers (101, 102, 103, etc.)
|
||||
- Major version jumps (200, 201) for significant changes
|
||||
- Keep version numbers unique across all migrations
|
||||
|
||||
### Safety Measures
|
||||
- Backup database before running migrations
|
||||
- Test rollback functionality
|
||||
- Keep migrations atomic (one change per migration)
|
||||
- Document what each migration does
|
||||
|
||||
## 🔍 Troubleshooting
|
||||
|
||||
### Migration Fails
|
||||
1. Check PHP error logs
|
||||
2. Verify database permissions
|
||||
3. Ensure all dependencies are installed
|
||||
4. Check if tables already exist
|
||||
|
||||
### Rollback Issues
|
||||
1. Some operations cannot be reversed (data loss)
|
||||
2. Foreign key constraints may prevent drops
|
||||
3. Manual intervention may be required
|
||||
|
||||
### Permission Errors
|
||||
1. Ensure PHP has database write permissions
|
||||
2. Check file system permissions for migration files
|
||||
3. Verify admin access for web interface
|
||||
|
||||
## 📊 Migration Tracking
|
||||
|
||||
Migrations are tracked in the `migrations` table:
|
||||
|
||||
```sql
|
||||
SELECT * FROM tblmigrations WHERE module = 'api' ORDER BY version DESC;
|
||||
```
|
||||
|
||||
Each successful migration updates this table with:
|
||||
- `module`: 'api'
|
||||
- `version`: migration version number
|
||||
|
||||
## 🔄 Rollback Procedures
|
||||
|
||||
### Emergency Rollback
|
||||
```bash
|
||||
# Rollback to previous version
|
||||
php migration_runner.php --rollback
|
||||
|
||||
# Rollback to specific version
|
||||
php migration_runner.php --rollback --target=200
|
||||
```
|
||||
|
||||
### Manual Rollback
|
||||
If automatic rollback fails:
|
||||
1. Identify the migration that caused issues
|
||||
2. Manually reverse the database changes
|
||||
3. Update the migrations table to reflect the rollback
|
||||
4. Test API functionality
|
||||
|
||||
## 📈 Performance Considerations
|
||||
|
||||
### Large Datasets
|
||||
- Use `LIMIT` clauses for large table operations
|
||||
- Consider running migrations during off-peak hours
|
||||
- Monitor database performance during migration
|
||||
|
||||
### Indexes
|
||||
- Add indexes for frequently queried columns
|
||||
- Remove unused indexes to improve performance
|
||||
- Consider composite indexes for complex queries
|
||||
|
||||
## 🔐 Security Notes
|
||||
|
||||
- Never commit database credentials to version control
|
||||
- Use environment variables for sensitive configuration
|
||||
- Test migrations on staging environments first
|
||||
- Backup production databases before deployment
|
||||
|
||||
## 📞 Support
|
||||
|
||||
For migration issues:
|
||||
1. Check this documentation first
|
||||
2. Review migration error logs
|
||||
3. Test on development environment
|
||||
4. Contact development team with specific error details
|
||||
|
||||
## 📝 Changelog
|
||||
|
||||
### Version 2.1.0
|
||||
- Added advanced migration runner with rollback support
|
||||
- Created web-based migration interface
|
||||
- Improved error handling and logging
|
||||
- Added migration templates and documentation
|
||||
|
||||
### Version 2.0.8
|
||||
- Initial migration system implementation
|
||||
- Basic upgrade functionality
|
||||
- Rate limiting and security enhancements</content>
|
||||
</xai:function_call: 1
|
||||
Reference in New Issue
Block a user