From ef33f15005be56f8530eadd4023413b422662977 Mon Sep 17 00:00:00 2001
From: Eduardo Gurgel Pinho <eduardo@gurgel.me>
Date: Wed, 22 Jul 2026 15:53:13 +1200
Subject: [PATCH 1/3] fix: add missing options to query typespec

---
 lib/postgrex.ex | 18 ++++++++++++------
 1 file changed, 12 insertions(+), 6 deletions(-)

diff --git a/lib/postgrex.ex b/lib/postgrex.ex
index 416d21ae..7d28f240 100644
--- a/lib/postgrex.ex
+++ b/lib/postgrex.ex
@@ -64,6 +64,12 @@ defmodule Postgrex do
           {:decode_mapper, (list -> term)}
           | option
 
+  @type query_option ::
+          {:cache_statement, String.t()}
+          | {:query_type, :binary | :text}
+          | {:comment, String.t()}
+          | execute_option
+
   @max_rows 500
   @timeout 15_000
 
@@ -303,7 +309,7 @@ defmodule Postgrex do
 
       Postgrex.query(conn, "COPY posts TO STDOUT", [])
   """
-  @spec query(conn, iodata, list, [execute_option]) ::
+  @spec query(conn, iodata, list, [query_option]) ::
           {:ok, Postgrex.Result.t()} | {:error, Exception.t()}
   def query(conn, statement, params \\ [], opts \\ []) when is_list(params) and is_list(opts) do
     query_type = Keyword.get(opts, :query_type, :binary)
@@ -381,7 +387,7 @@ defmodule Postgrex do
   Runs an (extended) query and returns the result or raises `Postgrex.Error` if
   there was an error. See `query/3`.
   """
-  @spec query!(conn, iodata, list, [execute_option]) :: Postgrex.Result.t()
+  @spec query!(conn, iodata, list, [query_option]) :: Postgrex.Result.t()
   def query!(conn, statement, params \\ [], opts \\ []) when is_list(params) and is_list(opts) do
     case query(conn, statement, params, opts) do
       {:ok, result} -> result
@@ -417,7 +423,7 @@ defmodule Postgrex do
 
       Postgrex.prepare(conn, "", "CREATE TABLE posts (id serial, title text)")
   """
-  @spec prepare(conn, iodata, iodata, [option]) ::
+  @spec prepare(conn, iodata, iodata, [option | {:comment, String.t()}]) ::
           {:ok, Postgrex.Query.t()} | {:error, Exception.t()}
   def prepare(conn, name, statement, opts \\ []) do
     query = %Query{name: name, statement: statement}
@@ -429,7 +435,7 @@ defmodule Postgrex do
   Prepares an (extended) query and returns the prepared query or raises
   `Postgrex.Error` if there was an error. See `prepare/4`.
   """
-  @spec prepare!(conn, iodata, iodata, [option]) :: Postgrex.Query.t()
+  @spec prepare!(conn, iodata, iodata, [option | {:comment, String.t()}]) :: Postgrex.Query.t()
   def prepare!(conn, name, statement, opts \\ []) do
     opts = Keyword.put(opts, :postgrex_prepare, comment_not_present!(opts))
     DBConnection.prepare!(conn, %Query{name: name, statement: statement}, opts)
@@ -465,7 +471,7 @@ defmodule Postgrex do
       Postgrex.prepare_execute(conn, "", "SELECT id FROM posts WHERE title like $1", ["%my%"])
 
   """
-  @spec prepare_execute(conn, iodata, iodata, list, [execute_option]) ::
+  @spec prepare_execute(conn, iodata, iodata, list, [execute_option | {:comment, String.t()}]) ::
           {:ok, Postgrex.Query.t(), Postgrex.Result.t()} | {:error, Postgrex.Error.t()}
   def prepare_execute(conn, name, statement, params, opts \\ []) when is_list(params) do
     query = %Query{name: name, statement: statement}
@@ -477,7 +483,7 @@ defmodule Postgrex do
   Prepares and runs a query and returns the result or raises
   `Postgrex.Error` if there was an error. See `prepare_execute/5`.
   """
-  @spec prepare_execute!(conn, iodata, iodata, list, [execute_option]) ::
+  @spec prepare_execute!(conn, iodata, iodata, list, [execute_option | {:comment, String.t()}]) ::
           {Postgrex.Query.t(), Postgrex.Result.t()}
   def prepare_execute!(conn, name, statement, params, opts \\ []) when is_list(params) do
     query = %Query{name: name, statement: statement}

From 9f0693dc216f2fd7ae16dfcb1ef0ed7e0dcf7005 Mon Sep 17 00:00:00 2001
From: Eduardo Gurgel Pinho <eduardo@gurgel.me>
Date: Wed, 22 Jul 2026 15:53:49 +1200
Subject: [PATCH 2/3] fix: add missing doc on :comment

---
 lib/postgrex.ex | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/lib/postgrex.ex b/lib/postgrex.ex
index 7d28f240..7ff77e95 100644
--- a/lib/postgrex.ex
+++ b/lib/postgrex.ex
@@ -294,6 +294,9 @@ defmodule Postgrex do
     * `:query_type` - Either `:binary` or `:text`. If `:binary` then the
       extended query protocol is used. If `:text` then the simple protocol
       is used. Defaults to `:binary`.
+    * `:comment` - When a binary string is provided, appends the given text to the
+      query wrapped in a `/* ... */` SQL comment. The comment cannot contain null
+      bytes or the sequence `*/`. Note it is not supported with `:cache_statement`.
 
   ## Examples
 

From 1e8681a096df788aaf173293a25a3735de8810f6 Mon Sep 17 00:00:00 2001
From: Eduardo Gurgel Pinho <eduardo@gurgel.me>
Date: Wed, 22 Jul 2026 16:54:36 +1200
Subject: [PATCH 3/3] fix: add :comment to missing places

---
 lib/postgrex.ex | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/lib/postgrex.ex b/lib/postgrex.ex
index 7ff77e95..6f7bda79 100644
--- a/lib/postgrex.ex
+++ b/lib/postgrex.ex
@@ -421,6 +421,9 @@ defmodule Postgrex do
     * `:timeout` - Prepare request timeout (default: `#{@timeout}`);
     * `:mode` - set to `:savepoint` to use a savepoint to rollback to before the
     prepare on error, otherwise set to `:transaction` (default: `:transaction`);
+    * `:comment` - When a binary string is provided, appends the given text to the
+      query wrapped in a `/* ... */` SQL comment. The comment cannot contain null
+      bytes or the sequence `*/`.
 
   ## Examples
 
@@ -468,6 +471,9 @@ defmodule Postgrex do
     decoding, (default: `fn x -> x end`);
     * `:mode` - set to `:savepoint` to use a savepoint to rollback to before the
     execute on error, otherwise set to `:transaction` (default: `:transaction`);
+    * `:comment` - When a binary string is provided, appends the given text to the
+      query wrapped in a `/* ... */` SQL comment. The comment cannot contain null
+      bytes or the sequence `*/`.
 
   ## Examples