Icon Creating and Using Databases

Before using the TDatabase component, you must first create an instance of the component, which you can do at design-time or at run-time. A global TDatabase instance called Database is automatically created at application startup and is used as the default database for any datasets that are created without being specifically associated with a database. Please see the Creating and Loading DataSets topic for more information on how datasets are associated with databases at creation time.

Creating a Database at Design-Time
The easiest way to create a database is by using the Database Manager in the IDE to define a database and its contained datasets. Once a database has been defined under a database in the database manager, you can easily add the database to an existing application by dragging the database from the database manager and dropping it into the project manager for the currently-opened project. When the database is dropped on or within the Units node of the project manager, a new TDatabase (or descendant) instance will be created for the project, along with an associated unit, and all of the defined datasets for the database will automatically be created as TDataSet instances in the new database instance.

At design-time, TDatabase instances act (and are stored) like forms but are actually just containers that allow non-visual components like TDataSet instances to be dropped on to the database designer surface. The database designer only allows for non-visual components to be placed on the designer surface, and the visual size of the database instance in the designer is exclusively a design-time property. Please see the Using the Form and Database Designers topic for more information on how to use the database designer.

Authenticating Requests
You can use the TDatabase UserName and Password properties to specify a user name and password to be used with any database requests to the web server. The TDatabase AuthenticationMethod property controls how the authentication information is sent to the web server.

If the AuthenticationMethod property is set to amHeaders (the default), then the user name and password are added as custom headers to the web server request as follows:

X-EWBUser: <User Name>
X-EWBPassword: <Password>

If the AuthenticationMethod property is set to amParameters, then the user name and password are added as parameters to the web server request as follows:

<Database Resource URL>&user=<User Name>&password=<Password>

Warning Elevate Web Builder uses the AJAX functionality in browsers to perform database requests, and this functionality is limited in its ability to perform authentication via native browser methods. Therefore, you should always use secure connections (https) to the web server with any database requests. This is especially true if using the parameter-based authentication, but is also true if you are using datasets with BLOB columns that will require authentication information in their load URL parameters. Please see the JSON Reference topic for more information on BLOB loading.

Database Request Queue
Each TDatabase instance contains a request queue that is used for all database requests to the web server. Elevate Web Builder automatically handles building and sending all databases requests as the database functionality is used in all TDatabase and TDataSet instances. However, if an error occurs during any database request, the request queue is paused and all queued database requests, including the request that failed, are effectively stalled. You can use the TDatabase NumPendingRequests property to determine how many pending requests are present in the request queue, and the TDatabase RetryPendingRequests and CancelPendingRequests methods to retry or cancel any pending requests in the database request queue.

Please see the Executing a Server Request topic for more information on how web server requests are executed.

By default, each TDatabase instance automatically handles transactions without requiring them to be manually started/committed/rolled back. This behavior is controlled via the TDatabase AutoTransactions property. Please see the Transactions topic for more information on how database transactions work in Elevate Web Builder.

Database Parameters
You can use the TDatabase Params property to specify database-specific parameters that will be passed as URL parameters with all database requests originating from the database. This is useful for situations where you want to tag all database requests with application-specific information, such as session IDs or tokens. The Params property is a string list (TStrings) of "name=value" pairs that represents the database URL parameters.