Access a database instance from SQL clients

Preview

This feature is in Public Preview in the following regions: us-east-1, us-west-2, eu-west-1, ap-southeast-1, ap-southeast-2, eu-central-1, us-east-2, ap-south-1.

This page describes how to access a Lakebase database instance from SQL clients and walks through how to connect to a database instance from psql.

You can access a database instance from external tools such as psql, DBeaver, and pgAdmin4. These tools also allow you to build dashboards to visualize database metrics for performance, storage usage, and query efficiency.

The psql command-line tool is PostgreSQL's built-in client that provides direct, interactive access to your database instance. Using psql gives you full Postgres functionality and integrates with existing Postgres workflows and tools.

DBeaver and pgAdmin are open source tools that allow you to manage your Postgres database. For instructions on how to install and connect, see the DBeaver documentation and the pgAdmin documentation.

Before you begin

• You must install psql. For more details, see the PostgreSQL tools and installation guide. psql version 14 or higher is required.
• You must install the libpq library.
• You have a corresponding Postgres role to log in to the database instance. See Create and manage Postgres roles for Databricks identities.
• Your Postgres role is granted the necessary permissions to access the database, schema, or table.
• You can authenticate to the database instance. If you must obtain an OAuth token for your database instance, see Authenticate to database instance.

Identity and database roles considerations

• The default owner of the instance is the Databricks user or service principal who provisions the database instance.
• During provisioning, a corresponding Postgres role name is automatically created for the identity:
  • Databricks user: The Postgres role name is the user’s email address.
  • Databricks Service Principal: The Postgres role name is the application ID of the service principal.

Connect with psql

After your database instance's status shows Available, connect to it using the psql command-line tool. Copy the connection command from the database instance configuration page.

1. Click Compute in the workspace sidebar.
2. Click Database instances.
3. Select the database instance you want to access from psql.
4. Click Connection details.
5. Copy the Connect with PSQL string.
6. Paste the command into your terminal and run it to connect to the database instance using psql.