Skip to main content
A database configuration is the ClickHouse connection - host, port, database, and credentials - that a project reads and writes data through. Every project needs at least one before it can show traces, dashboards, or any other data.

​
Add a database configuration

Configs live on the project page under the Database configurations tab (/organisation/project/[projectId]?tab=database). /settings/database-config redirects to Organisation.
1

Open Organisation

Select Organisation or Projects from the sidebar under Settings.
2

Open a project

Choose the project that should own the database configuration, then open the Database configurations tab.
3

Add New Config

Click Add New Config and enter Config Name, Environment, Username, Password, Host, Port, Database, and optional Query params. Click Save (or Update when editing).
4

Mark it active

Check the list row to Mark … as the active database config, or choose it from the header Databases switcher. Connectivity is checked after the config becomes active - there is no separate test-connection button on the form.

​
Selection behavior

The active database configuration is scoped to the current user and project - it’s not a global setting, so two people can be looking at different database configurations inside the same project at the same time. Switching projects updates the list of available database configurations to only those that belong to the newly selected project; a configuration created under one project is never selectable from another. If a project has no database configuration yet, OpenLIT guides you through onboarding before showing any data pages.

​
Multiple databases

A project can have multiple database configurations - for example, one per ClickHouse cluster or one per data retention tier. Use multiple configurations when you need to switch between them without changing projects or organisations.

Multiple database guide

Learn more about using multiple ClickHouse database configurations in OpenLIT.

​
Sharing a database configuration

A database configuration can be shared directly with specific teammates by email, independent of broader project membership - each share grants its own edit, delete, and re-share permissions, so you can give someone read-only-equivalent access to a connection without letting them modify or share it further.

​
Frequently asked questions

No. A database configuration belongs to the project it was created in and can’t be selected from a different project - create a new configuration (pointing at the same or a different ClickHouse instance) in each project that needs one.
No. Multiple configurations can point at the same ClickHouse cluster using different database names, or at entirely different clusters - whichever fits your infrastructure.
OpenLIT detects the missing configuration and walks you through adding one before showing any data pages for that project.
No. The password is masked in the API and UI after saving - only entering a new value overwrites it.