Metadata-Version: 2.4
Name: nxd-sqla
Version: 0.0.1
Summary: SQLAlchemy nxd dialect that wraps DB-specific dialects
Author: nextdata.inc
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Python: >=3.8
Requires-Dist: sqlalchemy<3,>=1.4
Provides-Extra: jupyterhub
Requires-Dist: cryptography>=42.0.4; extra == 'jupyterhub'
Requires-Dist: packaging>=21; extra == 'jupyterhub'
Provides-Extra: snowflake
Requires-Dist: snowflake-sqlalchemy; extra == 'snowflake'
Provides-Extra: superset
Description-Content-Type: text/markdown

# SQLAlchemy NXD Dialect

A SQLAlchemy dialect that connects to NXD to get database connection info before
connecting to the database. Includes decorators and event listeners for connection
and execution events. These decorators can be instrumented to capture info about
the user or the tables accessed.

## URL Structure
A valid connection URL looks something like this:
```shell
snowflake+nxd://dp.trynxd.com/listener-play-events?environment=demo&auth_token=xxxx
```
The `auth_token` can be either a personal access token (these start with `nxdpat_`)
or a bearer token, which is the token found in `~/.nxd/tokens.json`. To obtain a
PAT, run the following:
```shell
nxd create personal-access-token --name my-token --expires P30D
```
To obtain a bearer token do the following:
```shell
nxd login && cat ~/.nxd/tokens.json | jq .
```
The SQLAlchemy connector will use the information in the URL passed to fetch the
data product's services, look for a Snowflake service, construct a Snowflake
SQLAlchemy URL and delegate to the Snowflake connector.

## Integration Testing
Testing requires access to dp.nxd.local with Daff DPs deployed.

```shell
make integration-test
```

## Deploying to Superset

To test, enable superset on your cluster by setting installed=true for the
user-internal release in [/shared/tools/helmfile.yaml](../../shared/tools/helmfile.yaml)
and deploying.

Browse to [Settings -> Database Connections](https://superset.nxd.local/databaseview/list)
and make a connection of type "Other" the following:

* name: nxd listener-play-events
* url: snowflake+nxd://dp.trynxd.com/listener-play-events?environment=demo&auth_token=[your auth token]

Browse back to [SQL Lab](https://superset.nxd.local/sqllab/), select the database,
schema and table to see column names. Execute a sample query.

## Viewing Events
Currently, connection and SQL execute events are captured and logged. To view them,
tail the k8s logs of the superset pod. For example:

```shell
kubectl logs --tail=1 -f superset-576dccfb7f-ksgl4 -n user | grep "New DBAPI connection"
kubectl logs --tail=1 -f superset-576dccfb7f-ksgl4 -n user | grep "Before execute"
kubectl logs --tail=1 -f superset-576dccfb7f-ksgl4 -n user | grep "After execute"
```
