Installation

Prerequisites

Before installing a client library, make sure you have:

1. ✅ Deployed an ekoDB instance - See Getting Started
2. ✅ Retrieved your API key - See Authentication
3. ✅ Your database URL - Format: https://{SUBDOMAIN}.{ENVIRONMENT}.{PROVIDER}.ekodb.io

Installation by Language

🦀 Rust

Rust Installation

Requirements:

• Rust 1.70 or later
• Tokio runtime for async operations

Install via Cargo:

cargo add ekodb_client tokio

Or add to Cargo.toml:

[dependencies]
ekodb_client = "0.1"
tokio = { version = "1", features = ["full"] }
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"

Verify Installation:

use ekodb_client::Client;

fn main() {
    println!("ekoDB Rust client installed successfully!");
}

🐍 Python

Python Installation

Requirements:

• Python 3.8 or later
• pip package manager

Install via pip:

pip install ekodb-client

tip

You can also use pip install ekodb_client - PyPI normalizes package names, so both work identically.

Install in a virtual environment (recommended):

# Create virtual environment
python -m venv venv

# Activate (Linux/macOS)
source venv/bin/activate

# Activate (Windows)
venv\Scripts\activate

# Install ekodb-client
pip install ekodb-client

Verify Installation:

import ekodb_client
print("ekoDB Python client installed successfully!")
print(f"Version: {ekodb_client.__version__}")

Supported Platforms:

• Linux (x86_64, aarch64)
• macOS (Intel, Apple Silicon)
• Windows (via source distribution)
• FreeBSD (x86_64, aarch64)

📘 TypeScript

TypeScript/JavaScript Installation

Requirements:

• Node.js 16 or later
• npm, yarn, or pnpm

Install via npm:

npm install @ekodb/ekodb-client

Install via yarn:

yarn add @ekodb/ekodb-client

Install via pnpm:

pnpm add @ekodb/ekodb-client

Verify Installation:

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

console.log("ekoDB TypeScript client installed successfully!");

TypeScript Configuration:

The package includes TypeScript definitions. Make sure your tsconfig.json has:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "lib": ["ES2020"],
    "esModuleInterop": true
  }
}

🔷 Go

Go Installation

Requirements:

• Go 1.21 or later

Install via go get:

go get github.com/ekoDB/ekodb-client-go

Initialize your module (if needed):

go mod init your-project-name
go get github.com/ekoDB/ekodb-client-go

Verify Installation:

package main

import (
    "fmt"
    "github.com/ekoDB/ekodb-client-go"
)

func main() {
    fmt.Println("ekoDB Go client installed successfully!")
}

Update to latest version:

go get -u github.com/ekoDB/ekodb-client-go

🟣 Kotlin

Kotlin Installation

Requirements:

• JDK 17 or later
• Gradle or Maven

Install via Gradle (Kotlin DSL):

dependencies {
    implementation("io.ekodb:ekodb-client-kt:0.1.0")
}

Install via Gradle (Groovy):

dependencies {
    implementation 'io.ekodb:ekodb-client-kt:0.1.0'
}

Install via Maven:

<dependency>
    <groupId>io.ekodb</groupId>
    <artifactId>ekodb-client-kt</artifactId>
    <version>0.1.0</version>
</dependency>

Verify Installation:

import io.ekodb.client.EkoDBClient

fun main() {
    println("ekoDB Kotlin client installed successfully!")
}

📦 JavaScript

JavaScript Installation

Requirements:

• Node.js 16 or later
• npm, yarn, or pnpm

Install via npm:

npm install @ekodb/ekodb-client

Install via yarn:

yarn add @ekodb/ekodb-client

Install via pnpm:

pnpm add @ekodb/ekodb-client

Verify Installation:

const { EkoDBClient } = require("@ekodb/ekodb-client");

console.log("ekoDB JavaScript client installed successfully!");

ES Modules:

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

console.log("ekoDB JavaScript client installed successfully!");

Configuration

After installation, configure your client with your database URL and API key:

🦀 Rust

use ekodb_client::Client;
use std::env;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::builder()
        .base_url(env::var("EKODB_URL")?)
        .api_key(env::var("EKODB_API_KEY")?)
        .timeout(std::time::Duration::from_secs(30))
        .max_retries(3)
        .build()?;
    
    // Client is ready to use
    Ok(())
}

🐍 Python

import os
from ekodb_client import Client

client = Client.new(
    os.getenv("EKODB_URL"),
    os.getenv("EKODB_API_KEY"),
    should_retry=True,
    max_retries=3,
    timeout_secs=30
)

# Client is ready to use

📘 TypeScript

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

const client = new EkoDBClient({
  baseURL: process.env.EKODB_URL!,
  apiKey: process.env.EKODB_API_KEY!,
  shouldRetry: true,
  maxRetries: 3,
  timeout: 30000
});

await client.init();
// Client is ready to use

🔷 Go

import (
    "os"
    "github.com/ekoDB/ekodb-client-go"
)

client := ekodb.NewClient(
    os.Getenv("EKODB_URL"),
    os.Getenv("EKODB_API_KEY"),
)

// Client is ready to use

🟣 Kotlin

import io.ekodb.client.EkoDBClient

suspend fun main() {
    val client = EkoDBClient.Builder()
        .baseUrl(System.getenv("EKODB_URL"))
        .apiKey(System.getenv("EKODB_API_KEY"))
        .timeout(30000)
        .maxRetries(3)
        .build()
    
    // Client is ready to use
}

📦 JavaScript

const { EkoDBClient } = require("@ekodb/ekodb-client");

const client = new EkoDBClient({
  baseURL: process.env.EKODB_URL,
  apiKey: process.env.EKODB_API_KEY,
  shouldRetry: true,
  maxRetries: 3,
  timeout: 30000
});

await client.init();
// Client is ready to use

Environment Variables

We recommend using environment variables for configuration:

# .env file
EKODB_URL=https://your-subdomain.production.aws.ekodb.io
EKODB_API_KEY=your-api-key-here

Troubleshooting

🦀 Rust

Compilation errors

Make sure you have the latest version:

cargo update ekodb_client

Feature flag issues

If you get TLS-related errors, check your feature flags:

# Use rustls (default)
ekodb_client = "0.1"

# Or use native-tls
ekodb_client = { version = "0.1", default-features = false, features = ["native-tls"] }

🐍 Python

"No module named 'ekodb_client'"

Make sure the package is installed:

# Both of these work (PyPI normalizes names)
pip install ekodb-client
pip install ekodb_client

Then import with underscore:

import ekodb_client  # ✅ Correct
from ekodb_client import Client  # ✅ Correct

Common mistake:

import ekodb-client  # ❌ Wrong - hyphens are invalid in Python imports

Platform-specific issues

If you encounter build errors, you may need to install from source:

pip install ekodb-client --no-binary ekodb-client

📘 TypeScript

"Cannot find module '@ekodb/ekodb-client'"

Make sure the package is installed:

npm list @ekodb/ekodb-client

If not installed, run:

npm install @ekodb/ekodb-client

TypeScript errors

Ensure your tsconfig.json has proper settings:

{
  "compilerOptions": {
    "esModuleInterop": true,
    "moduleResolution": "node"
  }
}

🔷 Go

"package github.com/ekoDB/ekodb-client-go is not in GOROOT"

Run go mod tidy:

go mod tidy

Module not found

Make sure you're using Go modules:

go mod init your-project
go get github.com/ekoDB/ekodb-client-go

Version conflicts

If you have version conflicts, update to the latest:

go get -u github.com/ekoDB/ekodb-client-go

🟣 Kotlin

"Could not find io.ekodb:ekodb-client-kt"

Make sure Maven Central is in your repositories:

repositories {
    mavenCentral()
}

If the package was just published, wait a few minutes for Maven Central to sync.

Gradle sync issues

Try refreshing Gradle dependencies:

./gradlew clean build --refresh-dependencies

Compilation errors with coroutines

Make sure you have the coroutines dependency:

dependencies {
    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.9.0")
}

JDK version mismatch

Ensure you're using JDK 17 or later:

kotlin {
    jvmToolchain(17)
}

📦 JavaScript

"Cannot find module '@ekodb/ekodb-client'"

Make sure the package is installed:

npm list @ekodb/ekodb-client

If not installed, run:

npm install @ekodb/ekodb-client

ES Module vs CommonJS

The package supports both. For ES modules:

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

For CommonJS:

const { EkoDBClient } = require("@ekodb/ekodb-client");

Node.js version

Ensure you're using Node.js 16 or later:

node --version

Need Help?

• 📧 Email: support@ekodb.io
• 🐛 Issues: GitHub Issues
• 📚 Examples: GitHub Repository