w.postgres: Postgres

class databricks.sdk.service.postgres.PostgresAPI

Use the Postgres API to create and manage Lakebase Autoscaling Postgres infrastructure, including projects, branches, compute endpoints, and roles.

This API manages database infrastructure only. To query or modify data, use the Data API or direct SQL connections.

About resource IDs and names

Resources are identified by hierarchical resource names like projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id}. The name field on each resource contains this full path and is output-only. Note that name refers to this resource path, not the user-visible display_name.

create_branch(parent: str, branch: Branch, branch_id: str) → CreateBranchOperation

Creates a new database branch in the project.

Parameters:

  • parent – str The Project where this Branch will be created. Format: projects/{project_id}

  • branch – Branch The Branch to create.

  • branch_id – str The ID to use for the Branch. This becomes the final component of the branch’s resource name. The ID is required and must be 1-63 characters long, start with a lowercase letter, and contain only lowercase letters, numbers, and hyphens. For example, development becomes projects/my-app/branches/development.

Returns:

Operation

create_catalog(catalog: Catalog, catalog_id: str) → CreateCatalogOperation

Register a Postgres database in the Unity Catalog.

Parameters:

  • catalog – Catalog

  • catalog_id – str The ID in the Unity Catalog. It becomes the full resource name, for example “my_catalog” becomes “catalogs/my_catalog”.

Returns:

Operation

create_database(parent: str, database: Database [, database_id: Optional[str]]) → CreateDatabaseOperation

Create a Database.

Creates a database in the specified branch. A branch can have multiple databases.

Parameters:

  • parent – str The Branch where this Database will be created. Format: projects/{project_id}/branches/{branch_id}

  • database – Database The desired specification of a Database.

  • database_id –

    str (optional) The ID to use for the Database, which will become the final component of the database’s resource name. This ID becomes the database name in postgres.

    This value should be 4-63 characters, and only use characters available in DNS names, as defined by RFC-1123

    If database_id is not specified in the request, it is generated automatically.

Returns:

Operation

create_endpoint(parent: str, endpoint: Endpoint, endpoint_id: str) → CreateEndpointOperation

Creates a new compute endpoint in the branch.

Parameters:

  • parent – str The Branch where this Endpoint will be created. Format: projects/{project_id}/branches/{branch_id}

  • endpoint – Endpoint The Endpoint to create.

  • endpoint_id – str The ID to use for the Endpoint. This becomes the final component of the endpoint’s resource name. The ID is required and must be 1-63 characters long, start with a lowercase letter, and contain only lowercase letters, numbers, and hyphens. For example, primary becomes projects/my-app/branches/development/endpoints/primary.

Returns:

Operation

create_project(project: Project, project_id: str) → CreateProjectOperation

Creates a new Lakebase Autoscaling Postgres database project, which contains branches and compute endpoints.

Parameters:

  • project – Project The Project to create.

  • project_id – str The ID to use for the Project. This becomes the final component of the project’s resource name. The ID is required and must be 1-63 characters long, start with a lowercase letter, and contain only lowercase letters, numbers, and hyphens. For example, my-app becomes projects/my-app.

Returns:

Operation

create_role(parent: str, role: Role [, role_id: Optional[str]]) → CreateRoleOperation

Creates a new Postgres role in the branch.

Parameters:

  • parent – str The Branch where this Role is created. Format: projects/{project_id}/branches/{branch_id}

  • role – Role The desired specification of a Role.

  • role_id –

    str (optional) The ID to use for the Role, which will become the final component of the role’s resource name. This ID becomes the role in Postgres.

    This value should be 4-63 characters, and valid characters are lowercase letters, numbers, and hyphens, as defined by RFC 1123.

    If role_id is not specified in the request, it is generated automatically.

Returns:

Operation

create_synced_table(synced_table: SyncedTable, synced_table_id: str) → CreateSyncedTableOperation

Create a Synced Table.

Parameters:

  • synced_table – SyncedTable

  • synced_table_id –

    str The ID to use for the Synced Table. This becomes the final component of the SyncedTable’s resource name. ID is required and is the synced table name, containing (catalog, schema, table) tuple. Elements of the tuple are the UC entity names.

    Example: “{catalog}.{schema}.{table}”

    synced_table_id represents both of the following:

    1. An online VIEW virtual table in the Unity Catalog accessible via the Lakehouse Federation. 2. Postgres table named “{table}” in schema “{schema}” in the connected Postgres database

Returns:

Operation

delete_branch(name: str) → DeleteBranchOperation

Deletes the specified database branch.

Parameters:

name – str The full resource path of the branch to delete. Format: projects/{project_id}/branches/{branch_id}

Returns:

Operation

delete_catalog(name: str) → DeleteCatalogOperation

Delete a Database Catalog.

Parameters:

name –

str The full resource path of the catalog to delete.

Format: “catalogs/{catalog_id}”.

Returns:

Operation

delete_database(name: str) → DeleteDatabaseOperation

Delete a Database.

Parameters:

name – str The resource name of the postgres database. Format: projects/{project_id}/branches/{branch_id}/databases/{database_id}

Returns:

Operation

delete_endpoint(name: str) → DeleteEndpointOperation

Deletes the specified compute endpoint.

Parameters:

name – str The full resource path of the endpoint to delete. Format: projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id}

Returns:

Operation

delete_project(name: str) → DeleteProjectOperation

Deletes the specified database project.

Parameters:

name – str The full resource path of the project to delete. Format: projects/{project_id}

Returns:

Operation

delete_role(name: str [, reassign_owned_to: Optional[str]]) → DeleteRoleOperation

Deletes the specified Postgres role.

Parameters:

  • name – str The full resource path of the role to delete. Format: projects/{project_id}/branches/{branch_id}/roles/{role_id}

  • reassign_owned_to –

    str (optional) Reassign objects. If this is set, all objects owned by the role are reassigned to the role specified in this parameter.

    NOTE: setting this requires spinning up a compute to succeed, since it involves running SQL queries.

Returns:

Operation

delete_synced_table(name: str) → DeleteSyncedTableOperation

Delete a Synced Table.

Parameters:

name – str The Full resource name of the synced table, of the format “synced_tables/{catalog}.{schema}.{table}”, where (catalog, schema, table) are the UC entity names.

Returns:

Operation

generate_database_credential(endpoint: str [, claims: Optional[List[RequestedClaims]]]) → DatabaseCredential

Generate OAuth credentials for a Postgres database.

Parameters:

  • endpoint – str This field is not yet supported. The endpoint for which this credential will be generated. Format: projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id}

  • claims – List[RequestedClaims] (optional) The returned token will be scoped to UC tables with the specified permissions.

Returns:

DatabaseCredential

get_branch(name: str) → Branch

Retrieves information about the specified database branch.

Parameters:

name – str The full resource path of the branch to retrieve. Format: projects/{project_id}/branches/{branch_id}

Returns:

Branch

get_catalog(name: str) → Catalog

Get a Database Catalog.

Parameters:

name –

str The full resource path of the catalog to retrieve.

Format: “catalogs/{catalog_id}”.

Returns:

Catalog

get_database(name: str) → Database

Get a Database.

Parameters:

name – str The name of the Database to retrieve. Format: projects/{project_id}/branches/{branch_id}/databases/{database_id}

Returns:

Database

get_endpoint(name: str) → Endpoint

Retrieves information about the specified compute endpoint, including its connection details and operational state.

Parameters:

name – str The full resource path of the endpoint to retrieve. Format: projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id}

Returns:

Endpoint

get_operation(name: str) → Operation

Retrieves the status of a long-running operation.

Parameters:

name – str The name of the operation resource.

Returns:

Operation

get_project(name: str) → Project

Retrieves information about the specified database project.

Parameters:

name – str The full resource path of the project to retrieve. Format: projects/{project_id}

Returns:

Project

get_role(name: str) → Role

Retrieves information about the specified Postgres role, including its authentication method and permissions.

Parameters:

name – str The full resource path of the role to retrieve. Format: projects/{project_id}/branches/{branch_id}/roles/{role_id}

Returns:

Role

get_synced_table(name: str) → SyncedTable

Get a Synced Table.

Parameters:

name – str Format: “synced_tables/{catalog}.{schema}.{table}”, where (catalog, schema, table) are the entity names in the Unity Catalog.

Returns:

SyncedTable

list_branches(parent: str [, page_size: Optional[int], page_token: Optional[str]]) → Iterator[Branch]

Returns a paginated list of database branches in the project.

Parameters:

  • parent – str The Project that owns this collection of branches. Format: projects/{project_id}

  • page_size – int (optional) Upper bound for items returned. Cannot be negative.

  • page_token – str (optional) Page token from a previous response. If not provided, returns the first page.

Returns:

Iterator over Branch

list_databases(parent: str [, page_size: Optional[int], page_token: Optional[str]]) → Iterator[Database]

List Databases.

Parameters:

  • parent – str The Branch that owns this collection of databases. Format: projects/{project_id}/branches/{branch_id}

  • page_size – int (optional) Upper bound for items returned.

  • page_token – str (optional) Pagination token to go to the next page of Databases. Requests first page if absent.

Returns:

Iterator over Database

list_endpoints(parent: str [, page_size: Optional[int], page_token: Optional[str]]) → Iterator[Endpoint]

Returns a paginated list of compute endpoints in the branch.

Parameters:

  • parent – str The Branch that owns this collection of endpoints. Format: projects/{project_id}/branches/{branch_id}

  • page_size – int (optional) Upper bound for items returned. Cannot be negative.

  • page_token – str (optional) Page token from a previous response. If not provided, returns the first page.

Returns:

Iterator over Endpoint

list_projects([, page_size: Optional[int], page_token: Optional[str]]) → Iterator[Project]

Returns a paginated list of database projects in the workspace that the user has permission to access.

Parameters:

  • page_size – int (optional) Upper bound for items returned. Cannot be negative. The maximum value is 100.

  • page_token – str (optional) Page token from a previous response. If not provided, returns the first page.

Returns:

Iterator over Project

list_roles(parent: str [, page_size: Optional[int], page_token: Optional[str]]) → Iterator[Role]

Returns a paginated list of Postgres roles in the branch.

Parameters:

  • parent – str The Branch that owns this collection of roles. Format: projects/{project_id}/branches/{branch_id}

  • page_size – int (optional) Upper bound for items returned. Cannot be negative.

  • page_token – str (optional) Page token from a previous response. If not provided, returns the first page.

Returns:

Iterator over Role

update_branch(name: str, branch: Branch, update_mask: FieldMask) → UpdateBranchOperation

Updates the specified database branch. You can set this branch as the project’s default branch, or protect/unprotect it.

Parameters:

  • name – str Output only. The full resource path of the branch. Format: projects/{project_id}/branches/{branch_id}

  • branch –

    Branch The Branch to update.

    The branch’s name field is used to identify the branch to update. Format: projects/{project_id}/branches/{branch_id}

  • update_mask – FieldMask The list of fields to update. If unspecified, all fields will be updated when possible.

Returns:

Operation

update_database(name: str, database: Database, update_mask: FieldMask) → UpdateDatabaseOperation

Update a Database.

Parameters:

  • name – str The resource name of the database. Format: projects/{project_id}/branches/{branch_id}/databases/{database_id}

  • database –

    Database The Database to update.

    The database’s name field is used to identify the database to update. Format: projects/{project_id}/branches/{branch_id}/databases/{database_id}

  • update_mask – FieldMask The list of fields to update. If unspecified, all fields will be updated when possible.

Returns:

Operation

update_endpoint(name: str, endpoint: Endpoint, update_mask: FieldMask) → UpdateEndpointOperation

Updates the specified compute endpoint. You can update autoscaling limits, suspend timeout, or enable/disable the compute endpoint.

Parameters:

  • name – str Output only. The full resource path of the endpoint. Format: projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id}

  • endpoint –

    Endpoint The Endpoint to update.

    The endpoint’s name field is used to identify the endpoint to update. Format: projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id}

  • update_mask – FieldMask The list of fields to update. If unspecified, all fields will be updated when possible.

Returns:

Operation

update_project(name: str, project: Project, update_mask: FieldMask) → UpdateProjectOperation

Updates the specified database project.

Parameters:

  • name – str Output only. The full resource path of the project. Format: projects/{project_id}

  • project –

    Project The Project to update.

    The project’s name field is used to identify the project to update. Format: projects/{project_id}

  • update_mask – FieldMask The list of fields to update. If unspecified, all fields will be updated when possible.

Returns:

Operation

update_role(name: str, role: Role, update_mask: FieldMask) → UpdateRoleOperation

Update a role for a branch.

Parameters:

  • name – str Output only. The full resource path of the role. Format: projects/{project_id}/branches/{branch_id}/roles/{role_id}

  • role –

    Role The Postgres Role to update.

    The role’s name field is used to identify the role to update. Format: projects/{project_id}/branches/{branch_id}/roles/{role_id}

  • update_mask – FieldMask The list of fields to update in Postgres Role. If unspecified, all fields will be updated when possible.

Returns:

Operation