Before an Xperience by Kentico application can start, its database needs to be configured, reachable, and on the same version as the application. Setup scripts, update pipelines, and CI jobs need to know which of these conditions is not met to take the right recovery step. Starting the application and reading the startup logs cannot distinguish a project that is not configured yet from one that needs an update or one that is broken.
The --kxp-db-status command reports the state of the database connection and the database without starting the application. Run the command from the command line to check a project manually, or with the --format json option to branch your automation on the result.
Open the command line prompt.
Go to the root folder of your Xperience project.
Run the following command:
dotnet run --no-build -- --kxp-db-statusThe --no-build parameter skips the project build. If the project isn't built yet, build it first or remove the parameter.
The command reads the CMSConnectionString from the project's configuration file (appsettings.json by default), checks the database, and prints one of the reported states. The application stops after printing the result and does not start the website.
Command details
For a deployed application containing built assemblies, use the dotnet myxperienceproject.dll --kxp-db-status command instead (replace the assembly with the name of your Xperience project's DLL).
Add the -- syntax separator before any parameters that you want to pass directly to the Xperience application. This prevents conflicts with general .NET CLI parameters.
The --format option sets the output format. Use text (default) for a human-readable message, or json for machine-readable output. For details, see Consume the output from scripts.
The command distinguishes the following states:
| State | Meaning | Next step |
|---|---|---|
Ready | The database is available and its version matches the application version. | Start the application. |
MissingConnectionString | The | Add the connection string to the project's configuration. For a new project, create the project database to automatically obtain a configured database. |
NotAvailable | The connection string is configured, but the database cannot be used. Either the connection cannot be established, or the database does not contain Xperience objects. | Check that the connection string is valid, the database server is reachable, and the database was created by Xperience. See Database connection problems. |
UpdateRequired | The database is available, but its version does not match the application version. The message states which side is behind. | If the database version is lower than the application version, update the database using the |
The text output for each state is a short message that describes the state and, when an action is needed, the recommended next step. For example, when the database is outdated, the command reports:
The database version '31.8.0' is lower than the application version '31.9.0'.
Run the application with the '--kxp-update' command to update the database.Add the --format json option to get a JSON object instead of the text message:
dotnet run --no-build -- --kxp-db-status --format json{
"success": true,
"state": "UpdateRequired",
"databaseVersion": "31.8.0",
"applicationVersion": "31.9.0",
"message": "The database version '31.8.0' is lower than the application version '31.9.0'. Run the application with the '--kxp-update' command to update the database."
}| Property | Description |
|---|---|
success |
|
state | One of the reported states. |
databaseVersion | The version stored in the database, or |
applicationVersion | The version of the Xperience NuGet packages the application runs on. |
message | The same human-readable message that the text format prints. |
Exit codes
The command exits with code 0 for every reported state, including NotAvailable and UpdateRequired. To find out whether the database is ready, read the state property. Exit code 1 means that the command itself failed, for example, because of an invalid argument.
The following scripts check the database before starting a deployed application. Each script updates the database when the application is newer than the database. If the state requires manual intervention, the script exits with code 1. The Bash variant uses jq (opens in a new tab) to read the JSON output.
$result = dotnet MyXperienceProject.dll --kxp-db-status --format json | ConvertFrom-Json
switch ($result.state) {
'Ready' {
Write-Host 'Database is ready.'
}
'UpdateRequired' {
if ([version]$result.databaseVersion -lt [version]$result.applicationVersion) {
Write-Host "Updating database from $($result.databaseVersion) to $($result.applicationVersion)."
dotnet MyXperienceProject.dll --kxp-update --skip-confirmation
}
else {
Write-Error "Database version $($result.databaseVersion) is newer than the application. Deploy a matching application version."
exit 1
}
}
default {
Write-Error $result.message
exit 1
}
}result=$(dotnet MyXperienceProject.dll --kxp-db-status --format json)
state=$(echo "$result" | jq -r '.state')
case "$state" in
Ready)
echo "Database is ready."
;;
UpdateRequired)
db_version=$(echo "$result" | jq -r '.databaseVersion')
app_version=$(echo "$result" | jq -r '.applicationVersion')
if [ "$(printf '%s\n' "$db_version" "$app_version" | sort -V | head -n1)" = "$db_version" ] && [ "$db_version" != "$app_version" ]; then
echo "Updating database from $db_version to $app_version."
dotnet MyXperienceProject.dll --kxp-update --skip-confirmation
else
echo "Database version $db_version is newer than the application. Deploy a matching application version." >&2
exit 1
fi
;;
*)
echo "$result" | jq -r '.message' >&2
exit 1
;;
esacParse the JSON output, read the state property, and branch on its value. The same approach works in any scripting environment.
Next steps