Laravel默认推崇的数据库是MySQL，但在实际项目中，PostgreSQL凭借对JSONB、数组类型、全文检索和窗口函数的深度支持，越来越受到Laravel开发者的青睐。Eloquent作为Laravel的ORM，本身对PostgreSQL提供了完善的支持，只需要改几行配置，就可以无缝切换。这篇文章从配置、建模、JSONB操作到常见问题排查，完整讲解如何在Laravel中使用Eloquent操作PostgreSQL。
一、环境准备与数据库连接配置
使用PostgreSQL前，需要确保PHP安装了pdo_pgsql扩展。可以通过php -m命令查看已加载的扩展列表，如果没有该扩展，Linux下需要安装php-pgsql包，Windows下则要在php.ini中取消extension=pdo_pgsql前面的注释并重启服务。缺少这个扩展时，Laravel会直接抛出could not find driver异常，这是新手最容易踩的第一个坑。
接下来修改项目根目录下的.env文件，把默认连接切换为pgsql：
DB_CONNECTION=pgsql DB_HOST=127.0.0.1 DB_PORT=5432 DB_DATABASE=laravel_demo DB_USERNAME=postgres DB_PASSWORD=your_password
配置完成后，可以先在config/database.php中确认pgsql连接段的配置是否正确，尤其是charset和search_path。如果应用使用非public的schema，需要在dsn配置中指定search_path，例如：
'pgsql' => [
'driver' => 'pgsql',
'host' => env('DB_HOST', '127.0.0.1'),
'port' => env('DB_PORT', '5432'),
'database' => env('DB_DATABASE', 'forge'),
'username' => env('DB_USERNAME', 'forge'),
'password' => env('DB_PASSWORD', ''),
'charset' => 'utf8',
'prefix' => '',
'search_path' => 'public',
'sslmode' => 'prefer',
],
验证连接是否成功，最简单的办法是运行php artisan migrate，如果默认的迁移文件都能顺利执行，说明连接没有问题。也可以用php artisan tinker进入交互环境，执行DB::select('select version()')查看PostgreSQL版本信息。
二、Eloquent模型与PostgreSQL特性结合
连接配好之后，Eloquent的使用方式与MySQL下基本一致。假设有一张商品表，其中使用了PostgreSQL特有的JSONB类型存储扩展属性，先创建迁移文件：
Schema::create('products', function (Blueprint $table) {
$table->id();
$table->string('name');
$table->decimal('price', 10, 2);
$table->jsonb('attributes')->nullable();
$table->timestamps();
});
PostgreSQL的JSONB是二进制存储格式，支持索引和高效查询，这一点比MySQL的JSON类型性能更好。在Eloquent中操作JSONB字段，需要配合$casts属性把字段转换成数组：
class Product extends Model
{
protected $fillable = ['name', 'price', 'attributes'];
protected $casts = [
'attributes' => 'array',
];
}
// 写入JSONB数据
$product = Product::create([
'name' => '机械键盘',
'price' => 499.00,
'attributes' => ['color' => '黑色', 'layout' => '87键'],
]);
// 读取时自动转为数组
echo $product->attributes['color'];
查询JSONB内部字段时，Eloquent提供了->操作符支持，例如筛选颜色为黑色的商品：
$products = Product::where('attributes->color', '黑色')->get();
这行代码最终会被翻译成PostgreSQL的attributes->>'color'查询语法。如果需要对JSONB字段做更复杂的条件判断，比如查询数组类型字段是否包含某个值，可以借助whereJsonContains方法，它在PostgreSQL上会被编译成@>操作符，配合GIN索引能获得非常好的查询性能。
除了JSONB，PostgreSQL的数组类型、全文检索、窗口函数等特性也可以通过Eloquent的本地查询作用域或原生表达式来使用。例如用DB::raw()调用窗口函数统计每个分类的销售额排名，这类操作在MySQL旧版本上是无法直接实现的。
三、事务、批量插入与性能优化建议
PostgreSQL对事务和并发的处理能力很强，Laravel中通过DB::transaction使用事务的写法与MySQL完全相同：
use Illuminate\Support\Facades\DB;
DB::transaction(function () {
$order = Order::create(['user_id' => 1, 'total' => 998]);
OrderItem::create(['order_id' => $order->id, 'product_id' => 5]);
});
批量插入方面要注意一个差异：PostgreSQL对单条SQL语句的参数数量有上限（通常为32767），当使用insert批量插入超大数组时，Laravel生成的长SQL可能触发too many parameters错误。解决办法是使用insertOrIgnore配合分块，或者使用Laravel 8以上提供的upsert方法并控制每批的数据量，比如每批不超过500条：
collect($records)->chunk(500)->each(function ($chunk) {
Product::upsert(
$chunk->toArray(),
['name'],
['price', 'attributes']
);
});
在性能优化层面，PostgreSQL有几个值得利用的点。第一是部分索引，比如只对上架商品建索引：CREATE INDEX idx_on_sale ON products (price) WHERE status = 'on_sale'，比全表索引更省空间。第二是EXPLAIN ANALYZE，在开发阶段对慢查询逐条分析执行计划，比单纯猜测索引缺失有效得多。第三是连接池，PostgreSQL每个连接是独立进程，代价高于MySQL的线程模型，高并发场景建议在应用层使用PgBouncer做连接池，避免连接数暴涨。
四、常见报错与排查思路
切换到PostgreSQL后，一些在MySQL上习以为常的写法会报错。比较典型的有：字段名使用大小写混合时必须加双引号引用，建议全表统一使用蛇形命名；字符串拼接函数不同，MySQL的CONCAT在PostgreSQL中同样可用，但GROUP_CONCAT需要替换为string_agg；自增主键如果迁移时用了$table->increments()的旧写法，PostgreSQL会创建serial序列，一般不报错，但手动插入了显式id后序列不会自动前进，会触发duplicate key错误，此时需要用setval重置序列：
SELECT setval('products_id_seq', (SELECT MAX(id) FROM products));
另外，字符集问题也值得注意。PostgreSQL从版本9以后统一使用UTF-8编码，不再像MySQL那样区分utf8和utf8mb4，所以emoji和中文存储在PostgreSQL中天然没有乱码风险，这反而是它的一大优势。遇到连接被拒绝的错误时，优先检查pg_hba.conf和postgresql.conf中的监听地址与认证配置，确保Laravel服务器的IP被允许访问5432端口。
总体来说，Laravel Eloquent对PostgreSQL的支持已经非常成熟，绝大多数业务代码在两种数据库之间可以无差别迁移，而PostgreSQL的JSONB、数组、窗口函数等特性又能反过来增强Eloquent的表达能力。如果你的项目涉及复杂查询、半结构化数据存储或者未来有分库分表、读写分离的规划，PostgreSQL搭配Laravel是一个值得认真考虑的组合。
Laravel EloquentPostgreSQL数据库配置修改时间：2026-09-12 06:40:33