Skip to main content

Quickstart Guide

Get started with the Taruvi SDK in 5 minutes. This guide will walk you through creating your first application using the SDK.

Prerequisites​

Before you begin, ensure you have:

  • ✅ Installed the SDK (Installation Guide)
  • ✅ Access to a Taruvi instance (URL and credentials)
  • ✅ An application slug (create one in the Taruvi dashboard)

Step 1: Install the SDK​

pip install taruvi

Step 2: Setup Credentials​

Create a .env file in your project root:

# .env
TARUVI_API_URL=https://api.taruvi.cloud
TARUVI_APP_SLUG=my-app
[email protected]
TARUVI_PASSWORD=your-password
tip

Never commit your .env file to version control. Add it to .gitignore!

Step 3: Write Your First Script​

Create a file and add the following code:

quickstart.py
# Import the SDK
from taruvi import Client
import os

# Create client (api_url and app_slug are required)
client = Client(
    api_url=os.getenv("TARUVI_API_URL", "https://api.taruvi.cloud"),
    app_slug=os.getenv("TARUVI_APP_SLUG", "my-app")
)

# Authenticate
auth_client = client.auth.signInWithPassword(
    username=os.getenv("TARUVI_USERNAME"),
    password=os.getenv("TARUVI_PASSWORD")
)

# Query database (returns {"data": [...], "total": N})
print("📊 Fetching users...")
result = auth_client.database.from_("users").page_size(5).execute()
users = result["data"]
print(f"✅ Found {result['total']} users (showing {len(users)})")

for user in users:
    print(f"  - {user.get('username', 'N/A')}: {user.get('email', 'N/A')}")

# Execute a function
print("\n🚀 Executing function...")
result = auth_client.functions.execute(
    "hello-world",
    params={"name": "Alice"}
)
print(f"✅ Function result: {result}")

print("\n🎉 Quickstart complete!")

Step 4: Run Your Script​

python quickstart.py

Expected Output:

📊 Fetching users...
✅ Found 25 users (showing 5)
  - alice: [email protected]
  - bob: [email protected]
  - charlie: [email protected]
  - diana: [email protected]
  - eve: [email protected]

🚀 Executing function...
✅ Function result: {'data': {'message': 'Hello, Alice!'}}

🎉 Quickstart complete!

What Just Happened?​

Let's break down what the code does:

1. Import and Setup​

from taruvi import Client

Import the main Client class that provides access to all SDK features.

2. Create Client​

client = Client(api_url="...", app_slug="...")

Initialize the client with your Taruvi instance URL and application slug. Both parameters are required. The client starts unauthenticated.

3. Authenticate​

auth_client = client.auth.signInWithPassword(
    username="[email protected]",
    password="secret123"
)

Authenticate using username/password. The SDK returns a new client instance with authentication credentials attached.

4. Query Database​

result = auth_client.database.from_("users").page_size(5).execute()
users = result["data"]

Use the query builder to fetch data with filters, sorting, and pagination. execute() returns a dict with "data" (list of records) and "total" (total count).

5. Execute Function​

result = auth_client.functions.execute("hello-world", params={...})

Execute serverless functions with custom parameters.

Try More Examples​

Example 1: Query with Filters​

# Find active users over 18 years old
result = (
    auth_client.database.from_("users")
    .filter("is_active", "eq", True)
    .filter("age", "gte", 18)
    .sort("created_at", "desc")
    .page_size(10)
    .execute()
)

print(f"Found {result['total']} active adult users")
for user in result["data"]:
    print(f"  {user['username']}: age {user['age']}")

Example 2: Upload a File​

# Upload a file to storage
with open("document.pdf", "rb") as f:
    result = auth_client.storage.from_("documents").upload(
        files=[("document.pdf", f)],
        paths=["uploads/document.pdf"]
    )

print(f"File uploaded: {result[0]['path']}")

Example 3: Execute Async Function​

import time

# Execute long-running function in background
result = auth_client.functions.execute(
    "process-large-dataset",
    params={"dataset_id": 123},
    is_async=True
)

# Get task ID
task_id = result['invocation']['celery_task_id']
print(f"Task started: {task_id}")

# Poll for result
while True:
    task_result = auth_client.functions.get_result(task_id)
    status = task_result.get('status', task_result.get('data', {}).get('status'))

    if status == 'SUCCESS':
        print(f"Task completed: {task_result.get('result')}")
        break
    elif status == 'FAILURE':
        print(f"Task failed: {task_result.get('traceback')}")
        break

    print("Task still running...")
    time.sleep(2)

Example 4: Create and Update Records​

# Create a new record
new_user = auth_client.database.create("users", {
    "username": "frank",
    "email": "[email protected]",
    "age": 25
})
print(f"Created user: {new_user}")

# Update the record
updated_user = auth_client.database.update(
    "users",
    new_user['id'],
    {"age": 26}
)
print(f"Updated age to: {updated_user['age']}")

# Delete the record
auth_client.database.delete("users", record_id=new_user['id'])
print("User deleted")

# Or use the query builder for CRUD
result = (
    auth_client.database.from_("users")
    .create({"username": "grace", "email": "[email protected]"})
    .execute()
)
print(f"Created via query builder: {result}")

Common Patterns​

Using Context Managers (Python)​

from taruvi import Client

# Client automatically closes connections when done
with Client(api_url="https://api.taruvi.cloud", app_slug="my-app") as client:
    auth_client = client.auth.signInWithPassword(username="...", password="...")
    result = auth_client.database.from_("users").execute()
    users = result["data"]
    # Connection automatically closed

Error Handling​

from taruvi import Client, NotFoundError, ValidationError, TaruviError

client = Client(api_url="https://api.taruvi.cloud", app_slug="my-app")

try:
    auth_client = client.auth.signInWithPassword(
        username="[email protected]",
        password="secret123"
    )

    user = auth_client.database.get("users", record_id=999)

except NotFoundError as e:
    print(f"User not found: {e.message}")

except ValidationError as e:
    print(f"Validation error: {e.message}")
    print(f"Details: {e.details}")

except TaruviError as e:
    print(f"SDK error: {e.message} (status: {e.status_code})")

The SDK provides comprehensive error handling. See specific API documentation for error details.

Next Steps​

Now that you've completed the quickstart:

🔐 Authentication​

Learn about different authentication methods and patterns.

Authentication Guide →

📖 Examples Cookbook​

Browse 20+ real-world code examples.

Examples →

📚 Data Service API​

Learn how to query and manipulate data with the SDK.

Data Service →

🗄️ Storage API​

Upload and manage files using the storage SDK.

Storage API →

Getting Help​