Database Settings

Configure database connections, initialization, and migration behavior for RecroGrid Framework applications.

Configure the database connection, migration behavior, and Entity Framework context used by RecroGrid Framework applications.

BaseDbContext and connection selection

By default, RecroGrid Framework generates a BaseDbContext class and uses it for database operations.

It is recommended to derive the generated BaseDbContext from your own application DbContext when you want the RecroGrid Framework integration to live inside the application's wider data model.

Database initialization is required for RecroGrid Framework operation even when your custom database model is still minimal.

Configure connection strings

Add the connection strings and the default connection name to the application configuration.

"ConnectionStrings": {
  "SQLServer": "Server=(localdb)\\mssqllocaldb;Database=DATABASE_NAME;Trusted_Connection=True;MultipleActiveResultSets=false",
  "PostgreSQL": "Host=SERVER_NAME;Database=DATABASE_NAME;Username=USER_NAME;Password=PASSWORD;Command Timeout=15",
  "Oracle26": "Data Source=Oracle26ai:1521/free;User Id=C##USER_NAME;Password=PASSWORD"
}

"Recrovit": {
  "RecroGridFramework": {
    "DefaultConnectionName": "SQLServer",
    "AutoMigrateRGFDatabase": true
  }
}

Initialize and migrate the database

Set AutoMigrateRGFDatabase to true to use the recommended automatic migration workflow.

When the application starts, RecroGrid Framework automatically applies the Entity Framework Core migrations required by the framework database model. This keeps the RecroGrid Framework database structure aligned with the application version and also initializes the required framework database objects on the first startup.

The same startup workflow applies newly introduced migrations after RecroGrid Framework package updates, so database evolution remains integrated with the application lifecycle.

The current Blazor application model does not expose a database migration command through the Blazor UI. With AutoMigrateRGFDatabase: true, no migration bootstrap step is required because database initialization and subsequent RecroGrid Framework migrations are handled automatically during application startup.

Manual initialization and SingleUserMode

Before automatic database migration was available, a new RecroGrid Framework database had to be initialized manually through the built-in API-side /RGF/Admin administration interface. At that point no RecroSec administrator existed yet, so SingleUserMode: true could be used to allow the migration to be started without first establishing normal administrator permissions or obtaining an Access Token.

For environments where database initialization is intentionally performed manually, disable automatic migration and enable SingleUser mode for the initialization session:

"Recrovit": {
  "RecroGridFramework": {
    "AutoMigrateRGFDatabase": false
  },
  "RecroSec": {
    "SingleUserMode": true
  }
}

After the database and normal administrator access are configured, return SingleUserMode to false so the regular RecroSec permission rules apply.

SingleUserMode is not a database migration setting. It changes RecroSec authorization behavior by considering permission checks successful. This also remains useful in local development for direct RecroGrid Framework API testing without obtaining an Access Token, for example when sending requests from Postman or another API client.

Caution

SingleUserMode is intended exclusively for development environments. When enabled, RecroGrid Framework API requests use a shared single-user security context, so every process that can reach the API can operate through that context. Expose the API exclusively through localhost while SingleUserMode is enabled.

The recommended workflow for current Blazor applications is automatic migration with AutoMigrateRGFDatabase: true. The AutoMigrateRGFDatabase: false setting can also be used when database migrations are managed by the application's deployment or migration process.

Custom DbContext

If the generated BaseDbContext should not be used directly, disable its generation and register your own DbContext instead.

<PropertyGroup>
  <RGFBaseDbContext>false</RGFBaseDbContext>
  <RGFCustomSql>false</RGFCustomSql>
</PropertyGroup>

builder.Services.AddDbContext<YourDbContext>(options =>
    options.UseSqlServer(RGDataContext.DefaultConnectionString));

app.UseRGF<YourDbContext>();