Skip to main content
Version: 8

DocumentCache Administration CLI

The dms-document-cache tool inspects and administers one tenant/data-store pair at a time without starting the API web host. Start with the DocumentCache guide for help choosing an activation procedure and checking the result.

Installation​

Install the .NET 10 SDK to use dotnet tool install, and keep the .NET 10 runtime available to run the tool.

feed="https://pkgs.dev.azure.com/ed-fi-alliance/Ed-Fi-Alliance-OSS/_packaging/EdFi%40Release/nuget/v3/index.json"
version="8.1.0"
dotnet tool install --global EdFi.Api.DocumentCacheAdmin --source "$feed" --version "$version"
dms-document-cache --help

Ensure the .NET global tools directory is on PATH. The package includes the default Ed-Fi ApiSchema workspace. For extensions or another effective schema, configure AppSettings:ApiSchema:UseCustomPath=true and AppSettings:ApiSchema:Path to the matching workspace containing bootstrap-api-schema-manifest.json.

Configuration and Target Selection​

Run with complete settings matching the deployed API, its Configuration Service, provider, and effective schema. The operator needs database access appropriate to the selected workflow. For SQL Server, check the database and server settings before activation.

OptionUse
--settings <path>Load an explicit appsettings JSON file.
--environment <name>Select the environment-specific settings file. Without this flag, DOTNET_ENVIRONMENT, then ASPNETCORE_ENVIRONMENT, supplies the environment name.
--datastore postgresql|sqlserverOverride the provider for this invocation. It must match the deployment and selected data store's provider metadata.
--data-store-id <id>Positive Configuration Service data store ID.
--tenant-key <value>Tenant key; omit for the normalized default tenant ("").
--jsonEmit the shared result contract as JSON.

Settings load from appsettings.json in the working directory, then appsettings.<environment>.json, then the explicit --settings file. Environment variables override those files; supported command-line configuration overrides apply last. Use double underscores in environment keys, for example DataManagement__DocumentCache__ReadAcceleration__Enabled.

Keep connection strings and client credentials in protected settings or environment variables supplied by your deployment's secret management. The CLI does not expose secret-bearing command-line arguments. Mixed-provider targets backed by the Configuration Service are not a supported production topology.

Inspect Status​

With data store 1 registered and selected in DataManagement:DocumentCache:Targets in the complete settings:

dms-document-cache status --data-store-id 1 --settings ./appsettings.Production.json --environment Production --datastore postgresql --json

Add --tenant-key district-a for a named tenant. With --json, results go to standard output and logs go to standard error or the configured log destination. Verify the tenant and data store in targetKey. After activation, check that lifecycle.state is tracking and cacheAhead.state is clear.

The CLI reads database state and reports unknown with reason runtimeNotObserved for operationalHealth and caughtUp. Use the running API's status endpoint to verify the worker is healthy and caught up.

Pass a Request as JSON​

A script can supply the request in a file with --request-json <path> or through standard input with --request-json -. For example, save the following status request as status-target.json.

{ "targetKey": { "tenantKey": "", "dataStoreId": 1 } }
dms-document-cache status --request-json status-target.json \
--settings ./appsettings.Production.json --environment Production --json

When using --request-json, put the target and any required confirmation in the request. If the command requires --offline-writer-admission, include "offlineWriterAdmission": "closedAndDrained" in the JSON. For offline activation, you can also set expectedPhysicalSourceFingerprint to the value from status to verify that you're activating the same database.

Omit --tenant-key, --data-store-id, --confirm, --offline-writer-admission, and --expected-physical-source-fingerprint from the command line. You can still use --settings, --environment, --datastore, and --json.

Commands​

Supply the token shown with --confirm. For commands marked offline, stop writers and wait for writes in progress to finish. Then pass --offline-writer-admission closedAndDrained to acknowledge those steps. Keep writers stopped through retries.

CommandRequired confirmationWhen to use it
activate-new-emptynewEmptyActivationStart the cache on a newly provisioned database before its first resource or descriptor write. Stop writers and wait for writes in progress to finish first.
activate-offlineofflineActivationOffline. Build the first cached copies on an existing disabled database with the required publication history.
deactivate-offlineofflineDeactivationOffline. Clear cached copies and pending updates, then enter disabled. Requires the same publication history as offline activation.
rebuild-onlineonlineCacheRebuildRebuild cached copies while writes continue. Requires tracking or rebuilding and a clear cache-ahead flag.
scrubintegrityScrubCheck the cache against relational data and repair missing or incorrect queued updates. Requires tracking and a clear cache-ahead flag.
recover-cache-aheadinternalCacheAheadRecoveryOffline. Recover when a cached version is newer than its source. Requires the original publication history and the checks in the recovery procedure.

Follow the activation steps for a new database or an existing database. If a command stops in resetting or rebuilding, resume the same command with the same target and options. For other symptoms, see When Something Goes Wrong.

Removing a data store from Targets pauses the worker for that database. The database continues recording pending updates until you deactivate the cache.

Optional Checks and Time Limits​

OptionDefaultMeaning
--expected-physical-source-fingerprint <value>NoneProceed only if the selected database still matches the identifier from the last status check.
--command-timeout-seconds <seconds>86400Total administrative workflow budget.
--status-observation-timeout-seconds <seconds>5Time allowed to read each target's status from the database.
--status-timeout-seconds <seconds>30Overall status budget.

Timeout arguments are positive numeric seconds. For configuration equivalents, see Configuration Details.

Offline Administration History​

For activate-offline, deactivate-offline, and recover-cache-ahead, the original provisioning records must show that this database has never published changes to Kafka or another downstream system. The CLI calls this internalOnly. Managed provisioning records that history at database creation. Stopping or removing a Kafka connector cannot establish it later.

Find the original --managed-state-path and --deployment-key in your provisioning scripts or deployment settings. If the path was relative, resolve it against the original working directory or mounted volume. If the key was omitted, its default was local. The directory must still hold the original creation receipt, workflow journal, and source history.

Add the following to the complete CLI settings, substituting the original path and key. Use the same protected directory as provisioning and CDC administration. The tools use the same lock in that directory to prevent overlapping operations. A separate copy has its own lock.

{
"Cdc": {
"PublicationHistory": {
"StatePath": "/absolute/original/controller-state",
"DeploymentKey": "original-deployment-key",
"LockTimeout": "00:00:30"
}
}
}

Restrict access to the directory to its owner. The CLI holds the lock through the command. LockTimeout sets how long it waits to acquire the lock. The default is 30 seconds and the allowed range is greater than zero through ten minutes. Check for environment overrides such as Cdc__PublicationHistory__StatePath and Cdc__PublicationHistory__DeploymentKey.

The CLI rejects an offline command if it cannot read matching records or the history is unknown. If this database was created without managed history, use the new database procedure and reload the data after verification. If records are damaged or publication may have occurred, preserve the records and follow the history and recovery guidance.

Activate an Existing Database​

  1. Prepare the target and settings and configure offline administration history using the original provisioning records. For SQL Server, check the SQL Server prerequisites.

  2. Inspect the target. This example uses PostgreSQL, data store 1, and the default tenant. Substitute your registered ID, use --datastore sqlserver for SQL Server, and add --tenant-key <your-tenant-key> for a named tenant.

    dms-document-cache status --data-store-id 1 \
    --settings ./appsettings.Production.json --environment Production --datastore postgresql --json

    Verify targetKey.tenantKey and targetKey.dataStoreId and check that lifecycle.state is disabled. Copy physicalSourceFingerprint, the identifier for the database the CLI actually reached. Supplying this value in the next command prevents changes if the target now points elsewhere.

  3. Stop all API instances, bulk loaders, scheduled jobs, and other writers for this database. Prevent automatic restarts and wait for all writes in progress to finish. Keep writers stopped through activation and any retries.

  4. Activate the cache using the same target, provider, and settings. Replace the example fingerprint with the entire value from status, including sha256:. The command checks the original history before changing the cache.

    dms-document-cache activate-offline --data-store-id 1 \
    --confirm offlineActivation --offline-writer-admission closedAndDrained \
    --expected-physical-source-fingerprint "sha256:<observed-lowercase-hex>" \
    --settings ./appsettings.Production.json --environment Production --datastore postgresql --json
  5. If the CLI returns exit code 12, keep writers stopped and retry the same command with the same target and fingerprint. After completed (exit code 0), finish activation.

Exit Codes​

CodeMeaning
0The command completed. For status, read the result to check the target's state.
1The command failed unexpectedly. Check the error details.
10A safety check stopped the command before it changed the database. Read the reason in the output.
11The command failed before changing the database, or status could not return a complete result.
12The command stopped before it finished and may have changed the database. Retry it with the same target and options.
64Check the command arguments, confirmation token, or request JSON for errors.
78The CLI could not load a valid configuration. Check the settings files and environment variables.

If the command requires downtime, keep writers stopped through every retry.

Representation Restamp​

Run a restamp only when a release's upgrade instructions call for it. A restamp corrects how resources appear in API responses and Kafka messages after a change to the code that generates JSON. It advances ContentVersion and updates ContentLastModifiedAt so clients can detect the correction.

Keep all access to the database stopped, including readers, writers, workers, and loaders, while deploying the corrected code and running the procedure.

  • restamp-preview saves an operation record. It requires --mode (tracking or disabled, matching the database's lifecycle), --reason with a short explanation, and --offline-writer-admission closedAndDrained. Choose exactly one scope. For a resource type, pass both --project-name and --resource-name. For individual documents, pass --document-uuid once for each UUID. Confirm cacheAhead.state is clear before running the preview.
  • restamp-execute requires --confirm representationRestamp, the same offline option, and the operation ID from the preview. For an incomplete execution, retry with that same target and operation ID.

In tracking mode the command queues the corrected resources for the worker to process. In disabled mode it updates versions and timestamps in the relational tables. Follow the upgrade instructions for your release before restoring service.