Creating a database connection
A database connection stores everything the system needs to reach an external database that holds the source data of the analytics: the database type, the network address, the credentials, and — where the database requires it — SSL certificates. Connections are created and managed on the Connections page, opened from the main menu.
Scope and prerequisites
- A connection belongs to the project version that is open when the connection is created. Every version keeps its own set of connections; when a new version is created, the connections of the parent version are copied into it together with their certificates
- A project must be open — the list shows only the connections of the currently open project version
- The target database must accept incoming connections from the application server. The server IP address is displayed above the connections list together with a Copy IP address button; this address has to be allowed in the network access settings of the target database
- Creating a connection is available to the Super administrator, Administrator, Project manager, and Developer roles. An Analyst can view and verify connections, but cannot create them
Supported database types
| Database type | Schema | SSL | Notes |
|---|---|---|---|
| PostgreSQL | Set explicitly in the Database schema field, public by default |
Not configurable | Full set of data types |
| Microsoft SQL Server | Not entered in the form — the dbo schema is used |
Not configurable | — |
| ClickHouse | Not entered in the form — the database name is used instead | Configured on the SSL tab | TLS encryption with CA and client certificates |
The database type determines which fields the form shows and which checks are performed when the connection is verified. The type can also be changed later, when the connection is edited.
Creating a connection
- Open the Connections page and click Add connection
- Fill in the fields on the Parameters tab (see the table below)
- For a ClickHouse connection, open the SSL tab and, if the server requires TLS, select Use SSL and upload the certificate files. For the other database types the tab is not available
- Click Verify to check the parameters before saving
- Click Save
Connection parameters
| Parameter | Required | Description |
|---|---|---|
| Connection name | Yes | 1–64 characters. Latin and Cyrillic letters, digits, spaces, dots, hyphens, and underscores are allowed; the name cannot start with a space, a dot, a hyphen, or an underscore. Must be unique within the project version. The name is checked as it is typed, both for a new connection and when a connection is renamed: a message under the field says which rule is broken, and Save stays unavailable until the name is corrected |
| Database type | Yes | PostgreSQL, Microsoft SQL Server, or ClickHouse |
| Database host | Yes | Domain name, IPv4, or IPv6 address of the database server, without a scheme, port, or path |
| Database port | Yes | Integer from 1 to 65535 |
| Database name | Yes | Name of the database to connect to |
| Database schema | Yes, for PostgreSQL | Schema name; public by default. The field is hidden for Microsoft SQL Server and ClickHouse |
| Database user | Yes | Account in the target database. The account needs the rights to read the database metadata and the source tables |
| User password | Yes | Password of that account. It is encrypted before it leaves the browser and is stored encrypted |
Field availability by database type
| Field | PostgreSQL | Microsoft SQL Server | ClickHouse |
|---|---|---|---|
| Connection name | Yes | Yes | Yes |
| Database type | Yes | Yes | Yes |
| Database host | Yes | Yes | Yes |
| Database port | Yes | Yes | Yes |
| Database name | Yes | Yes | Yes |
| Database schema | Yes | No | No |
| Database user | Yes | Yes | Yes |
| User password | Yes | Yes | Yes |
| Use SSL and the certificate fields | No | No | Yes |
SSL certificates
The SSL tab is available for ClickHouse connections only. The certificate fields become active after Use SSL is selected.
| Field | Description |
|---|---|
| Use SSL | Turns on TLS for the connection and activates the certificate fields |
| CA certificate | Root certificate of the certification authority |
| Client certificate | Client certificate for mutual authentication |
| Client private key | Private key matching the client certificate |
Each certificate field has an upload button (Upload) and a Delete button that clears the uploaded file. Requirements for the files:
- Allowed extensions:
.crt,.pem,.cer,.ca-bundle,.bundle - Maximum size of one file: 1 MB. A larger file is rejected with the message "Maximum file size: 1 megabyte"
Uploaded certificates are stored encrypted; only their file names are shown in the form afterwards.
Verifying the connection before saving
The Verify button checks the parameters currently entered in the form. Nothing is created and nothing is stored: the system establishes a temporary connection to the database, and depending on the database type it also confirms that the target object exists.
- PostgreSQL — the specified schema must exist
- Microsoft SQL Server — the specified database must exist
- ClickHouse — the server must answer, and the specified database must exist
A successful check is reported with the notification "Database connection successful". A failed check is reported with the reason (see the messages below).
What happens when the connection is saved
- The form is validated: required fields, value formats, and the uniqueness of the connection name within the version
- The connection record is created, and the SSL certificates, if any, are uploaded to encrypted storage
- The system connects to the database and reads its schema — the list of tables and columns with their data types
- The schema is saved as a cached snapshot, which the fact table, data model, and data mart designers then use without contacting the database again
- On success the connection gets the Active status, the Last update column is filled with the current time, and the notification "Connected to the database successfully" is shown
- If any step fails, the connection is saved with the Update error status
- The event is written to the System Journal together with the connection details: type, host, port, user name, and whether SSL is used
Saving a connection that cannot be established
If the check performed on saving fails, the Check connection settings dialog appears with the text "The connection cannot be established with the current settings. Are you sure you want to save it?" and two buttons:
- Return to settings — closes the dialog and keeps the form open for corrections
- Save anyway — saves the connection with the Update error status; the warning "Database connection saved, but cannot be established" is shown
A connection saved this way stays in the list and can be corrected later by editing it, or refreshed once the database becomes reachable.
Validation and error messages
| Message | Cause |
|---|---|
| "Required field" | The name consists of spaces only |
| "Maximum length: 64 characters" | The name is longer than 64 characters |
| "The name cannot start with a space, a dot, a hyphen or an underscore" | The name does not start with a letter or a digit |
| "Letters, digits, space, dot, hyphen and underscore are allowed" | The name contains a character that is not allowed |
| "Invalid connection name: up to 64 letters, digits, spaces, dots, hyphens and underscores, starting with a letter or a digit" | Saving was refused because the name breaks the naming rules |
| "Connection with this name already exists. Please choose another name" | Another connection of the same project version already uses this name |
| "Invalid host format" | The host does not look like a domain name or an IP address |
| "The host is specified incorrectly: enter a domain name or an IP address without a scheme, port or path" | The host was entered with a scheme, a port, or a path |
| "This host is not allowed as a database address. Contact your administrator if the database is on an internal network." | Outbound connections to this address are not permitted. Which addresses are reachable is set by the administrator in the server configuration |
| "Authentication failed: password is incorrect, or there is no user with such name" | Wrong user name or password |
| "Access denied. Please check your username and password" | The account exists but has no access to the specified database |
| "The database does not exist. Please verify the database name" | There is no database with this name on the server |
| "The specified schema does not exist. Please verify the schema name" | There is no schema with this name in the database (PostgreSQL) |
| "SSL connection error. Please verify your SSL settings and certificates are correct" | The certificates do not match the server, are invalid, or have expired |
| "The connection attempt to the database timed out. Please try again" | The server did not answer in time |
| "Connection could not be established" | The host is unreachable, or the connection was refused |
| "Maximum file size: 1 megabyte" | The selected certificate file is larger than 1 MB |
Notes:
- The password is never stored in plain text: it is encrypted in the browser before it is sent, and encrypted again before it is written to the database
- Certificate files are kept only in encrypted storage; the connection record holds their file names
- Managing existing connections — the list, refreshing the cached schema, activation, editing, and deletion — is described on the next page