Merge pull request #13 from alexmalins/add-tests-badge-to-readme

Add GitHub code quality & tests Actions badges to Readme

.github/workflows/code_quality_tests_ubuntu_masos.yml

@@ -1,4 +1,4 @@
-name: Code formatting, linting, type checks and tests on ubuntu-latest and macos-latest
+name: Code checks & tests (Ubuntu & macOS)
 
 on:
   push:

.github/workflows/tests_windows_latest.yml

@@ -1,4 +1,4 @@
-name: Tests on windows-latest
+name: Tests (Windows)
 
 on:
   push:

README.md

@@ -3,6 +3,8 @@
 [![PyPI](https://img.shields.io/pypi/v/harlequin-databricks)](https://pypi.org/project/harlequin-databricks/)
 [![Conda](https://anaconda.org/conda-forge/harlequin-databricks/badges/version.svg)](https://anaconda.org/conda-forge/harlequin-databricks)
 [![Python Version](https://img.shields.io/pypi/pyversions/harlequin-databricks)](https://pypi.org/project/harlequin-databricks/)
+[![Tests](https://github.com/alexmalins/harlequin-databricks/actions/workflows/code_quality_tests_ubuntu_masos.yml/badge.svg)](https://github.com/alexmalins/harlequin-databricks/actions/workflows/code_quality_tests_ubuntu_masos.yml)
+[![Tests on Windows](https://github.com/alexmalins/harlequin-databricks/actions/workflows/tests_windows_latest.yml/badge.svg)](https://github.com/alexmalins/harlequin-databricks/actions/workflows/tests_windows_latest.yml)
 [![Code Style: Black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/alexmalins/harlequin-databricks/actions/workflows/code_quality.yml)
 [![License: MIT](https://img.shields.io/pypi/l/harlequin-databricks)](https://github.com/alexmalins/harlequin-databricks/blob/main/LICENSE)
 [![Downloads](https://static.pepy.tech/badge/harlequin-databricks)](https://pepy.tech/project/harlequin-databricks)
@@ -62,47 +64,61 @@ pipx install harlequin[databricks]
 
 ## Usage and Configuration
 
-For a minimum connection you are going to need:
+To connect to Databricks you are going to need to provide as CLI arguments:
 
 - server-hostname
 - http-path
-- access-token
+- credentials for one of the following authentication methods:
+  - a personal access token (PAT)
+  - a username and password
+  - an OAuth U2M type
+  - a service principle client ID and secret for OAuth M2M
+
+
+### Personal Access Token (PAT) authentication:
 
 ```bash
-harlequin -a databricks --server-hostname my_databricks.cloud.databricks.com --http-path /sql/1.0/endpoints/1234567890abcdef --access-token dabpi***
+harlequin -a databricks --server-hostname ***.cloud.databricks.com --http-path /sql/1.0/endpoints/*** --access-token dabpi***
 ```
 
-Authentication is also possible using a username and password (known as basic authentication):
+### Username and password (basic) authentication:
 
 ```bash
-harlequin -a databricks --server-hostname my_databricks.cloud.databricks.com --http-path /sql/1.0/endpoints/1234567890abcdef --username my_user --password my_pass
+harlequin -a databricks --server-hostname ***.cloud.databricks.com --http-path /sql/1.0/endpoints/*** --username *** --password ***
 ```
 
-Or by using [OAuth user-to-machine (U2M) authentication](https://docs.databricks.com/en/dev-tools/python-sql-connector.html#auth-u2m)
-- supply `databricks-oauth` or `azure-oauth` to the `--auth-type` CLI argument:
+### OAuth U2M authentication:
+
+For [OAuth user-to-machine (U2M) authentication](https://docs.databricks.com/en/dev-tools/python-sql-connector.html#auth-u2m)
+supply either `databricks-oauth` or `azure-oauth` to the `--auth-type` CLI argument:
 
 ```bash
-harlequin -a databricks --server-hostname my_databricks.cloud.databricks.com --http-path /sql/1.0/endpoints/1234567890abcdef --auth-type databricks-oauth
+harlequin -a databricks --server-hostname ***.cloud.databricks.com --http-path /sql/1.0/endpoints/*** --auth-type databricks-oauth
 ```
 
-Or via [OAuth machine-to-machine (M2M) authentication](https://docs.databricks.com/en/dev-tools/python-sql-connector.html#oauth-machine-to-machine-m2m-authentication),
-which also requires you `pip install databricks-sdk` as an additional dependency
+### OAuth M2M authentication:
+
+For [OAuth machine-to-machine (M2M) authentication](https://docs.databricks.com/en/dev-tools/python-sql-connector.html#oauth-machine-to-machine-m2m-authentication)
+you need to `pip install databricks-sdk` as an additional dependency
 ([databricks-sdk](https://github.com/databricks/databricks-sdk-py) is an optional dependency of
-`harlequin-databricks`):
+`harlequin-databricks`) and supply `--client-id` and `--client-secret` CLI arguments:
 
 ```bash
-harlequin -a databricks --server-hostname my_databricks.cloud.databricks.com --http-path /sql/1.0/endpoints/1234567890abcdef --client-id *** --client-secret ***
+harlequin -a databricks --server-hostname ***.cloud.databricks.com --http-path /sql/1.0/endpoints/*** --client-id *** --client-secret ***
 ```
 
-For more details on command line options, run:
+## Store an alias for your connection string
+
+We recommend you include an alias for your connection string in your `.bash_profile`/`.zprofile` so
+you can launch harlequin-databricks with a short command like `hdb` each time.
+
+Run this command
+(once) to create the alias:
 
 ```bash
-harlequin --help
+echo 'alias hdb="harlequin -a databricks --server-hostname ***.cloud.databricks.com --http-path /sql/1.0/endpoints/*** --access-token dabpi***"' >> .bash_profile    
 ```
 
-For more information, see the
-[harlequin-databricks Docs](https://harlequin.sh/docs/databricks/index).
-
 ## Using Unity Catalog and want fast Data Catalog indexing?
 
 Supply the `--skip-legacy-indexing` command line flag if you do not care about legacy metastores
@@ -122,11 +138,22 @@ So if your Databricks instance is running Unity Catalog, and you no longer care
 metastores, setting the `--skip-legacy-indexing` CLI flag is recommended as it will mean
 much faster indexing & refreshing of the assets in the Data Catalog pane.
 
+## Other CLI options:
+
+For more details on command line options, run:
+
+```bash
+harlequin --help
+```
+
+For more information, see the
+[harlequin-databricks Docs](https://harlequin.sh/docs/databricks/index).
+
 ## Issues, Contributions and Feature Requests
 
 Please report bugs/issues with this adapter via the GitHub
 [issues](https://github.com/alexmalins/harlequin-databricks/issues) page. You are welcome to
-attempt fixes yourself by forking this repo then opening an [PR](https://github.com/alexmalins/harlequin-databricks/pulls).
+attempt fixes yourself by forking this repo then opening a [PR](https://github.com/alexmalins/harlequin-databricks/pulls).
 
 For feature suggestions, please post in the
 [discussions](https://github.com/alexmalins/harlequin-databricks/discussions).