Managing database connections

The Connections page lists the database connections of the open project version and provides every action over an existing connection: refreshing its cached schema, editing its parameters, disabling and activating it, and deleting it. The page is opened from the main menu.

Connections list

Column	Description
Connection name	Name set by the user
Database type	PostgreSQL, Microsoft SQL Server, or ClickHouse
Database host	Host address of the database
Database name	Name of the database
Schema name	Schema name. Empty for Microsoft SQL Server and ClickHouse, which do not use a separate schema
Last update	Date and time of the last successful schema refresh
Status	Active, Disabled, or Update error with a colour indicator
Actions	Buttons: update connection, edit connection, activate or disable, delete

The table supports sorting and search by every column: connection name, database type, host, database name, schema name, last update, and status. Search is a case-insensitive substring match. When no sorting is applied, connections are listed in the order they were created. If the version has no connections, the list shows "No connections found".

Above the list there are the Add connection and Update all connections buttons, and the IP address of the application server with a Copy IP address button. That address has to be allowed in the network access settings of the target databases so that they accept incoming connections from the system.

Connection statuses

Status	Meaning
Active (green)	The last check succeeded and the schema metadata is cached. The connection is offered as a data source and is included in automatic schema refreshes
Disabled (red)	The connection has been disabled by a user. It is not offered as a data source and is not refreshed automatically, but it keeps its cached schema
Update error (yellow)	The last attempt to connect or to refresh the schema failed. The connection stays in the list, and the previously cached schema is still used

Cached schema and offline operation

When a connection is created, the system reads the full schema of the external database once — the list of tables and columns with their data types — and stores it as a snapshot. The fact table designer, the data model, and the data mart designer then work from that snapshot instead of querying the database.

The snapshot holds, for every column of every table: the table name, the schema name, the column name, the generalized data type used across the product, and the exact database type with its parameters (for example varchar(255), decimal(10,2), timestamp with time zone).

This has the following consequences:

Analytical objects can be designed and edited while the source database is temporarily unavailable
The source database receives no metadata queries when the interface is opened
Work with metadata does not depend on the network latency or the response time of the source

The external database is contacted only in these cases:

a connection check started by the user
a schema refresh, whether started by the user or performed automatically
execution of a data mart query when the result is requested
creation, update, or removal of materialized data mart objects in that database

Because the interface works from the snapshot, changes made in the source database become visible only after the schema is refreshed.

Refreshing the cached schema

Action	Description
Update connection	The button in the connection row refreshes the schema of that one connection. It is not available for connections in the Disabled status
Update all connections	The button above the list refreshes the schemas of all connections of the open project version that are not disabled. Every connection is processed independently, so one failure does not stop the others

Each refresh reports its result in a separate notification:

success — "{connection name}: Database connection updated successfully". The status becomes Active and Last update is set to the current time
failure — "{connection name}: Failed to update database connection". The status becomes Update error

A failed refresh never deletes the cached snapshot: the previously fetched metadata is kept and continues to be used, so work in the interface goes on with the last successfully read schema. Every refresh is written to the System Journal.

Refresh failures

Situation	Result
The host is unreachable or the network fails	Status Update error, the cached schema is kept and stays in use
The credentials are wrong	Status Update error, an authentication error message
The account has no rights to read the metadata	Status Update error, an insufficient rights message
The certificate is invalid or has expired	Status Update error, an SSL problem message
The database or the schema no longer exists	Status Update error, a message that the resource is unavailable
The database does not answer in time	Status Update error, a timeout message

Editing a connection

The Edit connection button in the connection row opens the same form as connection creation, with the following specifics:

The password is hidden. The password field shows placeholder characters and is read-only. To replace the password, click Edit next to the field — the field is cleared and becomes editable. If the button is not used, the stored password is kept
Only changed fields are sent. Values the user did not touch stay as they are
Certificates. The names of previously uploaded files are shown in read-only fields. A certificate is replaced by uploading a new file, and the old file is then removed from storage
Verify in edit mode checks the connection with the values currently in the form, substituting the stored values for the fields that were not changed
A successful save is reported with "Database connection settings changed successfully". If the connection cannot be established with the new parameters, the same Check connection settings dialog appears as during creation, and the connection can still be saved with the Update error status

When the source database changes

If tables, columns, or data types change in the source database, edit the connection only when its access parameters changed — otherwise it is enough to refresh the schema. In both cases the cached snapshot is replaced by the current state of the database:

Changing any field that affects the connection — host, port, database, schema, user name, password, or SSL — triggers a schema refresh automatically after the connection is saved
New tables and columns become available in the fact table and data mart designers as soon as the refresh finishes
References to tables and columns that no longer exist in the source become invalid. The elements that use them are marked as containing errors, which is shown in the state indicators of the fact tables and data marts built on those elements

Activating and disabling a connection

A connection can be disabled instead of deleted — for example while the source is temporarily unavailable, or when it is being decommissioned. Both actions use the same button in the connection row: Disable for an active connection, Activate for a disabled one.

Disabling a connection:

sets its status to Disabled and reports "Database connection disabled successfully"
excludes it from automatic schema refreshes, and its own refresh button becomes unavailable
removes it from the source selection lists in the RMD, fact table, and data mart forms
keeps its cached schema snapshot

Activating a connection makes the system connect to the database and try to refresh the schema. The final status depends on the outcome:

Outcome	Status	Notification
Connected and the schema was refreshed	Active	"Database connection activated successfully"
The database could not be reached or its schema could not be read	Update error	"Database connection activated in offline mode with existing schema data"

In the second case the connection leaves the Disabled status anyway and keeps its previous schema snapshot, so it can be used offline; refresh it once the database is reachable. If the activation request itself does not go through, the connection stays disabled and the error "Failed to activate database connection" is shown.

Deleting a connection

The delete button in the connection row asks for confirmation — "Are you sure you want to delete the database connection? All the links to this connection will be removed from the project" — and then removes the connection: its cached schema snapshot and its encrypted certificates are deleted from storage together with the connection record. The deletion is written to the System Journal with the state of the connection before it was removed.

What blocks a deletion. A connection cannot be deleted while data marts of the project are still bound to materialized objects in that database. Remove those bindings from the data marts first, then delete the connection.

Consequences of a deletion. The RMD elements whose Connected source pointed at this connection lose that reference. Such elements are marked as containing critical errors, which is shown in the state indicators of the fact tables and data marts that use them. Restoring the reference requires creating a connection again and selecting the source in those elements.

Access permissions

Connection management depends on the user's role in the project. The interface hides the actions a role cannot perform, and the same rules are enforced on the server.

Role	View	Verify	Refresh schema	Activate / disable	Create	Edit	Delete
Super administrator	Yes	Yes	Yes	Yes	Yes	Yes	Yes
Administrator	Yes	Yes	Yes	Yes	Yes	Yes	Yes
Project manager	Yes	Yes	Yes	Yes	Yes	Yes	Yes
Developer	Yes	Yes	Yes	Yes	Yes	Yes	Yes
Analyst	Yes	Yes	Yes	No	No	No	No
Viewer	Yes	No	No	No	No	No	No

Notes:

A Project manager has the rights shown above in the projects they own. In any other project they act at the access level assigned to them in the project members list, which may be Analyst or Viewer
All operations on connections are recorded in the System Journal with the values before and after the change
Every action over a connection also depends on the company license: if the license is missing, invalid, or suspended, the action buttons are hidden and the list stays read-only