Support new mode :append in PgLargeObjects.LargeObject API

This should be convenient when implementing e.g. the
Phoenix.LiveView.UploadWriter behaviour. It receives data via calls to
`write_chunk/2`, but this disallows keeping an open transaction.
Instead, on ever `write_chunk/2` call, we want to open and append to an
object.

Author: frerich

CHANGELOG.md

@@ -4,6 +4,7 @@
 
   * Document difference between `Enum.count/1` and `PgLargeObject.LargeObjects.size/1`
   * Reorder chapters in documentation
+  * Add `:append` option to `PgLargeObjects.LargeObject.open/3` and others.
 
 ## v0.1.2 - 2025-11-12
 

lib/pg_large_objects/large_object.ex

@@ -93,8 +93,9 @@ defmodule PgLargeObjects.LargeObject do
 
   * `:bufsize` - number of bytes to transfer at a time when streaming into/out
     of the object. Defaults to 1MB.
-  * `:mode` - can be one of `:read`, `:write` or `:read_write` indicating
-    whether to open the object for reading, writing, or both. Defaults to `:read`.
+  * `:mode` - can be one of `:read`, `:write`, `:append` or `:read_write`
+    indicating whether to open the object for reading, writing, appending or
+    reading and writing.
 
   ## Return value
 
@@ -117,11 +118,21 @@ defmodule PgLargeObjects.LargeObject do
       case opts[:mode] do
         :read -> Bindings.constant(:inv_read)
         :write -> Bindings.constant(:inv_write)
+        :append -> Bindings.constant(:inv_write)
         :read_write -> Bindings.constant(:inv_read) + Bindings.constant(:inv_write)
         mode -> raise ArgumentError, message: "invalid mode: #{mode}"
       end
 
-    with {:ok, fd} <- Bindings.open(repo, oid, flags) do
+    maybe_seek_to_end = fn
+      fd, :append ->
+        Bindings.lseek64(repo, fd, 0, Bindings.constant(:seek_end))
+
+      _fd, _mode ->
+        {:ok, 0}
+    end
+
+    with {:ok, fd} <- Bindings.open(repo, oid, flags),
+         {:ok, _position} <- maybe_seek_to_end.(fd, opts[:mode]) do
       lob =
         %__MODULE__{
           repo: repo,

test/pg_large_objects/large_object_test.exs

@@ -98,6 +98,15 @@ defmodule PgLargeObjects.LargeObjectTest do
       assert get_large_object!(oid) == "XYZDEFG"
     end
 
+    test "appends if open mode is `:append`" do
+      {:ok, oid} =
+        with_object("ABCDEFG", [mode: :append], fn lob ->
+          assert :ok == LargeObject.write(lob, "XYZ")
+        end)
+
+      assert get_large_object!(oid) == "ABCDEFGXYZ"
+    end
+
     test "fails given invalid object" do
       with_object("", [mode: :write], fn lob ->
         :ok = LargeObject.remove(TestRepo, lob.oid)