Skip to content
17 changes: 11 additions & 6 deletions docs/runtime/sql.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -400,19 +400,24 @@ await sql`SELECT * FROM users WHERE id IN ${sql(users, "id")}`;

### `sql.array` helper

The `sql.array` helper creates PostgreSQL array literals from JavaScript arrays:
The `sql.array` helper binds a JavaScript array as a typed PostgreSQL array parameter:

```ts
// Create array literals for PostgreSQL
// The element type is inferred from the values
await sql`INSERT INTO tags (items) VALUES (${sql.array(["red", "blue", "green"])})`;
// Generates: INSERT INTO tags (items) VALUES (ARRAY['red', 'blue', 'green'])
// Binds: $1::TEXT[] with '{"red","blue","green"}'

// Works with numeric arrays too
await sql`SELECT * FROM products WHERE ids = ANY(${sql.array([1, 2, 3])})`;
// Generates: SELECT * FROM products WHERE ids = ANY(ARRAY[1, 2, 3])
await sql`SELECT * FROM products WHERE id = ANY(${sql.array([1, 2, 3])})`;
// Binds: $1::INTEGER[] with '{1,2,3}'

// Pass the element type explicitly when inference is not enough
await sql`INSERT INTO events (ids) VALUES (${sql.array(["a0eebc99-..."], "UUID")})`;
```

<Note>`sql.array` is PostgreSQL-only. Multi-dimensional arrays and NULL elements may not be supported yet.</Note>
Without an explicit type, strings bind as `TEXT`, integers as `INTEGER` or `BIGINT`, other numbers as `DOUBLE PRECISION`, bigints as `BIGINT` (or `NUMERIC` when one is outside the 64-bit range), booleans as `BOOLEAN`, dates as `TIMESTAMPTZ`, buffers as `BYTEA`. A mix of numbers and bigints binds as `BIGINT` or `NUMERIC`. Objects, any other mix of kinds, empty arrays and arrays of only `null` or `undefined` bind as `JSON`. `null` and `undefined` elements bind as `NULL`.
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved

<Note>`sql.array` is PostgreSQL-only. Multi-dimensional arrays may not be supported yet.</Note>

---

Expand Down
12 changes: 11 additions & 1 deletion packages/bun-types/sql.d.ts
Original file line number Diff line number Diff line change
Expand Up @@ -760,14 +760,24 @@ declare module "bun" {
/**
* Creates a SQL array parameter
* @param values Array values to bind
* @param typeNameOrTypeID Element type name or type ID; defaults to JSON when omitted
* @param typeNameOrTypeID Element type name or type ID. When omitted, the
* type is inferred from the values: strings bind as `TEXT`, integers as
* `INTEGER` or `BIGINT`, other numbers as `DOUBLE PRECISION`, bigints as
* `BIGINT` (or `NUMERIC` when one is outside the 64-bit range), booleans
* as `BOOLEAN`, dates as `TIMESTAMPTZ`, buffers as `BYTEA`. A mix of
* numbers and bigints binds as `BIGINT` or `NUMERIC`. Objects, any other
* mix of kinds, empty arrays and arrays of only `null` or `undefined` bind
* as `JSON`.
* @returns The array parameter, ready to interpolate into a query
*
* @example
* ```ts
* const array = sql.array([1, 2, 3], "INT");
* await sql`CREATE TABLE users_posts (user_id INT, posts_id INT[])`;
* await sql`INSERT INTO users_posts (user_id, posts_id) VALUES (${user.id}, ${array})`;
*
* // the element type is inferred from the values
* await sql`SELECT * FROM users WHERE id = ANY(${sql.array([1, 2, 3])})`;
* ```
*/
array(values: any[], typeNameOrTypeID?: number | ArrayType): SQLArrayParameter;
Expand Down
107 changes: 102 additions & 5 deletions src/js/internal/sql/postgres.ts
Original file line number Diff line number Diff line change
Expand Up @@ -146,6 +146,8 @@ function arrayValueSerializer(type: ArrayType, is_numeric: boolean, is_json: boo
// we do minimal to none type validation, we just try to format nicely and let the server handle if is valid SQL
// postgres will try to convert string -> array type
// postgres will emit a nice error saying what value dont have the expected format outputing the value in the error
// An unquoted null is the SQL NULL element. The default branch would quote it.
if (value === null) return "null";
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
if ($isArray(value) || isTypedArray(value)) {
if (!value.length) return "{}";
const delimiter = type === "BOX" ? ";" : ",";
Expand Down Expand Up @@ -194,7 +196,8 @@ function arrayValueSerializer(type: ArrayType, is_numeric: boolean, is_json: boo
const hexValue = value.toString("hex");
// bytea array
if (type === "BYTEA") {
return `"\\x${arrayEscape(hexValue)}"`;
// The array parser unescapes the backslash, so byteain sees \xHEX.
return `"${arrayEscape("\\x" + hexValue)}"`;
}
if (is_json) {
return `"${arrayEscape(JSON.stringify(hexValue))}"`;
Expand All @@ -205,7 +208,7 @@ function arrayValueSerializer(type: ArrayType, is_numeric: boolean, is_json: boo
return `"${arrayEscape(JSON.stringify(value))}"`;
}
}
function getArrayType(typeNameOrID: number | ArrayType | undefined = undefined): ArrayType {
function getArrayType(values: any[], typeNameOrID: number | ArrayType | undefined): ArrayType {
const typeOfType = typeof typeNameOrID;
if (typeOfType === "number") {
return getPostgresArrayType(typeNameOrID as number) ?? "JSON";
Expand All @@ -226,8 +229,102 @@ function getArrayType(typeNameOrID: number | ArrayType | undefined = undefined):
}
return type;
}
// default to JSON so we accept most of the types
return "JSON";
return inferArrayType(values);
}

const enum ElementKind {
none,
string,
number,
bigint,
boolean,
date,
buffer,
json,
}

function isNumericKind(kind: ElementKind) {
return kind === ElementKind.number || kind === ElementKind.bigint;
}

const INT64_MIN = -(2n ** 63n);
const INT64_MAX = 2n ** 63n - 1n;

// Numbers follow the scalar inference in tag_jsc.rs (int4, int8, float8).
function inferArrayType(values: any[]): ArrayType {
let kind = ElementKind.none;
let fitsInt32 = true;
let fitsInt64 = true;
let allIntegers = true;

function visit(value: any) {
if (value === null || value === undefined) return;
if ($isArray(value)) {
for (let i = 0; i < value.length; i++) visit(value[i]);
return;
}
let current: ElementKind;
switch (typeof value) {
case "string":
current = ElementKind.string;
break;
case "number":
current = ElementKind.number;
if (!Number.isSafeInteger(value)) {
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
allIntegers = false;
} else if (value < -2147483648 || value > 2147483647) {
fitsInt32 = false;
}
break;
case "bigint":
current = ElementKind.bigint;
if (value < INT64_MIN || value > INT64_MAX) fitsInt64 = false;
break;
Comment thread
robobun marked this conversation as resolved.
Resolved
case "boolean":
current = ElementKind.boolean;
break;
default:
if (value instanceof Date) {
current = ElementKind.date;
} else if (Buffer.isBuffer(value)) {
current = ElementKind.buffer;
} else {
// Objects and typed array views keep the JSON default.
current = ElementKind.json;
}
}
if (kind === ElementKind.none) {
kind = current;
} else if (kind !== current) {
// A number mixed with a bigint is still numeric. Any other mix is JSON.
kind = isNumericKind(kind) && isNumericKind(current) ? ElementKind.bigint : ElementKind.json;
}
}

if ($isArray(values)) {
visit(values);
} else if (ArrayBuffer.isView(values) && !Buffer.isBuffer(values)) {
// A top-level typed array serializes as a flat list of its numbers.
for (let i = 0; i < values.length; i++) visit(values[i]);
}

switch (kind) {
case ElementKind.string:
return "TEXT";
case ElementKind.number:
if (!allIntegers) return "DOUBLE PRECISION";
return fitsInt32 ? "INTEGER" : "BIGINT";
case ElementKind.bigint:
return allIntegers && fitsInt64 ? "BIGINT" : "NUMERIC";
case ElementKind.boolean:
return "BOOLEAN";
case ElementKind.date:
return "TIMESTAMPTZ";
case ElementKind.buffer:
return "BYTEA";
Comment thread
robobun marked this conversation as resolved.
Resolved
default:
return "JSON";
}
}
function serializeArray(values: any[], type: ArrayType) {
if (!$isArray(values) && !isTypedArray(values)) return values;
Expand Down Expand Up @@ -443,7 +540,7 @@ class PostgresAdapter
}

array(values: any[], typeNameOrID?: number | ArrayType): SQLArrayParameter {
const arrayType = getArrayType(typeNameOrID);
const arrayType = getArrayType(values, typeNameOrID);
return new SQLArrayParameter(serializeArray(values, arrayType), arrayType);
}

Expand Down
117 changes: 107 additions & 10 deletions test/js/sql/sql.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -186,6 +186,103 @@ if (isDockerEnabled()) {
expect(update_roles).toEqual(["c", "d"]);
});

test("sql.array without a type infers the element type from the values", async () => {
await using sql = postgres(options);
const [row] = await sql`select
pg_typeof(${sql.array(["a", "b"])}) as strings,
pg_typeof(${sql.array([1, 2])}) as ints,
pg_typeof(${sql.array([1, 2 ** 40])}) as bigints,
pg_typeof(${sql.array([1n, 2n])}) as native_bigints,
pg_typeof(${sql.array([9223372036854775807n, -9223372036854775808n])}) as int64_bounds,
pg_typeof(${sql.array([9223372036854775808n])}) as beyond_int64,
pg_typeof(${sql.array([1, 2n])}) as mixed_ints,
pg_typeof(${sql.array([1.5, 2n])}) as mixed_float_bigint,
pg_typeof(${sql.array([1.5, 2])}) as floats,
pg_typeof(${sql.array([true, false])}) as booleans,
pg_typeof(${sql.array([new Date()])}) as dates,
pg_typeof(${sql.array([Buffer.from("hi")])}) as buffers,
pg_typeof(${sql.array([new Uint8Array([1, 2])])}) as views,
pg_typeof(${sql.array(new Int32Array([1, 2]))}) as typed_array,
pg_typeof(${sql.array([
[1, 2],
[3, null],
])}) as nested,
pg_typeof(${sql.array([null, "a"])}) as with_null,
pg_typeof(${sql.array([{ a: 1 }])}) as objects,
pg_typeof(${sql.array(["a", 1])}) as mixed,
pg_typeof(${sql.array([])}) as empty,
pg_typeof(${sql.array([null])}) as only_null`;
expect(row).toEqual({
strings: "text[]",
ints: "integer[]",
bigints: "bigint[]",
native_bigints: "bigint[]",
int64_bounds: "bigint[]",
beyond_int64: "numeric[]",
mixed_ints: "bigint[]",
mixed_float_bigint: "numeric[]",
floats: "double precision[]",
booleans: "boolean[]",
dates: "timestamp with time zone[]",
buffers: "bytea[]",
views: "json[]",
typed_array: "integer[]",
nested: "integer[]",
with_null: "text[]",
objects: "json[]",
mixed: "json[]",
empty: "json[]",
only_null: "json[]",
});
});

test("sql.array without a type works with casts and typed columns", async () => {
await using sql = postgres(options);
const random_name = "test_" + randomUUIDv7("hex").replaceAll("-", "");
await sql`CREATE TEMPORARY TABLE ${sql(random_name)} (
id SERIAL PRIMARY KEY,
tags TEXT[],
nums INT[],
flags BOOLEAN[],
blobs BYTEA[]
);`;

const [{ id, tags, nums, flags, blobs }] =
await sql`insert into ${sql(random_name)} (tags, nums, flags, blobs) values (${sql.array(["a", 'b"c', null])}, ${sql.array([1, 2, 3])}, ${sql.array([true, false])}, ${sql.array([Buffer.from("hi"), Buffer.from([0, 255])])}) returning *`;
expect({ id, tags, nums, flags, blobs }).toEqual({
id: 1,
tags: ["a", 'b"c', null],
nums: new Int32Array([1, 2, 3]),
flags: [true, false],
blobs: [Buffer.from("hi"), Buffer.from([0, 255])],
});

// the stored strings carry no JSON quotes
const [{ lengths }] = await sql.unsafe(
`select array(select length(t) from unnest(tags) as t) as lengths from ${random_name}`,
);
expect(lengths).toEqual([1, 3, null]);

const [{ found }] = await sql`select id as found from ${sql(random_name)} where id = ANY(${sql.array([1, 5])})`;
expect(found).toBe(1);

const [{ text_cast, int_cast }] =
await sql`select ${sql.array(["a", "b"])}::text[] as text_cast, ${sql.array([1, 2])}::int[] as int_cast`;
expect(text_cast).toEqual(["a", "b"]);
expect(int_cast).toEqual(new Int32Array([1, 2]));
});

test("sql.array encodes a null element as SQL NULL", async () => {
await using sql = postgres(options);
const [{ text_nulls, json_nulls, bool_nulls }] = await sql`select
${sql.array(["a", null, undefined, "null"], "TEXT")} as text_nulls,
${sql.array([{ a: 1 }, null, undefined], "JSON")} as json_nulls,
${sql.array([true, null], "BOOLEAN")} as bool_nulls`;
expect(text_nulls).toEqual(["a", null, null, "null"]);
expect(json_nulls).toEqual([{ a: 1 }, null, null]);
expect(bool_nulls).toEqual([true, null]);
});

test("sql.array should support jsonb and json", async () => {
await using sql = postgres(options);
{
Expand Down Expand Up @@ -1081,22 +1178,22 @@ if (isDockerEnabled()) {
}
});

// t("Empty array", async () => [true, Array.isArray((await sql`select ${sql.array([], 1009)} as x`)[0].x)]);
test("Empty array", async () =>
expect(Array.isArray((await sql`select ${sql.array([], 1009)} as x`)[0].x)).toBe(true));

test("string arg with ::int -> Array<int>", async () =>
expect((await sql`select ${"{1,2,3}"}::int[] as x`)[0].x).toEqual(new Int32Array([1, 2, 3])));

// t("Array of Integer", async () => ["3", (await sql`select ${sql.array([1, 2, 3])} as x`)[0].x[2]]);
test("Array of Integer", async () => expect((await sql`select ${sql.array([1, 2, 3])} as x`)[0].x[2]).toBe(3));

// t('Array of String', async() =>
// ['c', (await sql`select ${ sql.array(['a', 'b', 'c']) } as x`)[0].x[2]]
// )
test("Array of String", async () =>
expect((await sql`select ${sql.array(["a", "b", "c"])} as x`)[0].x[2]).toBe("c"));

// test("Array of Date", async () => {
// const now = new Date();
// const result = await sql`select ${sql.array([now, now, now])} as x`;
// expect(result[0].x[2].getTime()).toBe(now.getTime());
// });
test("Array of Date", async () => {
const now = new Date();
const result = await sql`select ${sql.array([now, now, now])} as x`;
expect(result[0].x[2].getTime()).toBe(now.getTime());
});

test("Array of Box", async () => {
const result = await sql`select ${"{(1,2),(3,4);(4,5),(6,7)}"}::box[] as x`;
Expand Down