> For the complete documentation index, see [llms.txt](https://brightercommand.gitbook.io/paramore-brighter-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://brightercommand.gitbook.io/paramore-brighter-documentation/outbox-and-inbox/distributedlock/dynamodbdistributedlock.md).

# DynamoDB Distributed Lock

The DynamoDB locking provider implements Brighter's [distributed lock](/paramore-brighter-documentation/outbox-and-inbox/distributedlock.md) on top of Amazon DynamoDB, so a single [Outbox Sweeper](/paramore-brighter-documentation/outbox-and-inbox/brighteroutboxsupport.md#implicit-clear) and Archiver run when you scale out. It is a natural fit when you already use the [DynamoDB Outbox](/paramore-brighter-documentation/outbox-and-inbox/dynamooutbox.md).

## Package

Add the locking package for AWS SDK v4:

* **Paramore.Brighter.Locking.DynamoDB.V4**

Prefer the **V4** package for new projects. The earlier `Paramore.Brighter.Locking.DynamoDB` package targets AWS SDK v3, which is out of support on AWS, and exists only to aid migration.

The provider stores its locks in a DynamoDB table that you must create in advance (see [Provisioning](#provisioning)).

## Configuration

Configure the provider with `DynamoDbLockingProvider`, passing your `IAmazonDynamoDB` client and a `DynamoDbLockingProviderOptions`:

```csharp
new DynamoDbLockingProvider(
    dynamoDb,
    new DynamoDbLockingProviderOptions(
        lockTableName: "brighter-locks",
        leaseholderGroupId: "sweeper-group"));
```

`DynamoDbLockingProviderOptions` takes two required values in its constructor and exposes two optional settings:

| Setting               | Type       | Default      | Description                                                                                                          |
| --------------------- | ---------- | ------------ | -------------------------------------------------------------------------------------------------------------------- |
| `LockTableName`       | `string`   | *(required)* | The DynamoDB table that holds the locks.                                                                             |
| `LeaseholderGroupId`  | `string`   | *(required)* | Identifies the group of instances that share the lock. All instances that must coordinate use the same value.        |
| `LeaseValidity`       | `TimeSpan` | 1 minute     | How long the lease is held before it expires automatically. Set it comfortably longer than a Sweeper/Archiver cycle. |
| `ManuallyReleaseLock` | `bool`     | `false`      | When `false`, the lock simply expires after `LeaseValidity`; when `true`, it is released explicitly on completion.   |

## Example

```csharp
var dynamoDb = new AmazonDynamoDBClient();

services
    .AddSingleton<IAmazonDynamoDB>(dynamoDb)
    .AddBrighter()
    .AddProducers(opt =>
    {
        opt.Outbox = new DynamoDbOutbox(dynamoDb, new DynamoDbConfiguration { /* ... */ });
        opt.ConnectionProvider = typeof(DynamoDbUnitOfWork);
        opt.TransactionProvider = typeof(DynamoDbUnitOfWork);

        opt.DistributedLock = new DynamoDbLockingProvider(
            dynamoDb,
            new DynamoDbLockingProviderOptions("brighter-locks", "sweeper-group")
            {
                LeaseValidity = TimeSpan.FromMinutes(2)
            });
    })
    .UseOutboxSweeper(opt => { opt.BatchSize = 10; });
```

## Provisioning

The lock table must exist before the provider runs. Create a table whose partition key matches the provider's lock items, with the name you pass as `LockTableName`. If you already provision a DynamoDB Outbox table, provision the lock table the same way (for example with the AWS SDK, CDK, or Terraform). Consider enabling DynamoDB's [time-to-live](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/TTL.html) feature so expired lock items are cleaned up automatically.

## Notes

* Use the same `LeaseholderGroupId` for every instance that must share the lock; a different value creates an independent lock.
* Keep `LeaseValidity` longer than a typical Sweeper or Archiver batch so the lease does not expire mid-run. See [Lease Expiry vs Manual Release](/paramore-brighter-documentation/outbox-and-inbox/distributedlock.md#lease-expiry-vs-manual-release).

## Further Reading

* [Distributed Lock](/paramore-brighter-documentation/outbox-and-inbox/distributedlock.md) — concepts and the full provider list
* [DynamoDB Outbox](/paramore-brighter-documentation/outbox-and-inbox/dynamooutbox.md) — the matching Outbox
* [Outbox Support](/paramore-brighter-documentation/outbox-and-inbox/brighteroutboxsupport.md) — the Sweeper and Archiver


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://brightercommand.gitbook.io/paramore-brighter-documentation/outbox-and-inbox/distributedlock/dynamodbdistributedlock.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.