Laravel 迁移中正确创建 MySQL 自定义函数的完整指南

在 laravel 迁移中，使用 `db::raw()` 无法执行 sql 函数定义；必须改用 `db::statement()` 才能实际创建或删除 mysql 存储函数。本文详解实现步骤、常见错误及最佳实践。

在 Laravel 应用中，当需要复用地理距离计算等复杂逻辑时，将计算逻辑下沉至 MySQL 层（如定义 calculate_distance 函数）是常见且高效的方案。但许多开发者在迁移中误用 DB::raw()，导致函数看似“迁移成功”，实则未在数据库中创建——正如你在 phpMyAdmin 中观察到的那样：控制台显示 Migrated:，但函数列表为空。

根本原因在于：DB::raw() 仅用于构造原始 SQL 表达式（例如 WHERE 条件中的 RAW 值），它不会触发 SQL 执行；而创建/删除函数属于 DDL（数据定义语言）操作，必须通过可执行语句接口完成。

✅ 正确做法是使用 DB::statement() —— 它专为执行任意原生 SQL 语句（包括 CREATE FUNCTION、DROP PROCEDURE、SET @var := ... 等）而设计，支持多语句（需确保 PDO 配置允许，见下文注意事项）。

以下是修复后的迁移文件示例（兼容 Laravel 8+，已优化可读性与健壮性）：

CodeWP

针对 WordPress 训练的AI代码生成器

下载

<?php

use Illuminate\Database\Migrations\Migration;
use Illuminate\Support\Facades\DB;

return new class extends Migration
{
    public function up()
    {
        // &#20808;&#23433;&#20840;&#21024;&#38500;&#65288;&#36991;&#20813;&#37325;&#22797;&#21019;&#24314;&#22833;&#36133;&#65289;
        DB::statement('DROP FUNCTION IF EXISTS calculate_distance');

        // &#21019;&#24314;&#20989;&#25968;&#65306;&#20351;&#29992;&#26631;&#20934; Haversine &#36817;&#20284;&#20844;&#24335;&#65292;&#21333;&#20301;&#20026;&#20844;&#37324;
        DB::statement(<<<SQL
CREATE FUNCTION calculate_distance(
    lat1 DECIMAL(10,8),
    lon1 DECIMAL(11,8),
    lat2 DECIMAL(10,8),
    lon2 DECIMAL(11,8)
) 
RETURNS DECIMAL(10,2)
READS SQL DATA
DETERMINISTIC
BEGIN
    RETURN ROUND(
        111.111 * DEGREES(
            ACOS(
                COS(RADIANS(lat1)) *
                COS(RADIANS(lat2)) *
                COS(RADIANS(lon1 - lon2)) +
                SIN(RADIANS(lat1)) *
                SIN(RADIANS(lat2))
            )
        ),
        2
    );
END
SQL
        );
    }

    public function down()
    {
        DB::statement('DROP FUNCTION IF EXISTS calculate_distance');
    }
};

? 关键注意事项：

• ✅ 必须分两次调用 DB::statement()：MySQL 不允许在单条 DB::statement() 中执行多个以分号分隔的语句（除非启用 PDO::MYSQL_ATTR_MULTI_STATEMENTS，但 Laravel 默认禁用，且存在安全风险）。因此 DROP 和 CREATE 需拆分为独立语句。
• ✅ 参数类型建议使用 DECIMAL 而非 FLOAT：地理坐标精度敏感，DECIMAL(10,8) 可精确表示纬度（±90°）和经度（±180°），避免浮点误差累积。
• ✅ 显式指定 READS SQL DATA 和 DETERMINISTIC：这是 MySQL 5.7+ 强制要求（尤其在 sql_mode=STRICT_TRANS_TABLES 下），否则创建失败。
• ⚠️ 函数名大小写敏感性：MySQL 默认函数名不区分大小写，但建议统一小写以保证跨平台一致性。
• ? 验证是否生效：迁移后可在 phpMyAdmin 的「Routines」→「Functions」标签页查看，或运行 SHOW FUNCTION STATUS LIKE 'calculate_distance';。

? 进阶提示：若需在 Eloquent 查询中调用该函数，可直接嵌入 selectRaw 或 whereRaw：

$stores = Store::select('id', 'name')
    ->selectRaw('calculate_distance(?, ?, latitude, longitude) as distance', [
        $userLat, $userLon
    ])
    ->having('distance', '<', 10)
    ->orderBy('distance')
    ->get();

至此，你的自定义 SQL 函数即可被 Laravel 稳定调用，同时保持数据库层逻辑复用与查询性能优势。