Initialize-DeploymentEnvironment

Owned by Stephen Fuqua
Last updated: Feb 17, 2022 by Eric Stockdale (Deactivated)
4 min read

Description

Deploy the databases necessary to run the Ed-Fi ODS/API. Part of the the EdFi.RestApi.Databases package (NuGet packages or source code in Ed-Fi-ODS-Implementation/scripts/nuget). Configuration depends on a combination of the input arguments as well as the settings in two config files:

  • databases.config  in the same location as Deployment.psm1 .
  • EdFi.Ods.BulkLoad.Console.exe.config in directory Ed-Fi-ODS-Implementation\logistics\bin\EdFi.Ods.BulkLoad.Console.
    • (warning) This file is no longer used starting with ODS/API 3.4.0. The minimal template is now installed via a database backup file, just like the populated template.

Configuration

  • To change database servers, default databases names, or connection credentials, simply update the relevant connection strings in the config file(s).
  • When changing the database name, be sure to retain the token "{0}". Each installation mode uses this token differently. For example, if the connection string contains "EdFi_3.3_{0}" in it, then:
    • SharedInstance deploy creates ODS databases named "EdFi_3.3_Ods", "EdFi_3.3_Ods_Bulk1", and "EdFi_3.3_Ods_Empty_Template"
    • YearSpecific deploy creates ODS databases named "EdFi_3.3_Ods_2020" (or whatever year(s) specified in the PowerShell command), "EdFi_3.3_Ods_Bulk1", and "EdFi_3.3_Ods_Empty_Template"
    • Sandbox deploy creates ODS databases named "EdFi_3.3_Ods_Bulk1", "EdFi_3.3_Ods_Empty_Template", "EdFi_3.3_Ods_Minimal_Template", and "EdFi_3.3_Ods_Populated_Template".


Sample Databases.config File
<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <connectionStrings>
    <add name="EdFi_Ods" connectionString="Database=EdFi_{0}; Data Source=(local); Trusted_Connection=True;" providerName="System.Data.SqlClient" />
    <add name="EdFi_Admin" connectionString="Database=EdFi_Admin; Data Source=(local); Trusted_Connection=True;" providerName="System.Data.SqlClient" />
    <add name="EdFi_Security" connectionString="Database=EdFi_Security; Data Source=(local); Persist Security Info=True; Integrated Security=True;" providerName="System.Data.SqlClient" />
    <add name="EdFi_master" connectionString="Database=master; Data Source=(local); Trusted_Connection=True;" providerName="System.Data.SqlClient" />
    <add name="BulkOperationDbContext" connectionString="Data Source=(local);Initial Catalog=EdFi_Bulk;Trusted_Connection=True;MultipleActiveResultSets=True" providerName="System.Data.SqlClient" />
  </connectionStrings>
  <appSettings>
    <add key="sandbox:populatedTemplateScript" value="GrandBend" />
    <add key="ExcludedExtensionSources" value="" />
    <add key="changeQueries:featureIsEnabled" value="false" />
  </appSettings>
</configuration>

The config file in the NuGet package includes two extra connection string values that are no longer necessary or only used in rare circumstances: EduIdContext  and UniqueIdIntegrationContext. These are omitted from the sample above.

Syntax

Initialize-DeploymentEnvironment [[-PathResolverRepositoryOverride] <String>] [[-InstallType] <String>] [[-Engine] <String>]
[[-ExcludedExtensionSources] <String>] [[-EnabledFeatureNames] <String>] [[-OdsTokens] <String[]>] [[-OdsDatabaseTemplateName]
<String>] [-DropDatabases] [-NoDuration] [-UsePlugins] [<CommonParameters>]

Parameters

Name

Alias

Description

Required?

Pipeline Input

Default Value

PathResolverRepositoryOverride


A semicolon-separated string of repositories to pass to path-resolver, such as 'Ed-Fi-ODS;Ed-Fi-Ods-Implementation'

false

false


InstallType


The type of deployment to install: 'Sandbox', 'SharedInstance' or 'YearSpecific'

false

false


Engine


The database engine provider, either 'SQLServer' or 'PostgreSQL'

false

false


ExcludedExtensionSources


A comma separated string of extensions sources to exclude from database deployment.
Any values specified will be excluded from the resolved extension sources list.
If no sources are passed then any resolved sources found by the artifact source resolver will be used.

false

false


EnabledFeatureNames


Any subtype features specified will be enabled.

false

false


OdsTokens

OdsYears

A semicolon-separated string of tokens to use when creating Ods database instances.
For a year specific deployment a valid value could be '2013;2014;2015;2016;2017'.
For a district specific deployment a valid value could be '255901;255902'.

false

false


OdsDatabaseTemplateName


Template to use when deploying Ods database. Allowed values: minimal, populated. Defaults to minimal.

false

false


DropDatabases

Transient


false

false

False

NoDuration


Turn off duration display

false

false

False

UsePlugins


Runs database scripts from downloaded plugin extensions in addition to extensions found in the Ed-Fi-Ods-Implementation

false

false

False

Examples

Sandbox

Import-Module .\Deployment.psm1
Initialize-DeploymentEnvironment `
	-PathResolverRepositoryOverride “Ed-Fi-Common;Ed-Fi-ODS;Ed-Fi-ODS-Implementation”

Shared Instance, with Change Queries

Import-Module .\Deployment.psm1
Initialize-DeploymentEnvironment `
	-InstallType SharedInstance `
	-PathResolverRepositoryOverride “Ed-Fi-Common;Ed-Fi-ODS;Ed-Fi-ODS-Implementation” `
	-EnabledFeatureNames Changes

Shared Instance, Without GrandBend Extension

Import-Module .\Deployment.psm1
Initialize-DeploymentEnvironment `
	-InstallType SharedInstance `
	-PathResolverRepositoryOverride “Ed-Fi-Common;Ed-Fi-ODS;Ed-Fi-ODS-Implementation” `
	-ExcludedExtensionSources GrandBend

Year Specific for 2019 and 2020

Import-Module .\Deployment.psm1
Initialize-DeploymentEnvironment `
	-InstallType YearSpecific `
    -OdsYears "2019;2020"
	-PathResolverRepositoryOverride “Ed-Fi-Common;Ed-Fi-ODS;Ed-Fi-ODS-Implementation”

Sandbox, using Glendale Database, Excluding Extensions, with Alternate Server and Database Names

In the config files below, notice that the database names have "_3.3" appended to them (for ODS/API 3.3.0), and the server has been changed from "(local)" to a named instance "localhost\second". The "sandbox:populatedTemplateScript" app setting was changed from "GrandBend" to "Glendale". 

Config Files

databases.config
<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <connectionStrings>
    <add name="EdFi_Ods" connectionString="Database=EdFi_{0}_3.3; Data Source=localhost\second; Trusted_Connection=True;" providerName="System.Data.SqlClient" />
    <add name="EdFi_Admin" connectionString="Database=EdFi_Admin_3.3; Data Source=localhost\second; Trusted_Connection=True;" providerName="System.Data.SqlClient" />
    <add name="EdFi_Security" connectionString="Database=EdFi_Security_3.3; Data Source=localhost\second; Persist Security Info=True; Integrated Security=True;" providerName="System.Data.SqlClient" />
    <add name="EdFi_master" connectionString="Database=master; Data Source=localhost\second; Trusted_Connection=True;" providerName="System.Data.SqlClient" />
    <add name="BulkOperationDbContext" connectionString="Data Source=localhost\second;Initial Catalog=EdFi_Bulk_3.3;Trusted_Connection=True;MultipleActiveResultSets=True" providerName="System.Data.SqlClient" />
  </connectionStrings>
  <appSettings>
    <add key="sandbox:populatedTemplateScript" value="Glendale" />
    <add key="ExcludedExtensionSources" value="" />
    <add key="changeQueries:featureIsEnabled" value="false" />
  </appSettings>
</configuration>

For ODS/API versions up to and including 3.3.0, the EdFi.Ods.BulkLoad.Console.exe.config file needs to be modified. This is not necessary for ODS/API 3.4 and beyond.

Partial EdFi.Ods.BulkLoad.Console.exe.config File
...
  <connectionStrings>
    <!--Clear is needed because there is always a SQLExpress default connection.-->
    <clear />
    <add name="EdFi_Ods" connectionString="Database=EdFi_Ods_3.3_Empty_Template; Data Source=localhost\second; Persist Security Info=True; Trusted_Connection=True;Connection Timeout=120" providerName="System.Data.SqlClient" />
    <add name="EdFi_Admin" connectionString="Database=EdFi_Admin_3.3; Data Source=localhost\second; Trusted_Connection=True;" providerName="System.Data.SqlClient" />
    <add name="EdFi_Ods_Bulk" connectionString="Database=EdFi_{0}_3.3; Data Source=localhost\second; Persist Security Info=True; Trusted_Connection=True;Connection Timeout=120" providerName="System.Data.SqlClient" />
    <add name="BulkOperationDbContext" connectionString="Data Source=localhost\second;Initial Catalog=EdFi_Bulk_3.3;Trusted_Connection=True;MultipleActiveResultSets=True" providerName="System.Data.SqlClient" />
    <add name="EdFi_Security" connectionString="Data Source=localhost\second;Initial Catalog=EdFi_Security_3.3;Integrated Security=True" providerName="System.Data.SqlClient" />
    <add name="NHibernatePlaceholder" connectionString="PLACEHOLDER-Required-but-Ignored-By-EdFiOdsConnectionProvider" />
  </connectionStrings>
...

PowerShell Command

Import-Module .\Deployment.psm1
Initialize-DeploymentEnvironment `
	-InstallType Sandbox `
	-PathResolverRepositoryOverride “Ed-Fi-Common;Ed-Fi-ODS;Ed-Fi-ODS-Implementation” `
	-ExcludedExtensionSources "GrandBend,Sample,Homograph"

Output

Databases

No extension tables