Windows-based Hosting::CreateCustomerDatabase

  • Article

The CreateCustomerDatabase procedure creates a database for a specified customer and optionally creates a customer directory structure on a specified share for data (mdf) and log (ldf) file. The size of the database is retrieved from the Customer Service Plans database and is based on customer's plan. The size is then applied to set the dataFile size (total allowed by plan is 1 mg for logFile).

Arguments

The CreateCustomerDatabase procedure has the following input parameters.

Input Argument Description

<org>

The Lightweight Directory Access Protocol (LDAP) path of the owning organization.

<databaseName>

The name of the database to be created.

<dataRootShare>

The name of the share (not the full path) where customer data (mdf) and logfiles (ldf) are stored. The full UNC path is constructed from the share name and the server name returned by Resource Manager.

This path must be accessible via the MPF server and the account that is submitting this request must have permissions to create directories on that share (e.g. \\SQL01\customerData$). The share must exist on all servers managed by Resource Manager.

<dataRootShare>/@serviceAcct

This attribute is the sAMAccountName of the service account that the SQL server runs as. This is required to provide file permission rights to the account for the customer's data and log files.

<dataRootPath>

The local path to the root directory where customer data (mdf) and logfiles are store (ldf). dataRootShare has to be passed if dataRootPath is being passed. Note that dataFile and logFile parameters will be ignored if you do not provide the dataRootShare and dataRootPath parameters.

<algorithm>

Defines the server candidate selection behavior. The allowed values (case sensitive) are:

  • tightPack - From the set of servers that can satisfy the capacity of an allocation, the servers are ranked favoring those with the least amount of free space.

  • level - From the set of servers that can satisfy the capacity of an allocation, the servers are ranked favoring those with the most amount of free space.

  • minSeverCount - From the set of servers that can satisfy the capacity of an allocation, servers are selected where the organization has already had databases allocated. If no appropriate servers are found meeting this criteria, then the procedure falls back to a "tightPack" algorithm or the algorithm specified in the @alternate optional parameter.

<preferredDomainController>

The name of the preferred domain controller.

<megabytes>

The size to be allocated to the resource.

<serverName>

A string representing the name of the server. This can be a NetBIOS name, a fully qualified domain name (FQDN), or an IP address. Overrides automatic selection behavior. However the specified server is still evaluated to see if it has been added to Resource Manager, whether it has the necessary resources to satisfy the request, and if it is a member of the specified server class.

<sqlUserName>

The user name for connecting to the SQL server via SQL Authentication. If this node is present, the connection will be made via SQL Authentication rather than Windows Authentication. The existence of this node also requires that the <sqlUserPass/> node exist.

<sqlUserPass>

The password for connecting to the SQL server via SQL Authentication, using the username indicated by <sqlUserName/>. If the <sqlUserName/> node is not present, this node is ignored.

<algorithm>/@alternate

Defines the alternate algorithm behavior if the minServerCount algorithm fails to find a candidate server. If provided, this alternate will be used to select the server candidate. If not provided, the procedure will default to a "tightPack" alternate. This optional attribute is ignored for all algorithm values except "minServerCount."

<dataFile>/<logicalName>

The logical name for the file. If you intend to supply any of the optional dataFile parameters, you must set the logical name of the data file.

<dataFile>/<fileGrowth>

Designates a growth increment in KB, MB, GB, terabyte, or percentage (you must specify the unit). The default is 10 percent and the minimum value is 64 KB. Requires that the dataFile/logicalName node exist and be non-null.

<logFile>/<logicalName>

The logical name for the file. If no log file is specified, a single log file is created with a system-generated name and size that is 25 percent of total data file size. If you intend to supply any of the optional logFile parameters, you must set the logical name of the data file.

<logFile>/<fileGrowth>

Designates a growth increment in KB, MB, GB, terabyte, or percentage (you must specify the unit). The default is 10 percent and the minimum value is 64 KB. Requires that the logFile/logicalName node exist and be non-null.

The CreateCustomerDatabase procedure returns the following output parameters.

Ouput Argument Description

<dataFile>/<filePath>

The operating system file name (full path).

<logFile>/<filePath>

The operating system file name (full path).

<serverName>

The server name on which the database was created.

Remarks

Security

The CreateCustomerDatabase procedure has the following security requirements:

  • The caller is impersonated.

  • The caller is tested for OrgCreator permissions.

Process Steps

The following steps occur when creating a customer database with the CreateCustomerDatabase procedure of the Managed Windows-based Hosting Namespace:

  • Validate service plan to permit database provisioning for this customer.

  • Allocate resources from the resource pool.

  • Create the customer's root directory and set its permissions by calling Managed Data Hosting::CreateCustomerDatabase.

  • Create the sqldata files folder and set its permissions.

  • Create the database and apply any optional settings.

  • Add a login to the database for the admins@<org> group.

  • Add the login to the dbo role for that database.

  • Update Resource Manager allocations.

Sample Code

Example XML Request

The following is an example of an XML request for the CreateCustomerDatabase procedure of the Managed Windows-based Hosting Namespace:

<request> 
        <procedure> 
                <execute namespace="Windows-based Hosting"  
                procedure="CreateCustomerDatabase" impersonate="1"> 
                        <executeData> 
                        <org>LDAP://OU=northwindtraders,OU=consolidatedmessenger, 
                        OU=Hosting,DC=fabrikam,DC=Com</org> 
                        <databaseName>NorthWindSales</databaseName> 
                        <dataRootShareNameserviceAcct="fabrikam\SQLService"> 
                        customerData$</dataRootShareName> 
                        <dataRootPath>c:\customerData</dataRootPath> 
                        <preferredDomainController>AD01.fabrikam.Com 
                        </preferredDomainController> 
                        <megabytes>100</megabytes> 
                        </executeData> 
                        <after source="executeData" destination="data" mode="merge"/> 
                </execute>   
        </procedure> 
</request>

Applies To

Managed Windows-based Hosting Namespace API for:

  • Hosted Messaging and Collaboration version 3.5

  • Hosted Messaging and Collaboration version 3.0

  • Windows-based Hosting version 4.5

  • Windows-based Hosting version 4.0

  • Windows-based Hosting version 3.5

  • Windows-based Hosting for Applications version 1.0

See also

Tasks

Windows-based Hosting::DeleteCustomerDatabase