Class DatabaseBuilder

Supports building and configuring the database.

Inheritance

object

Namespace: Umbraco.Cms.Infrastructure.Migrations.Install

Assembly: Umbraco.Infrastructure.dll

Syntax

public class DatabaseBuilder

Constructors

View Source

DatabaseBuilder(ICoreScopeProvider, IScopeAccessor, IUmbracoDatabaseFactory, IRuntimeState, ILoggerFactory, IKeyValueService, IDbProviderFactoryCreator, IConfigManipulator, IOptionsMonitor<GlobalSettings>, IOptionsMonitor<ConnectionStrings>, IMigrationPlanExecutor, DatabaseSchemaCreatorFactory, IEnumerable<IDatabaseProviderMetadata>, IEventAggregator)

Initializes a new instance of the DatabaseBuilder class.

Declaration

public DatabaseBuilder(ICoreScopeProvider scopeProvider, IScopeAccessor scopeAccessor, IUmbracoDatabaseFactory databaseFactory, IRuntimeState runtimeState, ILoggerFactory loggerFactory, IKeyValueService keyValueService, IDbProviderFactoryCreator dbProviderFactoryCreator, IConfigManipulator configManipulator, IOptionsMonitor<GlobalSettings> globalSettings, IOptionsMonitor<ConnectionStrings> connectionStrings, IMigrationPlanExecutor migrationPlanExecutor, DatabaseSchemaCreatorFactory databaseSchemaCreatorFactory, IEnumerable<IDatabaseProviderMetadata> databaseProviderMetadata, IEventAggregator aggregator)

Parameters

Type	Name	Description
ICoreScopeProvider	scopeProvider	Provides core scoping functionality for database operations.
IScopeAccessor	scopeAccessor	Accesses the current scope context.
IUmbracoDatabaseFactory	databaseFactory	Factory for creating Umbraco database connections.
IRuntimeState	runtimeState	Provides information about the current runtime state of the application.
ILoggerFactory	loggerFactory	Factory for creating logger instances.
IKeyValueService	keyValueService	Service for accessing key-value storage.
IDbProviderFactoryCreator	dbProviderFactoryCreator	Creates database provider factories for different database types.
IConfigManipulator	configManipulator	Handles manipulation of configuration files.
IOptionsMonitor<GlobalSettings>	globalSettings	Monitors and provides global settings options.
IOptionsMonitor<ConnectionStrings>	connectionStrings	Monitors and provides connection string options.
IMigrationPlanExecutor	migrationPlanExecutor	Executes migration plans for database schema changes.
DatabaseSchemaCreatorFactory	databaseSchemaCreatorFactory	Factory for creating database schema creators.
IEnumerable<IDatabaseProviderMetadata>	databaseProviderMetadata	A collection of metadata describing available database providers.
IEventAggregator	aggregator	Aggregates and dispatches events within the system.

Properties

View Source

CanConnectToDatabase

Gets a value indicating whether it is possible to connect to the configured database. It does not necessarily mean that Umbraco is installed, nor up-to-date.

Declaration

public bool CanConnectToDatabase { get; }

Property Value

Type	Description
bool

View Source

IsDatabaseConfigured

Gets a value indicating whether the database is configured. It does not necessarily mean that it is possible to connect, nor that Umbraco is installed, nor up-to-date.

Declaration

public bool IsDatabaseConfigured { get; }

Property Value

Type	Description
bool

Methods

View Source

CanConnect(string?, string)

Determines whether it is possible to connect to a database using the specified connection string and provider.

Declaration

public bool CanConnect(string? connectionString, string providerName)

Parameters

Type	Name	Description
string	connectionString	The connection string to the database.
string	providerName	The name of the database provider.

Returns

Type	Description
bool	True if a connection can be established; otherwise, false.

View Source

ConfigureDatabaseConnection(DatabaseModel, bool)

Configures the database connection using the provided database settings. If databaseSettings is null, attempts a quick install with default settings. Attempts to establish a connection and, if isTrialRun is false, saves the connection string configuration. Throws an InstallException if the database provider configuration cannot be determined or if the configuration update fails.

Declaration

public bool ConfigureDatabaseConnection(DatabaseModel databaseSettings, bool isTrialRun)

Parameters

Type	Name	Description
DatabaseModel	databaseSettings	The database settings model containing connection details, or `null` to use default settings.
bool	isTrialRun	If `true`, performs a trial run without saving the connection string; otherwise, saves the configuration.

Returns

Type	Description
bool	`true` if the connection was successfully configured and tested; otherwise, `false`.

View Source

CreateDatabase()

Creates a new database using the configured database provider and connection string. This method delegates the creation to the underlying database provider factory.

Declaration

public void CreateDatabase()

View Source

CreateSchemaAndData()

Creates the database schema and inserts initial data.

Declaration

public DatabaseBuilder.Result? CreateSchemaAndData()

Returns

Type	Description
DatabaseBuilder.Result	A DatabaseBuilder.Result object indicating whether the operation succeeded, failed, or requires an upgrade. Returns `null` if the operation could not be completed.

Remarks

This assumes that the database exists and the connection string is configured and it is possible to connect to the database.

View Source

HasSomeNonDefaultUser()

Determines whether there is at least one user in the database other than the default super user with the default password.

Declaration

public bool HasSomeNonDefaultUser()

Returns

Type	Description
bool	`true` if there is at least one user who is not the default super user with the default password; otherwise, `false`.

View Source

UpgradeSchemaAndData(MigrationPlan)

Upgrades the database schema and data according to the specified migration plan.

Declaration

[Obsolete("Use UpgradeSchemaAndDataAsync instead. Scheduled for removal in Umbraco 18.")]
public DatabaseBuilder.Result? UpgradeSchemaAndData(MigrationPlan plan)

Parameters

Type	Name	Description
MigrationPlan	plan	The migration plan to apply for upgrading the schema and data.

Returns

Type	Description
DatabaseBuilder.Result	A DatabaseBuilder.Result indicating the outcome of the upgrade operation, or `null` if the upgrade did not produce a result.

Remarks

This method is obsolete. Use UpgradeSchemaAndDataAsync(UmbracoPlan) instead. Scheduled for removal in Umbraco 18.

View Source

UpgradeSchemaAndData(UmbracoPlan)

Upgrades the database schema and data using the specified Umbraco plan.

Declaration

[Obsolete("Use UpgradeSchemaAndDataAsync instead. Scheduled for removal in Umbraco 18.")]
public DatabaseBuilder.Result? UpgradeSchemaAndData(UmbracoPlan plan)

Parameters

Type	Name	Description
UmbracoPlan	plan	The Umbraco plan describing the upgrade steps.

Returns

Type	Description
DatabaseBuilder.Result	A DatabaseBuilder.Result indicating the outcome of the upgrade, or `null` if no result is available.

Remarks

This method is obsolete. Use UpgradeSchemaAndDataAsync(UmbracoPlan) instead.

View Source

UpgradeSchemaAndDataAsync(MigrationPlan)

Upgrades the database schema and data by running migrations.

Declaration

public Task<DatabaseBuilder.Result?> UpgradeSchemaAndDataAsync(MigrationPlan plan)

Parameters

Type	Name	Description
MigrationPlan	plan

Returns

Type	Description
Task<DatabaseBuilder.Result>

Remarks

This assumes that the database exists and the connection string is configured and it is possible to connect to the database.

Runs whichever migrations need to run.

View Source

UpgradeSchemaAndDataAsync(UmbracoPlan)

Asynchronously upgrades the database schema and data based on the specified UmbracoPlan.

Declaration

public Task<DatabaseBuilder.Result?> UpgradeSchemaAndDataAsync(UmbracoPlan plan)

Parameters

Type	Name	Description
UmbracoPlan	plan	The UmbracoPlan that defines the migration steps to apply.

Returns

Type	Description
Task<DatabaseBuilder.Result>	A System.Threading.Tasks.Task<TResult> representing the asynchronous operation, containing the DatabaseBuilder.Result of the upgrade if successful; otherwise, `null` if no upgrade was performed.

View Source

ValidateDatabaseConnectionAsync(DatabaseModel)

Asynchronously validates the ability to connect to a database using the specified settings.

Declaration

public Task<Attempt<InstallOperationStatus>> ValidateDatabaseConnectionAsync(DatabaseModel databaseSettings)

Parameters

Type	Name	Description
DatabaseModel	databaseSettings	The database settings to use for validation.

Returns

Type	Description
Task<Attempt<InstallOperationStatus>>	A task that represents the asynchronous operation. The task result contains an Attempt<TResult> indicating the outcome of the validation, such as success, unknown provider, missing connection string, missing provider name, or connection failure.

View Source

ValidateSchema()

Validates the database schema.

Declaration

public DatabaseSchemaResult? ValidateSchema()

Returns

Type	Description
DatabaseSchemaResult	A DatabaseSchemaResult containing the result of the schema validation, or `null` if validation could not be performed.

Remarks

This assumes that the database exists, the connection string is configured, and a connection to the database can be established.