feat: support raw sql

src/factories/createSqlTag.ts

@@ -208,6 +208,16 @@ sql.unnest = (
   };
 };
 
+sql.raw = (
+  rawSql: string,
+): SqlSqlToken => {
+  return {
+    sql: rawSql,
+    type: SqlToken,
+    values: [],
+  };
+};
+
 export const createSqlTag = <T extends QueryResultRow = QueryResultRow>(): SqlTaggedTemplate<T> => {
   return sql;
 };

src/types.ts

@@ -367,6 +367,12 @@ export type SqlTaggedTemplate<T extends UserQueryResultRow = QueryResultRow> = {
   json: (value: SerializableValue) => JsonSqlToken,
   jsonb: (value: SerializableValue) => JsonBinarySqlToken,
   literalValue: (value: string) => SqlSqlToken,
+  /**
+   * **CAUTION:** Use this function with care.
+   *
+   * Directly injects a raw SQL string into the query.
+   */
+  raw: (rawSql: string) => SqlSqlToken,
   timestamp: (date: Date) => TimestampSqlToken,
   unnest: (
     // Value might be ReadonlyArray<ReadonlyArray<PrimitiveValueExpression>>,

test/helpers/createIntegrationTests.ts

@@ -158,6 +158,33 @@ export const createIntegrationTests = (
     await t.throwsAsync(firstConnection.oneFirst(sql`SELECT 1`));
   });
 
+  test('allows sql.raw to be used', async (t) => {
+    const pool = await createPool(t.context.dsn, {
+      PgPool,
+    });
+
+    await pool.query(sql`
+      CREATE TABLE people (
+        id SERIAL PRIMARY KEY,
+        name text
+      )
+    `);
+
+    await pool.query(sql`
+      INSERT INTO people (name)
+      VALUES (${sql.raw('\'foo\'')})
+    `);
+
+    const result = await pool.oneFirst(sql`
+      SELECT name
+      FROM people
+    `);
+
+    t.is(result, 'foo');
+
+    await pool.end();
+  });
+
   // We have to test serialization due to the use of different drivers (pg and postgres).
   test('serializes json', async (t) => {
     const pool = await createPool(t.context.dsn, {

test/slonik/templateTags/sql/raw.ts

@@ -0,0 +1,19 @@
+import {
+  createSqlTag,
+} from '../../../../src/index.js';
+import {
+  SqlToken,
+} from '../../../../src/tokens.js';
+import test from 'ava';
+
+const sql = createSqlTag();
+
+test('creates an object describing a query with an inlined raw value', (t) => {
+  const query = sql`CREATE USER foo WITH PASSWORD ${sql.raw('\'bar\'')}`;
+
+  t.deepEqual(query, {
+    sql: 'CREATE USER foo WITH PASSWORD \'bar\'',
+    type: SqlToken,
+    values: [],
+  });
+});