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 server manager in the IDE to define a database and its contained datasets. Once a database has been defined in the server manager, you can easily add the database to an existing client or server application project by dragging and dropping the database on to the tab gutter of the work area in the IDE:



When the database is dropped on the tab gutter of the work area, a new TDatabase (or descendant) instance will be created for the project, along with an associated source unit, and all of the defined datasets for the database will automatically be created as TDataSet instances in the new database instance. Please see the Using the Server Manager topic for more information.

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 Designer topic for more information on how to use the designer.

Database Authentication

---

Each TDatabase component instance in a client application has a ServerSession property that refers to a TServerSession component instance and provides a way for the TDatabase instance to authenticate the client application/user before attempting to execute any database access requests. This singleton instance of the TServerSession component is automatically associated with any TDatabase component instances that do not contain an explicit TServerSession component instance reference. You can use the TDatabase ActiveServerSession property to determine the actual TServerSession instance being used by the database for authentication.


Database Request Queue

---

Each TDatabase instance in a client application contains a server request queue that is used for all database access requests to the web server. The TDatabase component automatically handles building and sending all database requests as the database access functionality is used in the client application. However, if an error occurs during any database request, the request queue is paused and all queued database access 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.

If a session expires on the web server, an HTTP 403 error will be returned for any database access requests from the client application using the web server session. The TDatabase component will handle re-authentication and the estabishment of a new session, along with retrying the database access request, without any application intervention being required. Authentication is performed in client applications using an out-of-band server request that is separate from the request queue used for normal database access requests.


Transactions

---

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.

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. The Params property is a string list (TStrings) of "name=value" pairs that represents the database URL parameters.