Share via

Get started with the Databricks CLI for Lakebase

Important

Lakebase Autoscaling is in Beta in the following regions: eastus2, westeurope, westus.

Lakebase Autoscaling is the latest version of Lakebase with autoscaling compute, scale-to-zero, branching, and instant restore. For feature comparison with Lakebase Provisioned, see choosing between versions.

This guide helps you get started with the Databricks CLI to manage your Lakebase projects, branches, and computes (endpoints). You'll learn how to create a working project in just a few commands.

For complete command reference and all available options, see Databricks CLI postgres commands.

Prerequisites

  • Databricks CLI: Install the Databricks CLI. See Install the Databricks CLI.
  • Workspace access: You must have access to a Azure Databricks workspace where your Lakebase resource resides.

Authenticate with Databricks

Before running any CLI commands, authenticate with your Azure Databricks workspace:

databricks auth login --host https://your-workspace.cloud.databricks.com

Replace https://your-workspace.cloud.databricks.com with your actual workspace URL. This command opens a browser window for you to authenticate with your Azure Databricks account using OAuth.

Note

If you have multiple profiles, use the --profile flag to specify which one to use: databricks postgres <command> --profile my-profile. To view your configured profiles, run databricks auth profiles.

For more authentication options, see Databricks authentication.

Get command help

The CLI provides built-in help for all commands. Use --help to see available commands and options.

Get an overview of all Postgres commands:

databricks postgres --help

This displays all available commands, global flags, and information about resource naming conventions.

Get detailed help for a specific command:

databricks postgres create-project --help

This shows the command's purpose, required and optional parameters, usage examples, and available flags.

Quickstart: Create your first project

Follow these steps to create a complete working project with a branch and compute endpoint:

1. Create a project

Create a new Lakebase project:

databricks postgres create-project my-project \
  --json '{
    "spec": {
      "display_name": "My Lakebase Project"
    }
  }'

This command creates a project and waits for it to complete. The project ID (my-project) becomes part of the resource name: projects/my-project. The project is created with a default production branch and a read-write compute endpoint, both with auto-generated IDs.

Optionally, export the project ID as a variable to use in subsequent commands:

export PROJECT_ID="my-project"

2. Get the branch ID

List the branches in your project to find the default branch ID:

databricks postgres list-branches projects/$PROJECT_ID

This returns information about all branches in the project. Look for the branch with "default": true in the status. Note the branch ID from the name field (for example, br-divine-sea-y2k942xa).

Optionally export the branch ID as a variable for use in subsequent commands:

export BRANCH_ID="br-divine-sea-y2k942xa"

Replace br-divine-sea-y2k942xa with your actual default branch ID from the list output.

3. Get the endpoint ID

List the endpoints in your branch. The default branch automatically includes a read-write endpoint:

databricks postgres list-endpoints projects/$PROJECT_ID/branches/$BRANCH_ID

Note the endpoint ID from the name field. It will be in the format projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id}. Extract the endpoint ID (for example, ep-plain-sunset-y2vc0zan) and optionally export it as a variable:

export ENDPOINT_ID="ep-plain-sunset-y2vc0zan"

Replace ep-plain-sunset-y2vc0zan with your actual endpoint ID from the list output.

4. Generate database credentials

Generate credentials to connect to your database:

databricks postgres generate-database-credential \
  projects/$PROJECT_ID/branches/$BRANCH_ID/endpoints/$ENDPOINT_ID

The command returns an OAuth token you can use with PostgreSQL clients like psql to access your data using your Databricks identity. For step-by-step instructions on connecting with psql, see Connect with psql. For more information about token expiration and authentication, see Authentication.

Managing your resources

List all projects

List all projects in your workspace:

databricks postgres list-projects

This returns information about each project including its name, display name, current state, and creation/update timestamps.

Get resource details

Get detailed information about a project:

databricks postgres get-project projects/$PROJECT_ID

This returns detailed project configuration including display name, PostgreSQL version, owner, history retention period, branch size limits, default endpoint settings, storage size, and creation/update timestamps.

Get detailed information about a branch:

databricks postgres get-branch projects/$PROJECT_ID/branches/$BRANCH_ID

This returns detailed branch information including current state, default branch status, protection status, logical size, source branch details (if branched from another branch), and creation/update timestamps.

Get detailed information about an endpoint:

databricks postgres get-endpoint projects/$PROJECT_ID/branches/$BRANCH_ID/endpoints/$ENDPOINT_ID

This returns detailed endpoint configuration including endpoint type (read-write or read-only), autoscaling settings (minimum and maximum compute units), current state (ACTIVE, IDLE, etc.), connection host, suspend timeout, and creation/update timestamps.

Update resources

Update a resource using the update mask pattern. The update mask specifies which fields to update:

databricks postgres update-branch \
  projects/$PROJECT_ID/branches/$BRANCH_ID \
  spec.is_protected \
  --json '{
    "spec": {
      "is_protected": true
    }
  }'

This example sets spec.is_protected to true, making the branch protected. The update mask (spec.is_protected) tells the API which field to update. The command returns the updated resource showing the new value and an updated update_time timestamp.

To update multiple fields, use a comma-separated list:

databricks postgres update-endpoint \
  projects/$PROJECT_ID/branches/$BRANCH_ID/endpoints/$ENDPOINT_ID \
  "spec.autoscaling_limit_min_cu,spec.autoscaling_limit_max_cu" \
  --json '{
    "spec": {
      "autoscaling_limit_min_cu": 1.0,
      "autoscaling_limit_max_cu": 8.0
    }
  }'

Common workflows

Create a feature branch from production

Create a new branch based on an existing branch to test changes. When you specify a source_branch, the new branch will have the same schema and data as the source branch at the time of creation. Replace the project and branch IDs with your actual values:

databricks postgres create-branch \
  projects/my-project \
  feature \
  --json '{
    "spec": {
      "source_branch": "projects/my-project/branches/br-divine-sea-y2k942xa",
      "no_expiry": true
    }
  }'

Note

When creating a branch, you must specify an expiration policy. Use no_expiry: true to create a permanent branch.

To use shell variables inside the JSON spec (like $PROJECT_ID or $BRANCH_ID), you would need to use double quotes for the --json value and escape the internal quotes.

The feature branch needs a read-write compute endpoint to allow database operations:

databricks postgres create-endpoint \
  projects/$PROJECT_ID/branches/feature \
  primary \
  --json '{
    "spec": {
      "endpoint_type": "ENDPOINT_TYPE_READ_WRITE",
      "autoscaling_limit_min_cu": 0.5,
      "autoscaling_limit_max_cu": 2.0
    }
  }'

After completing your development and testing on the feature branch, you can delete it:

databricks postgres delete-branch projects/$PROJECT_ID/branches/feature

Note

Delete commands return immediately, but the actual deletion may take time to complete. You can verify deletion by running the corresponding get resource command, which returns an error once the resource is fully deleted.

Scale reads with read replicas

Add read replicas to handle increased read traffic. This example adds a read replica to the default production branch:

databricks postgres create-endpoint \
  projects/$PROJECT_ID/branches/$BRANCH_ID \
  read-replica-1 \
  --json '{
    "spec": {
      "endpoint_type": "ENDPOINT_TYPE_READ_ONLY",
      "autoscaling_limit_min_cu": 0.5,
      "autoscaling_limit_max_cu": 4.0
    }
  }'

You can create multiple read replicas with different endpoint IDs (read-replica-1, read-replica-2, etc.) to distribute read workloads.

Understanding key concepts

Long-running operations

Create, update, and delete commands are long-running operations. By default, the CLI waits for the operation to complete. Use --no-wait to return immediately and poll the status separately:

databricks postgres create-project $PROJECT_ID \
  --json '{"spec": {"display_name": "My Project"}}' \
  --no-wait

Poll the operation status:

databricks postgres get-operation projects/$PROJECT_ID/operations/operation-id

Resource naming

Lakebase uses hierarchical resource names:

  • Projects: projects/{project_id}. You specify the project ID when creating a project.
  • Branches: projects/{project_id}/branches/{branch_id}. You specify the branch ID when creating a branch.
  • Endpoints: projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id}. You specify the endpoint ID (like primary or read-replica-1) when creating an endpoint.

IDs must be 1-63 characters long, start with a lowercase letter, and contain only lowercase letters, numbers, and hyphens.

Update masks

Update commands require an update mask that specifies which fields to modify. The mask is a field path like spec.display_name or a comma-separated list for multiple fields.

The --json payload contains the new values for those fields. Only the fields listed in the update mask are modified.

Next steps

  • Last updated on