1. Install the CLI
The Nava Labs CLI is available via pip. Python 3.9 or higher is required.
Terminal
$ pip install nava-labs
Successfully installed nava-labs-0.9.1
$ nava auth login
Opening browser for authentication...
+ Authenticated as [email protected]
2. Add a data source
Run nava sources add and follow the prompts. Or pass credentials directly as flags:
Terminal
$ nava sources add \
--type postgresql \
--name prod-db \
--host db.prod.internal \
--database analytics \
--user nvl_reader
Password: ••••••••••
+ Source "prod-db" connected. 47 tables discovered.
3. Connector requirements
Each connector type requires specific permissions. The read-only role setup for common sources:
postgres
-- Create a read-only role for Nava Labs
CREATE USER nvl_reader WITH PASSWORD 'your-password';
GRANT CONNECT ON DATABASE analytics TO nvl_reader;
GRANT USAGE ON SCHEMA public TO nvl_reader;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO nvl_reader;
4. Run your first query
Once two sources are connected, run a cross-source query using the CLI or API:
Terminal
$ nava query run "
SELECT u.email, COUNT(e.id) AS events
FROM prod-db.public.users u
JOIN events-db.public.events e
ON u.id = e.user_id
GROUP BY u.email
"
email | events
--------------------------|-------
[email protected] | 247
[email protected] | 133
-- 1,247 rows, 0.42s
5. Using the Python SDK
The Python SDK wraps the REST API and includes a pandas-compatible result set:
example.py
import nava_labs
client = nava_labs.Client(api_key="nvl_...")
df = client.query("""
SELECT u.plan, COUNT(*) AS count
FROM prod-db.users u
GROUP BY u.plan
""").to_pandas()
print(df)
6. Custom connectors
Implement BaseConnector for internal APIs or proprietary databases. See the SDK reference for the full interface.
Custom connectors count as one source against your plan limit, same as built-in connectors. The SDK is available on all plans.