OutSystems Platform allows your applications to access data of an external database.

To work with data of an external database in your application, you need to follow these steps:

  1. Define a connection to the external database;
  2. Use an extension module to define entities for tables or views in the external database;
  3. Configure your extension to use the database connection;
  4. In your application, add a dependency to the extension;
  5. Use the entities of the extension as any other entity.

For a list of supported database engines using this procedure, see the System Requirements.


In our Sales app we would like to list Order records with the Customer and Product information, and allow users to modify them. The data is stored in the 'customer', 'order' and 'product' tables of an external database called 'salesdb'.

Define the Database Connection

In the environment management console, under Administration - Database Connection, set up a new database connection to your external database. Call it 'SalesDB Connection'.

The user defined in this database connection determines the privileges of access to the data, namely the ability to read, create, update or delete data.

Map Database Tables to Entities

In the application add a new extension module, name it 'SalesDB_Connector', and define the entities based on the database tables:

  1. Right-click on the Entities folder and choose 'Connect to External Table or View...';
  2. Follow the steps in the interface to connect to the 'customer', 'order' and 'product' tables;
  3. Make sure you choose 'SalesDB Connection' and 'salesdb' when you are prompted to select database connection and database;
  4. In the Logical Database Name field, type 'Logical SalesDB'.

As result, the 'customer', 'order' and 'product' entities are defined in the extension.

Click the '1-Click Publish' button to publish it.

Configure the Extension to Use a Database Connection

After publishing the extension, can configure the database connection that will be used by the logical database you defined earlier. This setting enables you to change easily which database connection the extension uses.

Click 'Configure', and in the environment management console, select the 'SalesDB Connection' to be used by the extension.

Use the Extension in Your App

In your app, add a dependency on the extension module. Learn how to add dependencies.

Now we can create the screens that list and modify order records.

Select the Database Connection at Runtime

In some cases you need to select the database based on run-time data. Typically the applicable databases share the same schema, but they have different data.

In these scenarios you can use the 'DatabaseConnection_SetConnectionStringForSession' action of the PlatformRuntime API.

See Also

Use Foreign Entities