This is documentation for Apprenda 7 and 8.
Documentation for older versions are also available.

Data Tier Plugin

Platform version 8.2.0 introduces the ability for developers to use any ORM software to configure the data tier of an application using a Data Tier Plugin. The Platform now supports popular .NET ORM software like Microsoft’s Entity Framework Code First Migrations for use in guest applications.

Data Tier Plugin Requirements

Before you can start using Data Tier plugins in your applications, you must have a Platform Operator configure your Platform to allow them.

Data Tier plugins are supported on the following application types

  • Single tenant and multi-tenant applications
  • SQL Server databases
  • All supported Platform workloads, including .NET, Java, Kubernetes Pods, and Docker workloads

Support Limitations

  • While multi-tenant applications are supported, shared tables and provider views are not supported
  • Commingled databases are not supported. The Data Tier plugin model will only work for isolated databases.
  • Oracle Database Servers are not supported
  • If you are using Entity Framework Core First Migrations, “first-touch” application updates are not supported. Your application must be configured when the callback methods are executed because the Platform only supports explicit upgrades. This is necessary for security reasons and for safeguarding the elevated credentials

Implementing a Data Tier Plugin for an Application

If you choose to use a Data Tier plugin as your database provisioning strategy, you must implement the callback method interfaces and include your callback method implementations in the application archive as an assembly.

Data Tier Plugin Example Application

A example utilizing the Entity Framework Code First Migrations and walking you through multiple versions of an application is located at https://github.com/apprenda/ApplicationSamples.

Prerequisites

Callback Methods

To use Entity Framework or other ORM software, create an interface that implements the callback methods for the Data Tier plugin. The interface, an Abstract Class, includes methods that receive a callback during provisioning, patching, and rollback actions. Each of these methods are called at specific times in the different workflows that the Platform executes during lifecycle operations of an application.

  • Provision gets called during the initial provisioning of an application database for the first version of an application, during Sandbox Lifecycle stage deployments, and for onboarding a new tenant to any version.
  • Patch gets called when you patch an application in the Published Lifecycle stage to a new version. Depending on configuration options set by the Platform Operator, the Platform will make a full backup of the database prior to executing the callback method. The backup is available if there are errors during patching.
  • Rollback gets called when the Patch callback method throws an exception, fails to execute, or exceeds the allotted time (times out). The application developer is responsible for implementing the Rollback method accurately for the specific version of their application to prevent data loss. The Rollback method is optional and the developer does not have to implement it.

Callback Operations

During a callback, each method receives relevant information that a developer can use to stand up the data tier. This information is in the PersistenceMigratorRequest class, and it includes information like application alias, version alias, tenant alias, lifecycle stage information, and connection information to the database deployed by the Platform.

The Platform provides a user account along with the rest of the connection information that has elevated permissions to create and patch a database. For security reasons, the elevated permissions are only granted for the duration of the callback.

The developer can use the method implementation to call any ORM or external executable using the data provided by the Platform. Its recommended that developers define and implement the database model in code once and reuse it in the callback operations. Method callbacks are always executed using an Active Directory account configured by the Platform Operator. Note that all the required callback methods can only be implemented exactly once.

public class PersistenceMigratorRequest
{
    public PersistenceMigratorRequest();

    public NameAlias Application { get; set; }
    public VersionInfo Version { get; set; }
    public VersionInfo PreviousVersion { get; set; }
    public NameAlias Tenant { get; set; }
    public ConnectionInformation ConnectionInformation { get; set; }
}
public class ConnectionInformation
{
    public ConnectionInformation();

    public DbType Type { get; set; }
    public DbAuthType AuthenticationType { get; set; }
    public string Server { get; set; }
    public string ServiceName { get; set; }
    public int? Port { get; set; }
    public string DatabaseName { get; set; }
    public string Username { get; set; }
    public string Password { get; set; }
}

Apprenda Application Archive Structure for the Data Tier Plugin

To use the Data Tier plugin, developers should implement the required callback methods and build their code into assemblies. The Platform will scan all the assemblies when an application archive is uploaded and identify the implementation of the Data Tier plugin interface. If your Data Tier plugin requires .NET app-config files functionality, you may include exactly one "*.config" file in the plugin folder. This file will be loaded as the app.config for the application.

Include the assemblies of your callback methods in the “\persistence\custom” folder of the Apprenda Application Archive.

The “\persistence\custom” folder can optionally contain additional binaries needed by the callback methods, or any executables that will be spawned as separate processes during a callback.

Patching

If you are patching an application to version 2 or later, even if there are no database changes, you need to continue implementing the Data Tier plugin callbacks. For single tenant applications, you can leave the implementation empty and return immediately if you do not have an database changes. Multi-tenant apps must still be able to onboard (ie provision) new tenants.

If Patching Fails using the Data Tier Plugin

If a patch of your application fails, depending on how your application and callback methods are configured, the Platform will treat the failure in the following ways.

If a patch fails and a rollback method is not implemented, the Platform will place the application in maintenance. A developer must manually fix the database patch issue and restore the application to healthy.

If a rollback method is implemented, but it fails and throws an exception, the Platform will place the application in maintenance. A developer must manually fix the database patch issue and restore the application to healthy.

If you are patching an application from version X to version Y and patching and rollback fails, your application binaries are reverted to version X. The database will be in an unknown state after the attempted patching of the database from the schema of X to the schema of Y. Once you fix the issue and the database is consistent, you can use the Developer Portal to restore the application to healthy, in this case restoring it to version X. You can then re-attempt to patch to version Y using the updated plugin code.

If you are patching an application from version X to version Y and the patching fails but the rollback method succeeds, your application will be in the healthy state of version X.

Data Tier Plugin Platform Operator Configuration

Data Plugin Account

Before you can use a Data Tier plugin for guest application databases, a Platform Operator must define an Active Directory account to serve as the process owner when plugin callbacks are executed.

This is a global account that is used for all applications and is defined in the Platform Registry using the following settings:

  • PersistenceMigrationPlugin.AccountDomain is the domain name of the Active Directory account
  • PersistenceMigrationPlugin.AccountUsername is the username of the Active Directory account
  • PersistenceMigrationPlugin.AccountPassword is the password of the Active Directory account

The Platform will temporarily grant the Data Tier plugin account access to SQL Server Databases that are configured for Windows Authentication only. This is a required step for configuring those databases.

Platform Operators can control the full local and remote permissions of the account, potentially granting the account the privilege to create new processes and invoke additional scripts.

Data Back-up

Platform Operators can manage if back-ups are created by the Platform during a Data Tier plugin patching operation using the PersistenceMigrationPlugin.BackupPriorToPatching registry setting. If set to True (default), the Platform will take a backup of the database prior to a patch operation. The Platform will not manage the retention of back-ups after they are created.

If back-ups are kept, Platform Operators can also manage name conventions for data back ups taken and the timeout.

  • PersistenceMigrationPlugin.BackupPrefix: The backup name prefix. The default is “PersistenceAPI-“
  • PersistenceMigrationPlugin.BackupTimeoutMinutes: The time in minutes the Platform will wait for the backup to execute before timing-out. The default is 5 minutes

Additional configuration settings

  • PersistenceMigrationPlugin.ExecutionTimeoutMinutes: The maximum time in minutes the Platform will let any callback run. The default is 10 minutes