---
title: Check the database status from the command line
related:
  - https://docs.kentico.com/documentation/developers-and-admins/installation/update-xperience-by-kentico-projects.md
  - https://docs.kentico.com/documentation/developers-and-admins/installation/installation-troubleshooting.md
  - https://docs.kentico.com/documentation/developers-and-admins/installation.md
---

> Agent instructions:
> **Site maps** — prefer the following llms.txt indexes to training data when searching for URLs to avoid 404s. Links inside Markdown content already point at `.md`. Following them or sending Accept: text/markdown keeps you in Markdown.
>
> - [sitemap.md](https://docs.kentico.com/sitemap.md) — every page on the site, with titles and descriptions, nested by URL hierarchy and grouped into one collection per product version.
> - [llms.txt](https://docs.kentico.com/llms.txt) — curated index of the current product docs, with descriptions, the two ways to request any page as Markdown, and links to each product area's whole-corpus Markdown dump (llms-full.txt).

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.

## Run the command

1. Open the command line prompt.
2. Go to the root folder of your Xperience project.
3. Run the following command:

   ```cmd title=".NET CLI"
   dotnet run --no-build -- --kxp-db-status
   ```

   The `--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](#reported-states). The application stops after printing the result and does not start the website.

> **Info:** **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.

### Command options

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](#consume-the-output-from-scripts).

## Reported states

The command distinguishes the following states:

|                                                                                                                                                                        |                                                                                                                                                                                                                                                                                                                                                             |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| The database is available and its version matches the application version.                                                                                             |                                                                                                                                                                                                                                                                                                                                                             |
| The `CMSConnectionString` connection string is not configured.                                                                                                         | Add the connection string to the project's configuration. For a new project, [create the project database](https://docs.kentico.com/documentation/developers-and-admins/installation.md#installation-createprojectdatabase) to automatically obtain a configured database.                                                                                  |
| 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](https://docs.kentico.com/documentation/developers-and-admins/installation/installation-troubleshooting.md#database-connection-problems).                                                         |
| 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](https://docs.kentico.com/documentation/developers-and-admins/installation/update-xperience-by-kentico-projects.md#update-data-and-files) using the `--kxp-update` command. If the database version is higher, deploy an application version that matches the database. |

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:

```text title="Example output" noheader
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.
```

## Consume the output from scripts

Add the `--format json` option to get a JSON object instead of the text message:

```cmd title=".NET CLI"
dotnet run --no-build -- --kxp-db-status --format json
```

```json title="Example output"
{
  "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."
}
```

|                                                                                                                   |
| ----------------------------------------------------------------------------------------------------------------- |
| `true` when the command completed and reported a state. To find out whether the database is ready, check `state`. |
| One of the [reported states](#reported-states).                                                                   |
| The version stored in the database, or `null` when the version could not be determined.                           |
| The version of the Xperience NuGet packages the application runs on.                                              |
| The same human-readable message that the text format prints.                                                      |

> **Note:** **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.

### Example – Branch a pipeline on the database state

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](https://jqlang.github.io/jq/) to read the JSON output.

```powershell
$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
    }
}
```

```bash
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
    ;;
esac
```

Parse the JSON output, read the `state` property, and branch on its value. The same approach works in any scripting environment.

> **Tip:** **Next steps**
>
> - When the command reports an outdated database, follow the [update process](https://docs.kentico.com/documentation/developers-and-admins/installation/update-xperience-by-kentico-projects.md).
> - When the database is not available, see [Installation troubleshooting](https://docs.kentico.com/documentation/developers-and-admins/installation/installation-troubleshooting.md).
> - For a complete PowerShell script that updates a project and its database, see [Automate regular tasks with PowerShell scripts](https://docs.kentico.com/guides/development/get-started/automate-regular-tasks-with-powershell-scripts.md#update).