# KV Store: Atomic Operations

**Page:** api/sqlite/kv-atomic

[Download Raw Markdown](./api/sqlite/kv-atomic.md)

---

{/* AUTO-GENERATED — Do not edit manually. Regenerate with: npm run docs:api:generate */}



The KV Store atomic array operations let you manipulate JSON array values stored in the KV store without race conditions. Use these endpoints to append elements, remove elements by index or value, or pop the last element from an array. All operations support JSON paths for targeting nested arrays inside a stored object, and optionally write to history for audit and rollback workflows.

## Push to array

### `POST /api/v1/sqlite/kv/{key}/push`

Append a value to an array stored at `key`. If the key holds an object, use the `path` parameter to target a nested array.

### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `key` | path | string | Yes | Key name |
| `db` | query | string | Yes | Database file path |
| `table` | query | string | No | Custom table name. Default: `kv_store` |
| `path` | query | string | No | JSON path to nested array |
| `history` | query | boolean | No | Enable history tracking. Default: `true` |

### Request Body

A value to append to the array.

```json
{
  "event": "user_signup",
  "userId": "u_8f2a1b",
  "timestamp": "2026-01-15T10:30:00Z"
}
```

### Response



Value appended successfully.

```json
{
  "success": true,
  "key": "events",
  "newLength": 42
}
```


Invalid request or not an array.

```json
{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Value at key 'events' is not an array"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `INVALID_DB_PATH` | Invalid database path | The provided database path is invalid or inaccessible | Provide a valid absolute path, or use bare name / ./name shorthand (resolved to /hoody/databases/*.db) |
| `INVALID_PARAMETERS` | Invalid request parameters | One or more request parameters are invalid or malformed | Check parameter types and values against the API specification |
| `INVALID_SQLITE_HEADER` | Not a valid SQLite database | The file exists but is not a valid SQLite database | Ensure the file is a valid SQLite database with proper header |
| `PATH_IS_DIRECTORY` | Path is a directory | Expected a .db file but got a directory (use table parameter for directory mode) | Use a .db file path or add table parameter for directory mode KV store |


Internal server error.

```json
{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "Database write failed"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `DATABASE_ERROR` | Database operation failed | An internal database error occurred | Check server logs for details. Database may be corrupted or locked. |
| `FILE_SYSTEM_ERROR` | File system error | Failed to read or write filesystem in directory mode | Check file permissions and disk space |



### SDK Usage

```ts
const result = await client.sqlite.kvStore.push({
  key: 'events',
  db: '/hoody/databases/app.db',
  data: {
    event: 'user_signup',
    userId: 'u_8f2a1b',
    timestamp: '2026-01-15T10:30:00Z'
  }
});
```


When targeting a nested array, pass a JSON path such as `$.queue` or `$.users[0].tags` in the `path` parameter. The append is performed atomically on the resolved array.


## Pop from array

### `POST /api/v1/sqlite/kv/{key}/pop`

Pop the last element from an array stored at `key`. If the key holds an object, use the `path` parameter to target a nested array.

### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `key` | path | string | Yes | Key name |
| `db` | query | string | Yes | Database file path |
| `table` | query | string | No | Custom table name. Default: `kv_store` |
| `path` | query | string | No | JSON path to nested array |
| `history` | query | boolean | No | Enable history tracking. Default: `true` |

### Response



Value popped successfully.

```json
{
  "key": "events",
  "value": {
    "event": "user_signup",
    "userId": "u_8f2a1b",
    "timestamp": "2026-01-15T10:30:00Z"
  },
  "newLength": 41
}
```


Invalid request or not an array.

```json
{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Value at key 'events' is not an array"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `INVALID_DB_PATH` | Invalid database path | The provided database path is invalid or inaccessible | Provide a valid absolute path, or use bare name / ./name shorthand (resolved to /hoody/databases/*.db) |
| `INVALID_PARAMETERS` | Invalid request parameters | One or more request parameters are invalid or malformed | Check parameter types and values against the API specification |
| `INVALID_SQLITE_HEADER` | Not a valid SQLite database | The file exists but is not a valid SQLite database | Ensure the file is a valid SQLite database with proper header |
| `PATH_IS_DIRECTORY` | Path is a directory | Expected a .db file but got a directory (use table parameter for directory mode) | Use a .db file path or add table parameter for directory mode KV store |


Key not found.

```json
{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Key 'events' does not exist"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `KEY_NOT_FOUND` | Key not found | The requested key does not exist in the KV store | Verify the key name and database/table parameters |
| `DATABASE_NOT_FOUND` | Database file does not exist | The specified database file was not found | Check the file path or use create_db_if_missing=true to create it |
| `KEY_EXPIRED` | Key expired | The key existed but has expired due to TTL | The key was automatically deleted. Store a new value if needed. |


Internal server error.

```json
{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "Database write failed"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `DATABASE_ERROR` | Database operation failed | An internal database error occurred | Check server logs for details. Database may be corrupted or locked. |
| `FILE_SYSTEM_ERROR` | File system error | Failed to read or write filesystem in directory mode | Check file permissions and disk space |



### SDK Usage

```ts
const result = await client.sqlite.kvStore.pop({
  key: 'events',
  db: '/hoody/databases/app.db'
});
```

## Remove array element

### `POST /api/v1/sqlite/kv/{key}/remove`

Remove an element from an array stored at `key`. Use the `index` query parameter to remove by position, or pass a value in the request body to remove the first matching element. Supports JSON paths for nested arrays.

### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `key` | path | string | Yes | Key name |
| `db` | query | string | Yes | Database file path |
| `table` | query | string | No | Custom table name. Default: `kv_store` |
| `path` | query | string | No | JSON path to nested array |
| `index` | query | integer | No | Array index to remove |
| `history` | query | boolean | No | Enable history tracking. Default: `true` |

### Request Body

The value to match and remove. Required when removing by value (i.e. when `index` is not provided).

```json
{
  "event": "user_signup",
  "userId": "u_8f2a1b"
}
```

### Response



Element removed successfully.

```json
{
  "success": true,
  "key": "events",
  "removedIndex": 3,
  "newLength": 40
}
```


Invalid request or not an array.

```json
{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Provide either index query parameter or value in request body"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `INVALID_DB_PATH` | Invalid database path | The provided database path is invalid or inaccessible | Provide a valid absolute path, or use bare name / ./name shorthand (resolved to /hoody/databases/*.db) |
| `INVALID_PARAMETERS` | Invalid request parameters | One or more request parameters are invalid or malformed | Check parameter types and values against the API specification |
| `INVALID_SQLITE_HEADER` | Not a valid SQLite database | The file exists but is not a valid SQLite database | Ensure the file is a valid SQLite database with proper header |
| `PATH_IS_DIRECTORY` | Path is a directory | Expected a .db file but got a directory (use table parameter for directory mode) | Use a .db file path or add table parameter for directory mode KV store |


Key or value not found.

```json
{
  "statusCode": 404,
  "error": "Not Found",
  "message": "No matching element found"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `KEY_NOT_FOUND` | Key not found | The requested key does not exist in the KV store | Verify the key name and database/table parameters |
| `DATABASE_NOT_FOUND` | Database file does not exist | The specified database file was not found | Check the file path or use create_db_if_missing=true to create it |
| `KEY_EXPIRED` | Key expired | The key existed but has expired due to TTL | The key was automatically deleted. Store a new value if needed. |


Internal server error.

```json
{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "Database write failed"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `DATABASE_ERROR` | Database operation failed | An internal database error occurred | Check server logs for details. Database may be corrupted or locked. |
| `FILE_SYSTEM_ERROR` | File system error | Failed to read or write filesystem in directory mode | Check file permissions and disk space |



### SDK Usage

```ts
// Remove by index
const byIndex = await client.sqlite.kvStore.removeElement({
  key: 'events',
  db: '/hoody/databases/app.db',
  index: 3
});

// Remove by matching value
const byValue = await client.sqlite.kvStore.removeElement({
  key: 'events',
  db: '/hoody/databases/app.db',
  data: { event: 'user_signup', userId: 'u_8f2a1b' }
});
```


Removing by value performs a deep equality match against the first element. If you need to remove all occurrences, call the endpoint in a loop or restructure your data into a keyed map rather than a flat array.