From 8f7a553f85fd66feb70fb8d55da9f60842f1ed47 Mon Sep 17 00:00:00 2001 From: Connor Braa Date: Wed, 22 Apr 2026 15:06:50 -0700 Subject: [PATCH 1/6] docs: document LSD_CHECKPOINT_DELETE env var Adds agent server env var reference for the deferred checkpoint deletion feature flag, covering all configurable JSON fields (enabled, enabledWorkerOnly, pollIntervalMs, batchSize, batchSleepMs) shipped in langgraph-api#3111. Co-Authored-By: Claude Opus 4.7 (1M context) --- src/langsmith/env-var.mdx | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/src/langsmith/env-var.mdx b/src/langsmith/env-var.mdx index 5436adde42..b7731c7c83 100644 --- a/src/langsmith/env-var.mdx +++ b/src/langsmith/env-var.mdx @@ -65,6 +65,22 @@ When [`BG_JOB_ISOLATED_LOOPS`](#bg_job_isolated_loops) is enabled, the pool is n Defaults to `150` connections. +## `LSD_CHECKPOINT_DELETE` + +JSON-valued configuration for deferred checkpoint deletion. When enabled, thread delete and prune operations enqueue checkpoints for background deletion instead of deleting synchronously, moving the I/O off the request hot path. + +Accepted fields: + +- `enabled` (boolean, default `false`): Enables the deferred-delete wrapper and starts the background drain worker. When `true`, `DeleteForThreads` and `Prune` enqueue rows into `checkpoint_delete_queue` and return immediately; the worker drains the queue. +- `enabledWorkerOnly` (boolean, default `false`): Starts only the background drain worker without the wrapper. Use this to finish draining queued entries after rolling `enabled` back to `false`. +- `pollIntervalMs` (integer, default `5000`): How often the worker polls the queue, in milliseconds. +- `batchSize` (integer, default `25`): Number of checkpoint entries the worker dequeues per transaction. Smaller values spread I/O over more time at the cost of longer drain latency. +- `batchSleepMs` (integer, default `500`): How long the worker sleeps between batches when the queue is non-empty, in milliseconds. + +Example: `LSD_CHECKPOINT_DELETE='{"enabled":true,"batchSize":10,"pollIntervalMs":1000}'`. + +Defaults to disabled (synchronous checkpoint deletion). + ## `LS_DEFAULT_CHECKPOINTER_BACKEND` Sets the default [checkpointer backend](/langsmith/configure-checkpointer) for agent servers that don't specify one in `langgraph.json`. Accepted values: `"default"` (PostgreSQL), `"mongo"`, `"custom"`. From b7a3c70f56b06663ae3426b5aad617e06ab8ef48 Mon Sep 17 00:00:00 2001 From: Connor Braa Date: Wed, 22 Apr 2026 15:07:54 -0700 Subject: [PATCH 2/6] docs: note langgraph-api>=0.7.103 for LSD_CHECKPOINT_DELETE The feature shipped in 3111 but the queue table migration did not apply until the renumber fix in 3269, which also bumped the version to 0.7.103. Direct users to that version to avoid hitting the broken migration. Co-Authored-By: Claude Opus 4.7 (1M context) --- src/langsmith/env-var.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/langsmith/env-var.mdx b/src/langsmith/env-var.mdx index b7731c7c83..d6d12b9d53 100644 --- a/src/langsmith/env-var.mdx +++ b/src/langsmith/env-var.mdx @@ -67,7 +67,7 @@ Defaults to `150` connections. ## `LSD_CHECKPOINT_DELETE` -JSON-valued configuration for deferred checkpoint deletion. When enabled, thread delete and prune operations enqueue checkpoints for background deletion instead of deleting synchronously, moving the I/O off the request hot path. +JSON-valued configuration for deferred checkpoint deletion. When enabled, thread delete and prune operations enqueue checkpoints for background deletion instead of deleting synchronously, moving the I/O off the request hot path. Available in `langgraph-api>=0.7.103`. Accepted fields: From ffdfb699418417efb685de4c9e1e5999f63c754f Mon Sep 17 00:00:00 2001 From: Connor Braa Date: Wed, 22 Apr 2026 15:08:41 -0700 Subject: [PATCH 3/6] docs: reword LSD_CHECKPOINT_DELETE to drop "wrapper" terminology Describe the behavior in terms of enqueue/drain instead of the internal checkpointer-wrapper implementation detail. Co-Authored-By: Claude Opus 4.7 (1M context) --- src/langsmith/env-var.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/langsmith/env-var.mdx b/src/langsmith/env-var.mdx index d6d12b9d53..9dd895ed43 100644 --- a/src/langsmith/env-var.mdx +++ b/src/langsmith/env-var.mdx @@ -71,8 +71,8 @@ JSON-valued configuration for deferred checkpoint deletion. When enabled, thread Accepted fields: -- `enabled` (boolean, default `false`): Enables the deferred-delete wrapper and starts the background drain worker. When `true`, `DeleteForThreads` and `Prune` enqueue rows into `checkpoint_delete_queue` and return immediately; the worker drains the queue. -- `enabledWorkerOnly` (boolean, default `false`): Starts only the background drain worker without the wrapper. Use this to finish draining queued entries after rolling `enabled` back to `false`. +- `enabled` (boolean, default `false`): When `true`, thread delete and prune operations enqueue checkpoints into `checkpoint_delete_queue` and return immediately, and the background worker drains the queue. +- `enabledWorkerOnly` (boolean, default `false`): Runs only the background drain worker without enqueuing new entries. Use this to finish draining the queue after rolling `enabled` back to `false`. - `pollIntervalMs` (integer, default `5000`): How often the worker polls the queue, in milliseconds. - `batchSize` (integer, default `25`): Number of checkpoint entries the worker dequeues per transaction. Smaller values spread I/O over more time at the cost of longer drain latency. - `batchSleepMs` (integer, default `500`): How long the worker sleeps between batches when the queue is non-empty, in milliseconds. From cb7822cfbdb616e622ac11ce435acbef03809e8a Mon Sep 17 00:00:00 2001 From: Connor Braa Date: Wed, 22 Apr 2026 15:10:11 -0700 Subject: [PATCH 4/6] docs: note LSD_CHECKPOINT_DELETE is postgres-only and future default MongoDB checkpointer's DeleteCheckpoints explicitly returns unsupported, so the deferred-delete worker only works against the postgres backend. Flag it will become the default later so operators can plan ahead. Co-Authored-By: Claude Opus 4.7 (1M context) --- src/langsmith/env-var.mdx | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/src/langsmith/env-var.mdx b/src/langsmith/env-var.mdx index 9dd895ed43..10e55b114c 100644 --- a/src/langsmith/env-var.mdx +++ b/src/langsmith/env-var.mdx @@ -69,6 +69,10 @@ Defaults to `150` connections. JSON-valued configuration for deferred checkpoint deletion. When enabled, thread delete and prune operations enqueue checkpoints for background deletion instead of deleting synchronously, moving the I/O off the request hot path. Available in `langgraph-api>=0.7.103`. + +Only supported with the default PostgreSQL checkpointer backend. This will become the default in a future release. + + Accepted fields: - `enabled` (boolean, default `false`): When `true`, thread delete and prune operations enqueue checkpoints into `checkpoint_delete_queue` and return immediately, and the background worker drains the queue. From bd435541a02d253dc8c8bae6b8286ab3f360088d Mon Sep 17 00:00:00 2001 From: Connor Braa Date: Wed, 22 Apr 2026 15:11:07 -0700 Subject: [PATCH 5/6] docs: clarify "deferred deletes" will be the future default Co-Authored-By: Claude Opus 4.7 (1M context) --- src/langsmith/env-var.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/langsmith/env-var.mdx b/src/langsmith/env-var.mdx index 10e55b114c..22c609f1cb 100644 --- a/src/langsmith/env-var.mdx +++ b/src/langsmith/env-var.mdx @@ -70,7 +70,7 @@ Defaults to `150` connections. JSON-valued configuration for deferred checkpoint deletion. When enabled, thread delete and prune operations enqueue checkpoints for background deletion instead of deleting synchronously, moving the I/O off the request hot path. Available in `langgraph-api>=0.7.103`. -Only supported with the default PostgreSQL checkpointer backend. This will become the default in a future release. +Only supported with the default PostgreSQL checkpointer backend. Deferred deletes will become the default in a future release. Accepted fields: From e6ffb918333668c282a857522409806b8ff5cd6a Mon Sep 17 00:00:00 2001 From: Connor Braa Date: Thu, 23 Apr 2026 12:40:20 -0700 Subject: [PATCH 6/6] docs: rename to LS_CHECKPOINT_DELETE, bump min version to 0.8.1 --- src/langsmith/env-var.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/langsmith/env-var.mdx b/src/langsmith/env-var.mdx index 22c609f1cb..f46eda4f33 100644 --- a/src/langsmith/env-var.mdx +++ b/src/langsmith/env-var.mdx @@ -65,9 +65,9 @@ When [`BG_JOB_ISOLATED_LOOPS`](#bg_job_isolated_loops) is enabled, the pool is n Defaults to `150` connections. -## `LSD_CHECKPOINT_DELETE` +## `LS_CHECKPOINT_DELETE` -JSON-valued configuration for deferred checkpoint deletion. When enabled, thread delete and prune operations enqueue checkpoints for background deletion instead of deleting synchronously, moving the I/O off the request hot path. Available in `langgraph-api>=0.7.103`. +JSON-valued configuration for deferred checkpoint deletion. When enabled, thread delete and prune operations enqueue checkpoints for background deletion instead of deleting synchronously, moving the I/O off the request hot path. Available in `langgraph-api>=0.8.1`. Only supported with the default PostgreSQL checkpointer backend. Deferred deletes will become the default in a future release. @@ -81,7 +81,7 @@ Accepted fields: - `batchSize` (integer, default `25`): Number of checkpoint entries the worker dequeues per transaction. Smaller values spread I/O over more time at the cost of longer drain latency. - `batchSleepMs` (integer, default `500`): How long the worker sleeps between batches when the queue is non-empty, in milliseconds. -Example: `LSD_CHECKPOINT_DELETE='{"enabled":true,"batchSize":10,"pollIntervalMs":1000}'`. +Example: `LS_CHECKPOINT_DELETE='{"enabled":true,"batchSize":10,"pollIntervalMs":1000}'`. Defaults to disabled (synchronous checkpoint deletion).