API for multi_insert with returning

[eriklovmo]

For Dataset#insert with #returning, the return value is an array of hashes regardless of how many columns are specified to #returning:

[1] pry(main)> DB[:tenants].returning(:id, :name).insert({name: "foo"})
D, [2026-01-05T11:46:00.801557 #94819] DEBUG -- : (0.005904s) INSERT INTO "tenants" ("name") VALUES ('foo') RETURNING "id", "name"
=> [{id: 13, name: "foo"}]
[2] pry(main)> DB[:tenants].returning(:id).insert({name: "foo"})
D, [2026-01-05T11:46:08.618171 #94819] DEBUG -- : (0.001710s) INSERT INTO "tenants" ("name") VALUES ('foo') RETURNING "id"
=> [{id: 14}]

But for Dataset#multi_insert, the return value shape changes depending on the number of columns specified to #returning:

[3] pry(main)> DB[:tenants].returning(:id, :name).multi_insert([{name: "foo"}])
D, [2026-01-05T11:45:46.708463 #94819] DEBUG -- : (0.001605s) INSERT INTO "tenants" ("name") VALUES ('foo') RETURNING "id", "name"
=> [{id: 12, name: "foo"}]
[4] pry(main)> DB[:tenants].returning(:id).multi_insert([{name: "foo"}])
D, [2026-01-05T11:45:41.952456 #94819] DEBUG -- : (0.001500s) INSERT INTO "tenants" ("name") VALUES ('foo') RETURNING "id"
=> [11]

This is a little surprising.

I see this documented in

sequel/lib/sequel/adapters/shared/postgres.rb

Line 2570 in 25ee6b9

# is only set to return a single columns, return an array of just that column.

but only on the protected #_import. Could it be documented closer to the "public" API? Maybe on #multi_insert, or do you have a better idea?

FWIW, I'm on Sequel version 5.99.0.

[jeremyevans]

Thanks for pointing this out. The behavior is expected, but you are correct that it should be better documented. I'll add documentation to #import, as #multi_insert already documents it is a front-end to #import.

In terms of the reasoning for the behavior, unless you specify return: :primary_key, the general return value of #import (and therefore #multi_insert) is undefined and should not be used. On PostgreSQL, #import does have a defined return value if the dataset uses RETURNING.

I realize this behavior makes #multi_insert's return value dependent on the hashes passed in, which is probably suboptimal. I'm open to supporting a PostgreSQL-specific option to #import/#multi_insert to change it to force an array of hashes to be returned, even if only a single RETURNING column is used.

[eriklovmo]

Thanks for the fast and thorough answer!

[jeremyevans]

Added documentation for this in 4293be3