Cmdlets for Lakebase

Build 25.0.9434

Establishing a Connection

With the CData Cmdlets users can install a data module, set the connection properties, and start scripting. This section provides examples of using our Lakebase Cmdlets with native PowerShell cmdlets, like the CSV import and export cmdlets.

Connecting to Lakebase

To connect to Lakebase, set these properties:

  • DatabricksInstance: The Databricks instance or server hostname, provided in the format instance-abcdef12-3456-7890-abcd-abcdef123456.database.cloud.databricks.com .
  • Server: The host name or IP address of the server hosting the Lakebase database.
  • Port (optional): The port of the server hosting the Lakebase database, set to 5432 by default.
  • Database (optional): The database to connect to after authenticating to the Lakebase Server, set to the authenticating user's default database by default.

Authentication Schemes for Lakebase

Lakebase supports two types of OAuth-based authentication schemes for calling workspace-level APIs: OAuthClient and OAuthPKCE.

OAuthClient

OAuthClient uses the OAuth client credentials grant type. This authentication scheme requires you to perform additional configuration on your service principal in order to connect, as described in Setting Up OAuthClient Authentication.

Authentication is handled via the OAuth Client Credentials flow. This flow does not involve direct user authentication; rather, it uses credentials that apply only to the application itself. The CData Cmdlets PowerShell Module for Lakebase uses the service principal itself to authenticate with the associated permissions being defined in the service principal.

Since no embedded OAuth credentials are provided, specifying the OAuthClient authentication scheme requires you to perform extra configuration of your service principal, as described in Setting Up OAuthClient Authentication.

Set these configuration parameters:

  • AuthScheme: OAuthClient.
  • OAuthClientId: The client ID (also known as the consumer key) that was assigned when you configured the service principal. This ID is required to identify the application to the OAuth authorization server during authentication.
  • OAuthClientSecret: The client secret (also known as the application secret or consumer secret) that was assigned when you configured the service principal. This confidential value is used to authenticate the application to the OAuth authorization server.

OAuthPKCE

OAuthPKCE uses the OAuth code grant type with PKCE (Proof Key for Code Exchange) to guard against cross-site request forgery and authorization code injection attacks.

In this authentication scheme, authentication is handled via the use of a temporary code that the client exchanges for an access token. The code itself is obtained from the authorization server, where the user can see what information the client is requesting, and can either approve or deny the request.

Set these configuration parameters:

Authenticating to Lakebase

Once you have set the configuration parameters required to connect to Lakebase, and the configuration parameters required for your chosen form of authentication, you can authenticate to Lakebase as described in the following sections.

Desktop Applications

The first time you authenticate to Lakebase from a desktop application you must set InitiateOAuth twice in the course of the OAuth flow:

  • At initial login, you must set InitiateOAuth to GETANDREFRESH. This launches the login page and saves tokens.
  • Once you have obtained valid access and refresh tokens, you can re-set InitiateOAuth to REFRESH. This reuses stored tokens without prompting the user again, which can be useful on unattended machines.

After authentication, tokens are saved to OAuthSettingsLocation. These values persist across sessions and are used to automatically refresh the access token when it expires. This means that upon subsequent connections you will not need to log in again.

Headless Machines

Headless environments like CI/CD pipelines, background services, or server-based integrations do not have an interactive browser. To authenticate using OAuthClient, you must complete the OAuth flow on a separate device with a browser and transfer the authentication result to the headless system.

Note: The following procedures are meant for use with the OAuthPKCE authscheme. Since the OAuthClient authscheme does not require browser interaction, it can make use of InitiateOAuth=GETANDREFRESH on a headless machine as well.

Setup options:

  • Obtain and exchange a verifier code: Use another device to sign in and retrieve a verifier code, which the headless system uses to request tokens.
  • Transfer an OAuth settings file: Authenticate on another device, then copy the stored token file to the headless environment.

Using a Verifier Code

  1. On a device with a browser:
    • Set InitiateOAuth to OFF.
    • Call the GetOAuthAuthorizationUrl stored procedure to generate a sign-in URL.
    • Open the returned URL in a browser. Sign in and grant grant permissions to the driver.
      You are redirected to the callback URL, which contains the verifier code.
    • After signing in, save the value of the code parameter from the redirect URL. You will use this later to set the OAuthVerifier connection property.
  2. At the headless machine:
    • Set the following properties:
      • OAuthClientId: The client Id that was generated when you configured the service principal.
      • OAuthClientSecret: The client secret that was generated when you configured the service principal.
    • After tokens are saved, reuse them by setting:
      • OAuthSettingsLocation: Make sure this location grants read and write permissions to the driver to enable the automatic refreshing of the access token.

Transferring OAuth Settings

  1. On a device with a browser, connect using the instructions in the Desktop Applications section. After connecting, tokens are saved to the file path in OAuthSettingsLocation. The default filename is OAuthSettings.txt.

  2. On the headless machine:
    1. Copy the OAuth settings file to the machine.
    2. Set the following properties:
      • OAuthSettingsLocation: Make sure this location grants read and write permissions to the driver to enable the automatic refreshing of the access token.

After setup, the driver uses the stored tokens to refresh the access token automatically. No browser or manual login is required.

Creating a Connection Object

You can then use the Connect-Lakebase cmdlet to create a connection object that can be passed to other cmdlets: 

$conn = Connect-Lakebase -User 'lakebase' -Password 'admin' -Server '127.0.0.1' -Port '5432' -Database 'lakebase'

Retrieving Data

After you have created a connection, you can use the other cmdlets to perform operations that you would normally expect to be able to perform against a relational database. The Select-Lakebase cmdlet provides a native PowerShell interface for retrieving data: 

$results = Select-Lakebase -Connection $conn -Table ""lakebase"."schema01".Orders" -Columns @("ShipName, ShipCity") -Where "ShipCountry='USA'"
The Invoke-Lakebase cmdlet provides an SQL interface. This cmdlet can be used to execute an SQL query via the Query parameter.

Piping Cmdlet Output

The cmdlets return row objects to the pipeline one row at a time. The following line exports results to a CSV file: 

Select-Lakebase -Connection $conn -Table "lakebase"."schema01".Orders -Where "ShipCountry = 'USA'" | Select -Property * -ExcludeProperty Connection,Table,Columns | Export-Csv -Path c:\my"lakebase"."schema01".OrdersData.csv -NoTypeInformation

You will notice that we piped the results from Select-Lakebase into a Select-Object cmdlet and excluded some properties before piping them into an Export-CSV cmdlet. We do this because the CData Cmdlets append Connection, Table, and Columns information onto each row object in the result set, and we do not necessarily want that information in our CSV file.

However, this makes it easy to pipe the output of one cmdlet to another. The following is an example of converting a result set to JSON: 

 
PS C:\> $conn  = Connect-Lakebase -User 'lakebase' -Password 'admin' -Server '127.0.0.1' -Port '5432' -Database 'lakebase'
PS C:\> $row = Select-Lakebase -Connection $conn -Table ""lakebase"."schema01".Orders" -Columns (ShipName, ShipCity) -Where "ShipCountry = 'USA'" | select -first 1
PS C:\> $row | ConvertTo-Json
{
  "Connection":  {

  },
  "Table":  ""lakebase"."schema01".Orders",
  "Columns":  [

  ],
  "ShipName":  "MyShipName",
  "ShipCity":  "MyShipCity"
}

Deleting Data

The following line deletes any records that match the criteria: 

Select-Lakebase -Connection $conn -Table "lakebase"."schema01".Orders -Where "ShipCountry = 'USA'" | Remove-Lakebase

Modifying Data

The cmdlets make data transformation easy as well as data cleansing. The following example loads data from a CSV file into Lakebase, checking first whether a record already exists and needs to be updated instead of inserted. 

Import-Csv -Path C:\My"lakebase"."schema01".OrdersUpdates.csv | %{
  $record = Select-Lakebase -Connection $conn -Table "lakebase"."schema01".Orders -Where ("Id = `'"+$_.Id+"`'")
  if($record){
    Update-Lakebase -Connection $conn -Table "lakebase"."schema01".Orders -Columns @("ShipName","ShipCity") -Values @($_.ShipName, $_.ShipCity) -Where "Id  = `'$_.Id`'"
  }else{
    Add-Lakebase -Connection $conn -Table "lakebase"."schema01".Orders -Columns @("ShipName","ShipCity") -Values @($_.ShipName, $_.ShipCity)
  }
}

Copyright (c) 2025 CData Software, Inc. - All rights reserved.
Build 25.0.9434