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

# Databricks Lakebase

> Connect Artie to a Databricks Lakebase Postgres destination with OAuth, using a Databricks service principal instead of a database password.

Use this for a [Databricks Lakebase](https://docs.databricks.com/aws/en/oltp/) Postgres destination when you don't want to allow native Postgres password logins. Artie signs in as a Databricks service principal and requests a short-lived Postgres credential for every new connection, so no database password is stored. For other PostgreSQL databases, or Lakebase with a password role, follow the [PostgreSQL destination](/docs/destinations/postgres) setup.

What you'll need:

* A Lakebase project. Instances upgraded from Lakebase Provisioned work too.
* Permission to create a service principal and generate an OAuth secret for it in the workspace.
* A Databricks OAuth sign-in to the Lakebase database with `CREATE` and `CREATE ROLE`, such as the project owner.

## Setup

<Steps>
  <Step title="Create a service principal">
    In your workspace, go to **Settings** > **Identity and access** > **Service principals** and add a service principal for Artie. On its **Configurations** tab, enable **Workspace access**. Lakebase only issues database credentials to service principals that have it.

    On the **Secrets** tab, select **Generate secret**, then copy the client ID and the secret. The secret is only shown once, and the client ID is the same as the service principal's application ID. Artie requests the `all-apis` scope, so the secret must allow it. Rotate the secret in Artie before it expires.
  </Step>

  <Step title="Create the service principal's Postgres role">
    In the Lakebase App, open your project's **SQL Editor**, select the branch and the `databricks_postgres` database, and run the following while signed in with Databricks OAuth. Sessions that signed in with a Postgres password can't create OAuth roles.

    ```sql theme={null}
    CREATE EXTENSION IF NOT EXISTS databricks_auth;

    -- The role name is the service principal's client ID (case-sensitive).
    SELECT databricks_create_role('6f1c2a7e-3b4d-4e8f-9a0b-1c2d3e4f5a6b', 'SERVICE_PRINCIPAL');

    -- New OAuth roles can only log in. Allow connecting and creating the schemas Artie needs.
    GRANT CONNECT, CREATE ON DATABASE databricks_postgres TO "6f1c2a7e-3b4d-4e8f-9a0b-1c2d3e4f5a6b";

    -- If the target schema already exists, allow creating tables in it.
    GRANT USAGE, CREATE ON SCHEMA analytics TO "6f1c2a7e-3b4d-4e8f-9a0b-1c2d3e4f5a6b";
    ```

    Artie owns the schemas and tables it creates, so it can run DDL such as `ALTER TABLE` on them. Lakebase doesn't support transferring ownership with a plain `ALTER ... OWNER TO`, so grant access to an existing schema instead.
  </Step>

  <Step title="Find the connection details">
    In the Lakebase App, open your project's **Branches** page, select the branch, and open its **Computes** tab.

    * **Host**: select **Connect** and copy the host. Use the compute's direct host, not the `-pooler` host, because Lakebase connection pooling doesn't support OAuth roles.
    * **Endpoint**: in the compute's **Get ID** menu, copy the **Resource name**, for example `projects/my-project/branches/production/endpoints/primary`. You can also list them with `databricks postgres list-endpoints projects/<project-id>/branches/<branch-id>`.
    * **Workspace host**: your workspace's hostname without `https://`, for example `dbc-1234abcd-5678.cloud.databricks.com`.
  </Step>

  <Step title="Add the destination in Artie">
    Create a PostgreSQL destination and select **Databricks Lakebase OAuth** as the authentication method. Enter the host, port `5432`, workspace host, endpoint, client ID, and client secret. Use `databricks_postgres` as the database unless you created another one.
  </Step>
</Steps>

## Advanced

<Accordion title="How Artie uses the OAuth credentials">
  * Artie exchanges the client ID and secret for a workspace OAuth token, then calls the Lakebase credentials API for a Postgres credential that's valid for 60 minutes. It caches the credential and requests a new one shortly before it expires.
  * Lakebase only checks the credential at sign-in, so open connections stay open after it expires. New connections use the current credential.
  * Artie always connects to Lakebase over TLS.
</Accordion>

<Accordion title="Writing to tables that another role owns">
  Artie can write rows to existing tables owned by another role if you grant it `SELECT, INSERT, UPDATE, DELETE` on them, but schema changes such as `ALTER TABLE` need ownership. To move ownership to the service principal, use Lakebase's [temporary shared role procedure](https://docs.databricks.com/aws/en/oltp/projects/transfer-object-ownership).
</Accordion>

<Accordion title="Network access">
  Choosing OAuth over password sign-in doesn't change who can reach the database. Network access is controlled separately, through your workspace's IP access lists and ingress policies or Private Link. Allow Artie's IP addresses, or connect through [PrivateLink](/docs/connection-options/privatelink).
</Accordion>

<Warning>Databricks Lakebase OAuth is only supported for PostgreSQL destinations, not sources.</Warning>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.