Connection overview

Beta

Lakebase Postgres (Autoscaling Beta) is the next version of Lakebase, available for evaluation only. For production workloads, use Lakebase Public Preview. See choosing between versions to understand which version is right for you.

Learn how to connect to your Lakebase Postgres database project.

Quick start: Connect to your database

Connect to your database using one of two authentication methods:

• OAuth role: Authenticate using your Databricks identity with an OAuth token. The project owner can connect immediately. To allow other Databricks identities to use OAuth authentication, create their Postgres roles using the databricks_auth extension. See Create an OAuth role.
• Native Postgres password authentication: Authenticate using a Postgres role with a traditional database password. Create these roles using the Lakebase UI or SQL.

The examples below use psql, a standard Postgres client, but you can also access your database through the Lakebase SQL Editor, Tables Editor, or third-party tools like pgAdmin and other Postgres-compatible clients. See Query your data for more options.

Each project contains a default database named databricks_postgres that you can connect to. This database is owned by the Postgres role for your Databricks identity (for example, user@databricks.com), which is automatically created when you create a project. To create additional Postgres roles, see Manage Postgres roles.

note

All database connections are subject to a 24-hour idle timeout and 3-day maximum connection life. Learn more: Connection timeouts

Connect with an OAuth role

OAuth roles let you connect using your Databricks identity with token-based authentication. The project owner's OAuth role is created automatically. To allow other Databricks identities to use OAuth authentication, their Postgres roles must be created using the databricks_auth extension. See Create an OAuth role.

To connect with an OAuth role:

1. From the Lakebase App, select your database project and click Connect.
2. Select the branch, compute, and database you want to connect to, then select your Databricks identity from the Roles drop-down menu.
3. Copy the psql connection snippet to your terminal and enter it.
4. When prompted for a password, click Copy OAuth Token and enter it as your password:

Connect with native Postgres password

Native Postgres password authentication lets you connect using a Postgres role with a traditional database password.

To connect with native Postgres password authentication:

1. From the Lakebase App, select your database project and click Connect.
2. Select the branch, compute, and database you want to connect to, then select a Postgres role from the Roles drop-down menu.
3. Copy the psql connection snippet to your terminal and enter it to connect.

note

Understanding authentication: Lakebase uses two separate systems - Databricks identities for OAuth authentication and Postgres roles for database access. Learn more: Authentication

Understanding connection strings

A Lakebase connection string includes the role, hostname, and database name. For native Postgres password authentication, the connection string also includes the password. For OAuth authentication using psql, you provide the password (OAuth token) separately when prompted.

Connection string format

OAuth authentication:

postgresql://your-email@example.com@ep-abc-123.databricks.com/databricks_postgres?sslmode=require
             ^                      ^                         ^
       role -|                      |- hostname               |- database

Native Postgres password authentication:

postgresql://role_name:password@ep-abc-123.databricks.com/databricks_postgres?sslmode=require
             ^         ^        ^                         ^
       role -|         |        |- hostname               |- database
                       |
                       |- password

note

The hostname includes the ID of the compute endpoint, which has an ep- prefix (for example, ep-abc-123). This identifies the specific compute that serves your database.

Connection string components

You can configure your connection using individual components. For example, you might place these in an .env file:

Bash

PGHOST=ep-abc-123.databricks.com
PGDATABASE=databricks_postgres
PGUSER=role_name
PGPASSWORD=your-password or token
PGPORT=5432

Or assign them to a DATABASE_URL variable:

Bash

DATABASE_URL="postgresql://role_name:password@ep-abc-123.databricks.com/databricks_postgres?sslmode=require"

Connection security

Lakebase requires that all connections use SSL/TLS encryption. The sslmode=require parameter enforces this requirement. All connection strings provided in the Lakebase App include this parameter by default.

Port

Lakebase uses the default Postgres port, 5432.

Network configuration

To connect classic compute to Postgres, open TCP port 5432 to 0.0.0.0/0 in your network security group.

Connect from apps and frameworks

The examples below show how to connect to your Lakebase database from different programming languages and frameworks. You can also get connection snippets for these languages from the Connect dialog in the Lakebase App.

Psql

Bash

psql 'postgresql://role_name:password@ep-abc-123.databricks.com/databricks_postgres?sslmode=require'

.env

ini

PGHOST=ep-abc-123.databricks.com
PGDATABASE=databricks_postgres
PGUSER=role_name
PGPASSWORD=password
PGPORT=5432

Prisma

JavaScript

import { PrismaClient } from '@prisma/client';

const prisma = new PrismaClient({
  datasources: {
    db: {
      url: process.env.DATABASE_URL,
    },
  },
});

.NET

Csharp

// Connection string
"Host=ep-abc-123.databricks.com;Database=databricks_postgres;Username=role_name;Password=password"

// with SSL
"Host=ep-abc-123.databricks.com;Database=databricks_postgres;Username=role_name;Password=password;SSL Mode=Require;Trust Server Certificate=true"

// Entity Framework (appsettings.json)
{
  ...
  "ConnectionStrings": {
    "DefaultConnection": "Host=ep-abc-123.databricks.com;Database=databricks_postgres;Username=role_name;Password=password;SSL Mode=Require;Trust Server Certificate=true"
  },
  ...
}

Django

Python

# settings.py
DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': 'databricks_postgres',
        'USER': 'role_name',
        'PASSWORD': 'password',
        'HOST': 'ep-abc-123.databricks.com',
        'PORT': '5432',
        'OPTIONS': {
            'sslmode': 'require',
        },
    }
}

SQLAlchemy

Python

from sqlalchemy import create_engine
import os

# Using environment variable
database_url = os.getenv('DATABASE_URL')
engine = create_engine(database_url)

# Or construct the connection string
engine = create_engine(
    'postgresql://role_name:password@ep-abc-123.databricks.com:5432/databricks_postgres?sslmode=require'
)

Symfony

Bash

# .env
DATABASE_URL="postgresql://role_name:password@ep-abc-123.databricks.com/databricks_postgres?sslmode=require&charset=utf8"

Go

Go

package main

import (
    "database/sql"
    "fmt"
    "log"
    "os"

    _ "github.com/lib/pq"
    "github.com/joho/godotenv"
)

func main() {
    err := godotenv.Load()
    if err != nil {
        log.Fatalf("Error loading .env file: %v", err)
    }

    connStr := os.Getenv("DATABASE_URL")
    if connStr == "" {
        panic("DATABASE_URL environment variable is not set")
    }

    db, err := sql.Open("postgres", connStr)
    if err != nil {
        panic(err)
    }
    defer db.Close()

    var version string
    if err := db.QueryRow("select version()").Scan(&version); err != nil {
        panic(err)
    }
    fmt.Printf("version=%s\n", version)
}

Next steps

• Authentication - Understand how OAuth tokens and Postgres passwords work, including token expiration and connection timeouts
• Manage Postgres roles - Create and manage Postgres roles for Databricks identities and understand pre-created roles
• Manage permissions - Learn how to grant database access to Postgres roles through privileges
• Query your data - Use SQL editor, psql, or other Postgres tools to query your database