You are reading the documentation for an outdated Corteza release. 2023.9 is the latest stable Corteza release.

DAL Connections

DAL connections (also referred to as connections) define a location where Corteza can store and retrieve the data. A connection outlines the physical location of the data storage, describes its properties (such as encoding and recovery) and provides connection parameters.

Currently, only connections to the following RDBMS databases are supported:
  • MySQL,

  • PostgreSQL,

  • SQLite.

You can define as many connections as you need to help your business conform to data privacy regulations, offload specific datasets to specialized databases, and easily integrate external data.

You can connect to databases with already existing data, removing the need to migrate it over to Corteza.

The connection management interface is available in the Corteza Admin under the system  connections section

Annotated image

Connection Types

Primary connection

The primary connection is the default connection the Corteza uses to store records and is the same as the DB_DSN defined in your .env file. The primary connection is defined when provisioning a fresh Corteza instance or upgrading from an older release.

Primary connections only partially support modification and block any change which would change its identification or underlying storage connection.

External connection

The administrator adds external connections that can be used as an alternative to the primary connection.

Modifying connection parameters may lead to data loss issues when Corteza can no longer connect to the original storage location.

Connection Configuration

Basic Settings

Basic settings provide the general outline of the connection, such as its identification, physical location, ownership, and data sensitivity levels. Data sensitivity levels are discussed in the data privacy sections.

DevNote link to the data privacy section

Annotated image


The name specifies a user-friendly label for this connection. The name is used when displaying connections on the user interfaces, such as the map on the privacy console.


The handle specifies a user-friendly identifier used by the system. The handle, in some cases, can be used instead of the ID to identify the connection uniquely.

The handle implies the same constraints as any other handle.

  1. start with a character,

  2. contain at most 64 characters,

  3. contain only characters, numbers, _ (underscore), - (dash) or . (dot),

  4. end with a character or a number.

Location name

The location name specifies the physical location of where the data is located. The location name can be the name of the data centre, the region, or the continent.

Location coordinates

The location coordinates provide the exact location of where the data is located. The connection is plotted on the map in the data privacy console when the coordinates are provided.


The ownership specifies who owns the data or the data centre where the data is stored. The ownership can come in handy if you’re offloading your database management needs to external service providers.

Highest allowed sensitivity level

The highest allowed sensitivity level specifies the upper limit of what can be stored in the given connection regarding data privacy. Any modules and fields utilizing the connection can not exceed the upper limit.

You can define multiple connections with multiple sensitivity levels to better conform to data privacy regulations worldwide.

Connection Properties

Connection properties provide additional information regarding the database or data centre. The connection properties primarily focus on data encryption and restoration.

Connection properties outline the underlying storage we’re connecting to. These properties do not configure Corteza to perform anything outlined by the properties.

Annotated image

Encrypt data at rest enabled

Data at rest encryption indicates the data is encrypted when stored in the data centre. Data encryption at rest helps mitigate damages in case of a breach.

Annotated image

Data at rest protection provided

Data at rest protection indicates that the data is physically protected from unauthorised access when stored in the data centre. Data protection helps reduce the chance of a data breach.

Annotated image

Encrypt data at transit enabled

Data at transit encryption indicates the data when transported between systems, is encrypted. Data encryption at transit helps mitigate the risks of wiretapping attacks.

Annotated image

Data at rest backup and restoration implemented

Data at rest backup and restoration indicates the data is backed up and can be restored in case of system failures and disasters.

Annotated image

Connection Parameters

Connection parameters provide the parameters needed for Corteza’s DAL to connect to the underlying storage.

Connection parameters define how Corteza should interact with the underlying storage. Connection parameters also define some default values in regard to the internals of the storage driver, such as default table or collection identifier.

Annotated image

Default table or container name

The default table or container name specifies where Corteza should store the records inside of the connection. In the context of RDBMS, the identifier would specify what table Corteza should use.

The identifier input supports value placeholders which help reduce the required configuration for larger instances.

You can use the following placeholders:
  • {{module}}: the {{module}} placeholder is replaced with the module’s handle or the ID if the handle is not defined.

  • {{namespace}}: the {{namespace}} placeholder is replaced with the namespace’s slug or the ID if the slug is not defined.

To exemplify; the following identifier compose_records_{{namespace}}_{{module}} could produce the identifier of compose_records_crm_lead.

Connection and parameter type

The connection and parameter type specify how we’ll provide the connection parameters and, consequentially, the underlying storage driver type. Refer to the connection parameter types section for a complete overview of available options and their input formatting.

Connection parameters

The connection parameters specify the connection parameters used by Corteza and depend on the option selected in connection parameter type. Refer to the Connection Types sub-section for details.

Connection Parameter Types


The corteza::dal:connection:dsn connection type specifies we’ll use a DSN string to connect to the database.

  1. You must provide the configuration parameters in the following format:

  "dsn": ""
Currently, Corteza supports the following databases:
  • MySQL

  • PostgreSQL

  • SQLite