Skip to main content

Quick Start Guide

Two ways to stand up a backend on ekoDB: describe it to an agent (three steps, no API code) or build it by hand (the dozen steps below). New here? Start with the Introduction.

You do not have to hand-write the API below. Deploy an AI Agent next to your database, describe the backend you want, and it builds the collections and server-side functions for you. Your app calls those functions with one line. Then you go build your frontend.

🤖 With an agent🛠️ By hand
Setupdeploy a database and an agentdeploy a database
Build the backenddescribe it in chatwrite insert / get / query / update / batch yourself
Add a feature laterask for itwrite another endpoint
Your jobthe frontendthe frontend and the whole API

Three steps​

  1. Deploy a database and an AI Agent. Two deployments at app.ekodb.io, then connect the agent to the database. (Build Your First AI Agent has the click-by-click.)

  2. Describe your backend in the agent's chat:

    Build a user-management backend: a users collection with name, email, age, and role, plus a function list_developers that returns everyone whose role is developer.

    The agent creates the collection and the stored function directly in your database.

  3. Call it from your app with the SDK and your database's API key:

    import { EkoDBClient } from "@ekodb/ekodb-client";

    const client = new EkoDBClient({ baseURL: "https://my-first-db.development.google.ekodb.net", apiKey: "YOUR_API_KEY" });
    await client.init();

    const developers = await client.callFunction("list_developers");

    That is the backend done. Go build your UI; ekoDB runs the rest.

It does not stop at building​

Once your backend is live, keep talking to the agent to run it:

  • Read the logs and surface errors
  • Diagnose a bug by tracing it through the server logs to the cause
  • Test a function by calling it and checking the result
  • Add or fix an index when a query is slow
  • Scale it: spin up new deployments, convert a database to a multi-node cluster, tune node configs, and take backups
  • Schedule jobs, evolve schemas, and add features, all by asking

From the first build through production scale, the agent runs the backend so you can stay on the frontend.

Want raw control, or to see what the agent generates?

The rest of this guide is the by-hand path: deploy a database, authenticate, and write each operation (insert, query, update) yourself.

Step 1: Deploy Your Database (2 minutes)​

  1. Sign up at app.ekodb.io
  2. Click "Create Deployment" at the top of the dashboard page: app.ekodb.io/dashboard
  3. Choose the Database module (the default). The other option, AI Agent, is covered in Build Your First AI Agent.
  4. Select your region (choose the region closest to your users)
  5. Choose a machine tier (start with the free tier for testing)
  6. Set your subdomain and environment:
    • Environment Type: development
    • Subdomain: my-first-db (or any unique name)
  7. Click Create Deployment

Your database will be ready in a few minutes. You'll receive an email once it's live.

Step 2: Your Database URL​

Once properly up and running, your deployment's status will show as "Running". Your database URL will be:

https://my-first-db.development.{provider}.ekodb.net

Replace {provider} with your selected cloud provider (ex. "google").

Viewing Your Deployments

View all of your deployments at app.ekodb.io/deployments.

Click on your deployment to navigate to that deployment's information page.

That deployment's database URL can be found at the top under the subdomain (shown with "/api").

Here you can also find this deployment's API keys. You will need the Admin API key for the next step.

To copy the Admin API key: Select your deployment → "Keys" tab → Click "Load Keys" → Copy the Admin API key

Step 3: Authenticate (30 seconds)​

You authenticate with your API key. A client library takes the key and manages tokens for you, so you can skip ahead. For raw HTTP, the API key is not sent directly; you first exchange it for a short-lived access token:

use ekodb_client::Client;

let client = Client::builder()
    .base_url("https://my-first-db.development.google.ekodb.net")
    .api_key("YOUR_API_KEY")
    .build()?;

// Token is automatically managed by the client
Save Your Token

Save this token for subsequent requests. Tokens are valid for a limited time (default: 1 hour). Client libraries handle token refresh automatically.

Step 4: Insert Your First Record (1 minute)​

Let's create a user record:

use ekodb_client::Record;

let mut record = Record::new();
record.insert("name", "Alice");
record.insert("email", "alice@example.com");
record.insert("age", 30);
record.insert("role", "developer");

let result = client.insert("users", record, None).await?;

println!("Record ID: {}", result.get_string("id").unwrap_or_default());
Important

The id returned is an encrypted record ID. Save this ID - you'll need it to fetch, update, or delete this specific record.

Step 5: Get a Record (30 seconds)​

Retrieve the record you just created:

let record = client.get("users", &record_id).await?;

println!("{:?}", record);

Response (Default - Typed):

{
  "id": {
    "type": "String",
    "value": "encrypted_record_id_here"
  },
  "name": {
    "type": "String",
    "value": "Alice"
  },
  "email": {
    "type": "String",
    "value": "alice@example.com"
  },
  "age": {
    "type": "Integer",
    "value": 30
  },
  "role": {
    "type": "String",
    "value": "developer"
  }
}
Typed Responses

By default, ekoDB returns typed responses with type metadata. This provides type safety and explicit type information.

Want simpler JSON? You can switch to non-typed responses:

  • Via App: app.ekodb.io/deployments → Select your deployment → Configurations → Edit → Toggle "Use Typed Values"
  • Via API: PUT /api/config with {"use_typed_values": false}

Non-typed response example:

{
  "id": "encrypted_record_id_here",
  "name": "Alice",
  "email": "alice@example.com",
  "age": 30,
  "role": "developer"
}

Step 6: Query with Filter (30 seconds)​

You can also query records using filters instead of IDs:

use ekodb_client::QueryBuilder;

let query = QueryBuilder::new().eq("name", "Alice").build();
let results = client.find("users", query, None).await?;

println!("{:?}", results);

Response (Typed):

[
  {
    "id": {
      "type": "String",
      "value": "encrypted_record_id_here"
    },
    "name": {
      "type": "String",
      "value": "Alice"
    },
    "email": {
      "type": "String",
      "value": "alice@example.com"
    },
    "age": {
      "type": "Integer",
      "value": 30
    },
    "role": {
      "type": "String",
      "value": "developer"
    }
  }
]

Step 7: Update a Record (30 seconds)​

Update Alice's role using the encrypted ID:

client.update("users", &record_id, serde_json::json!({
    "role": "senior developer"
})).await?;
Using Record IDs

Replace {record_id} with the actual id from your insert response. This is the encrypted record ID that ekoDB uses to identify specific records.

While direct API calls work great, we recommend using our official client libraries for a better developer experience:

No Token Management Required

Client libraries automatically handle token generation and refresh for you. Simply provide your API key once, and the client manages authentication behind the scenes!

cargo add ekodb_client
# Optional: Add tokio if using #[tokio::main] in your code
# cargo add tokio --features macros
use ekodb_client::{Client, QueryBuilder, Record};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::builder()
        .base_url("https://my-first-db.development.{provider}.ekodb.net")
        .api_key("YOUR_API_KEY")
        .build()?;

    // Insert
    let mut record = Record::new();
    record.insert("name", "Bob");
    record.insert("email", "bob@example.com");
    record.insert("age", 25);
    record.insert("role", "designer");
    let user = client.insert("users", record, None).await?;
    println!("Inserted: {}", user.get_string("id").unwrap_or_default());

    // Query
    let query = QueryBuilder::new().eq("role", "designer").build();
    let users = client.find("users", query, None).await?;

    println!("{:?}", users);
    Ok(())
}

What You Just Learned​

✅ How to deploy an ekoDB database
✅ How to insert records
✅ How to query data
✅ How to update records
✅ How to use client libraries

Next Steps​

Now that you have ekoDB running, here's what to explore next:

📚 Learn by Example​

GitHub Examples Repository - 129 in all languages:

  • Rust, Python, TypeScript, JavaScript, Go, Kotlin
  • Client library examples (using official SDKs) and direct HTTP examples (raw REST API calls)
  • CRUD operations, search, batch operations, functions, and more
  • Complete working code you can copy and run

Choose Your Path​

Building a Web/Mobile App? → Client Libraries Guide - Type-safe SDKs for your language

Using REST API Directly? → Basic Operations - Complete API reference

Need Advanced Features? → Batch Operations - High-performance bulk operations
→ Transactions - Atomic, durable multi-document transactions
→ Functions - Stored procedures

Building an AI Application? → Chat & RAG - Chat with your data using the database's built-in RAG
→ Vector Search & Embeddings - Semantic similarity search
→ Search - Full-text search capabilities

Want autonomous AI? → Build Your First AI Agent - Deploy an AI Agent that connects to this database and runs tools, goals, and scheduled tasks
→ AI Agents - What agents are and how they work

Want to Understand the Architecture? → White Paper - Deep dive into ekoDB's design

Common Next Tasks​

  1. Set up proper authentication: Authentication Guide
  2. Define schemas: Add validation and constraints to your collections
  3. Add indexes: Optimize query performance
  4. Enable WebSockets: Real-time data updates
  5. Set up Ripple: Multi-region replication

Need Help?​

Ready to build something amazing? Let's go! 🚀