> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openlit.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Database Config

> Add and manage ClickHouse database configurations for an OpenLIT project

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.

<Steps>
  <Step title="Open Organisation">
    Select **Organisation** or **Projects** from the sidebar under Settings.
  </Step>

  <Step title="Open a project">
    Choose the project that should own the database configuration, then open the **Database configurations** tab.
  </Step>

  <Step title="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).
  </Step>

  <Step title="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.
  </Step>
</Steps>

## 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.

<Card title="Multiple database guide" href="/latest/openlit/developer-resources/multiple-db" icon="database">
  Learn more about using multiple ClickHouse database configurations in OpenLIT.
</Card>

## 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

<AccordionGroup>
  <Accordion title="Can I use the same database configuration across two projects?">
    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.
  </Accordion>

  <Accordion title="Do I need a new ClickHouse instance for every database configuration?">
    No. Multiple configurations can point at the same ClickHouse cluster using different database names, or at entirely different clusters - whichever fits your infrastructure.
  </Accordion>

  <Accordion title="What happens if I open a project with no database configuration?">
    OpenLIT detects the missing configuration and walks you through adding one before showing any data pages for that project.
  </Accordion>

  <Accordion title="Is my ClickHouse password visible after I save a configuration?">
    No. The password is masked in the API and UI after saving - only entering a new value overwrites it.
  </Accordion>
</AccordionGroup>