How to configure a Store for States' Workers?

This guide explains what Stores are in beVault, the two categories you’ll encounter (dbStore and fileStore), and how to configure them so States’ workers can extract from or write to external systems.

What’s a Store?

In beVault States, a Store is a physical endpoint that workers use to access data. Stores abstract connection details and credentials, allowing workers to read from or write to databases and file systems through a uniform interface. Typical destinations include databases (PostgreSQL, SQL Server, Snowflake, Oracle, etc.) and file systems or services (local directories, SFTP, S3, GitLab).

Two categories:
- dbStore: Database-oriented stores (Category = Db; e.g., postgresql, sqlserver, snowflake, oracle)
- fileStore: File-oriented stores (Category = File; e.g., file for directories, sftp, s3, gitlab)

For a complete list of supported stores and their type-specific configuration keys, see Stores documentation

How workers use Stores?

States’ workers poll the orchestrator for tasks, and when executing a task (e.g., querying a database, listing files, or bulk inserting), they reference a configured Store by its name. The worker reads the Store’s type and config to connect to the target system and perform the operation.

Configure stores during worker installation

Stores are set up when you install and configure the States’ workers. You can provide the store definitions in either of the following ways:

JSON configuration file:
- Define your stores in a stores.json file.
- Reference that file from the worker’s appsettings.json using the StoreConfigFile key.
Environment variables:
- Provide the same configuration via environment variables with the prefix DFAKTO_WORKERS_STORES__.

Both methods are supported by the Workers configuration and are functionally equivalent.

Base configuration model

All Stores share a common base schema. You define one or more stores and give each a unique Name. The Type selects the store driver; Config contains type-specific settings (like ConnectionString or BasePath). HealthCheck can be enabled to validate connectivity at startup.

Example :

JSON

{
  "Name": "df-staging",
  "Type": "postgresql",
  "HealthCheck": true,
  "Config": {
    "ConnectionString": ""
  }
}

Key fields:

Name (string, required): Unique identifier used by workers.
Type (string, required): Store driver (e.g., postgresql, sqlserver, file, sftp, s3, …).
HealthCheck (bool, optional): Enable to verify connectivity on startup.
Config (object, required): Type-specific options (see per-store docs ).

Configuration methods

You can configure Stores for States’ workers using either a JSON file or environment variables.

Option A — stores.json file

Create stores.json with your store definitions:

JSON

{
  "Stores": {
    "Stores": [
      {
        "Name": "postgresql_store",
        "Type": "postgresql",
        "HealthCheck": true,
        "Config": {
          "ConnectionString": "Server=localhost;Port=5432;User Id=postgres;Password=password;Database=main"
        }
      }
    ]
  }
}

In your worker’s appsettings.json, reference the file:
JSON
```
{
  "StoreConfigFile": "stores.json"
}
```

Option B — Environment variables

Use indexed keys under DFAKTO_WORKERS_STORES__STORES__{i}. Double underscores map to JSON nesting.

Example: one fileStore and one dbStore

CODE

DFAKTO_WORKERS_STORES__STORES__0__Name=files
DFAKTO_WORKERS_STORES__STORES__0__Type=file
DFAKTO_WORKERS_STORES__STORES__0__HealthCheck=true
DFAKTO_WORKERS_STORES__STORES__0__Config__BasePath=/some/path

DFAKTO_WORKERS_STORES__STORES__1__Name=mydb
DFAKTO_WORKERS_STORES__STORES__1__Type=sqlserver
DFAKTO_WORKERS_STORES__STORES__1__HealthCheck=true
DFAKTO_WORKERS_STORES__STORES__1__Config__ConnectionString="Server=...;Database=...;User ID=...;Password=...;"

Notes:

Indexes are zero-based and continuous (0, 1, 2, …).
Use the exact casing shown for keys.

Apply the new configuration (restart required)

Changes to stores.json or environment variables are applied only after the workers restart. After adding or updating stores, restart your worker processes or containers.

If your workers are deployed with Docker Compose, you can restart them with:

POWERSHELL

docker compose restart workers

References

Workers Config: Store configuration location, env var examples, and logging settings .
Stores: Base schema and complete list of available stores with type-specific configuration .
Architecture & Installation: How Stores fit in the overall beVault/States runtime .