From 19a925d6fe58adb2e1116bd853d2183027223754 Mon Sep 17 00:00:00 2001 From: Blake Gentry Date: Thu, 29 Aug 2024 11:11:57 -0500 Subject: [PATCH] improve InsertTx documentation (#569) I got this feedback from a River Pro customer who mentioned that we had a better explanation of the reasons to use `InsertTx` on the docs website than we had in the godoc. This attempts to bridge that gap by providing a better explanation in the method comments. --- client.go | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/client.go b/client.go index 4a83bb03..4aa69df9 100644 --- a/client.go +++ b/client.go @@ -1276,8 +1276,11 @@ func (c *Client[TTx]) Insert(ctx context.Context, args JobArgs, opts *InsertOpts // } // // This variant lets a caller insert jobs atomically alongside other database -// changes. An inserted job isn't visible to be worked until the transaction -// commits, and if the transaction rolls back, so too is the inserted job. +// changes. It's also possible to insert a job outside a transaction, but this +// usage is recommended to ensure that all data a job needs to run is available +// by the time it starts. Because of snapshot visibility guarantees across +// transactions, the job will not be worked until the transaction has committed, +// and if the transaction rolls back, so too is the inserted job. func (c *Client[TTx]) InsertTx(ctx context.Context, tx TTx, args JobArgs, opts *InsertOpts) (*rivertype.JobInsertResult, error) { return c.insert(ctx, c.driver.UnwrapExecutor(tx), args, opts) }