• Prerequisites
  • Create a database
  • Review your database
• Quickstart
  • Populate your data
  • Query your data
  • Update your data
  • List transactions
  • Get change feed (cdc)
• Wrapping up

Lite Kv is designed for developers who need a globally distributed, immutable key-value store. This quickstart guide will walk you through creating a Lite Kv database, managing it through the dashboard, populating it via API, and querying it with your applications.

Prerequisites

Lite Kv is framework-agnostic and can be used with any backend service that can make HTTP requests. Ensure you have

• Lite Kv account with API access
• Any HTTP client (like curl, Postman or built into your preferred programming language)

Create a database

• Log into your Litebase dashboard.
• Go to the "Kv" section, click on "Create database".
• Name your database main or another preferred name, click "Create".

Review your database

Your newly created main database is now ready to handle all data operations. Environment variables for connecting to your database will be automatically generated, the only environment variable you need is LITEKV_API_TOKEN.

Quickstart

Let's kick things off by getting your data up and running with Lite Kv. With just a few HTTPs requests, you'll start seeing how Lite Kv simplifies transactions and ensures global consistency.

Populate your data

First things first, let's add some data into your Lite Kv database. Imagine you have two users, and you awn to store their details. Here's a simple way to do it:

cURL

curl -X POST https://kv.litebase.io/v1/write \
    -H "Authorization: Bearer {LITEKV_API_TOKEN}" \
    -H "Content-Type: application/json" \
    -d '{
        "data": {
            "user:1": {
                "id": 1,
                "name": "Anakin Skywalker"
            },
            "user:2": {
                "id": 2,
                "name": "Obi-Wan Kenobi"
            }
        }
    }'

curl -X POST https://kv.litebase.io/v1/write \
    -H "Authorization: Bearer {LITEKV_API_TOKEN}" \
    -H "Content-Type: application/json" \
    -d '{
        "data": {
            "user:1": {
                "id": 1,
                "name": "Anakin Skywalker"
            },
            "user:2": {
                "id": 2,
                "name": "Obi-Wan Kenobi"
            }
        }
    }'

Typescript

// Ensure you're running this in an environment
// that supports fetch, or have a polyfill.
// Replace with your actual API token.
const LITEKV_API_TOKEN = "YOUR_LITEKV_API_TOKEN";

const response = await fetch("https://kv.litebase.io/v1/write", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${LITEKV_API_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    data: {
      "user:1": { id: 1, name: "Anakin Skywalker" },
      "user:2": { id: 2, name: "Obi-Wan Kenobi" },
    },
  }),
});

const data = await response.json();
console.log(data);

// Ensure you're running this in an environment
// that supports fetch, or have a polyfill.
// Replace with your actual API token.
const LITEKV_API_TOKEN = "YOUR_LITEKV_API_TOKEN";

const response = await fetch("https://kv.litebase.io/v1/write", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${LITEKV_API_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    data: {
      "user:1": { id: 1, name: "Anakin Skywalker" },
      "user:2": { id: 2, name: "Obi-Wan Kenobi" },
    },
  }),
});

const data = await response.json();
console.log(data);

python

import requests
import json

## Replace with your actual API token
LITEKV_API_TOKEN = 'YOUR_LITEKV_API_TOKEN'

def write_data_to_lite_kv():
    headers = {
        'Authorization': f'Bearer {LITEKV_API_TOKEN}',
        'Content-Type': 'application/json'
    }
    payload = {
        'data': {
            "user:1": { "id": 1, "name": "Anakin Skywalker" },
            "user:2": { "id": 2, "name": "Obi-Wan Kenobi" }
        }
    }
    response = requests.post('https://kv.litebase.io/v1/write',
        headers=headers,
        data=json.dumps(payload))
    print(response.json())

write_data_to_lite_kv()

import requests
import json

## Replace with your actual API token
LITEKV_API_TOKEN = 'YOUR_LITEKV_API_TOKEN'

def write_data_to_lite_kv():
    headers = {
        'Authorization': f'Bearer {LITEKV_API_TOKEN}',
        'Content-Type': 'application/json'
    }
    payload = {
        'data': {
            "user:1": { "id": 1, "name": "Anakin Skywalker" },
            "user:2": { "id": 2, "name": "Obi-Wan Kenobi" }
        }
    }
    response = requests.post('https://kv.litebase.io/v1/write',
        headers=headers,
        data=json.dumps(payload))
    print(response.json())

write_data_to_lite_kv()

When you send off this command, Lite Kv handles it in a transaction way. You'll get a response something like this:

{
  "status": "ok",
  "tx": 1,
  "duration": "759ns"
}

{
  "status": "ok",
  "tx": 1,
  "duration": "759ns"
}

Here , tx is like your receipt number, providing the transaction took place. Lite Kv is cool because it doesn't just save your data; it saves the whole history of changes, making sure that everyone around the world sees the same sequence of updates.

Query your data

Now, let's see what Lite Kv knows about your users:

bash

## This is how you ask Lite Kv to spill the beans on user:1 and user:2
curl -X GET https://kv.litebase.io/v1/read?keys=user:1,user:2 \
    -H "Authorization: Bearer {LITEKV_API_TOKEN}" \
    -H "Content-Type: application/json"

## This is how you ask Lite Kv to spill the beans on user:1 and user:2
curl -X GET https://kv.litebase.io/v1/read?keys=user:1,user:2 \
    -H "Authorization: Bearer {LITEKV_API_TOKEN}" \
    -H "Content-Type: application/json"

typescript

const response = await fetch(
  "https://kv.litebase.io/v1/read?keys=user:1,user:2",
  {
    method: "GET",
    headers: {
      Authorization: `Bearer ${LITEKV_API_TOKEN}`,
      "Content-Type": "application/json",
    },
  }
);

const data = await response.json();

const response = await fetch(
  "https://kv.litebase.io/v1/read?keys=user:1,user:2",
  {
    method: "GET",
    headers: {
      Authorization: `Bearer ${LITEKV_API_TOKEN}`,
      "Content-Type": "application/json",
    },
  }
);

const data = await response.json();

python

headers = {
    'Authorization': f'Bearer {LITEKV_API_TOKEN}',
    'Content-Type': 'application/json'
}

response = requests.get('https://kv.litebase.io/v1/read?keys=user:1,user:2', headers=headers)

print(response.json())

headers = {
    'Authorization': f'Bearer {LITEKV_API_TOKEN}',
    'Content-Type': 'application/json'
}

response = requests.get('https://kv.litebase.io/v1/read?keys=user:1,user:2', headers=headers)

print(response.json())

And Lite Kv will tell you all about them, including which transaction their details come from:

{
  "tx": 1,
  "versions": {
    "user:1": 1,
    "user:2": 1
  },
  "data": {
    "user:1": {
      "id": 1,
      "name": "Anakin Skywalker"
    },
    "user:2": {
      "id": 2,
      "name": "Obi-Wan Kenobi"
    }
  },
  "duration": "146ns"
}

{
  "tx": 1,
  "versions": {
    "user:1": 1,
    "user:2": 1
  },
  "data": {
    "user:1": {
      "id": 1,
      "name": "Anakin Skywalker"
    },
    "user:2": {
      "id": 2,
      "name": "Obi-Wan Kenobi"
    }
  },
  "duration": "146ns"
}

This response provides a wealth of information:

• tx The unique identifier for the transaction in which these records were last updated or confirmed.
• versions Each key within the database has a version number. In this case, both user:1 and user:2 are at version 1, implying that they have been involved in a single transaction each, which is likely the initial write operation.
• data Contains the actual data that you requested. It reflects the latest state of the records for user:1 and user:2.
• duration This is a performance metric indicating the time taken by Lite Kv to execute your read request. In this example, it took just 146 nanoseconds to retrieve the data.

The response not only assures you of the successful storage of your data but also gives you insights into the efficiency and performance of Lite Kv’s data retrieval process.

Update your data

What if user:1 has embraced the dark side? Let's update their name:

bash

curl -X POST https://kv.litebase.io/v1/write \
    -H "Authorization: Bearer {LITEKV_API_TOKEN}" \
    -H "Content-Type: application/json" \
    -d '{
        "read_set": {
            "user:1": 1,
        },
        "data": {
            "user:1": {
                "id": 1,
                "name": "Darth Vader"
            }
        }
    }'

curl -X POST https://kv.litebase.io/v1/write \
    -H "Authorization: Bearer {LITEKV_API_TOKEN}" \
    -H "Content-Type: application/json" \
    -d '{
        "read_set": {
            "user:1": 1,
        },
        "data": {
            "user:1": {
                "id": 1,
                "name": "Darth Vader"
            }
        }
    }'

typescript

const LITEKV_API_TOKEN = "your_api_token"; // Replace with your actual API token

async function writeToLiteKV() {
  const url = "https://kv.litebase.io/v1/write";
  const headers = {
    Authorization: `Bearer ${LITEKV_API_TOKEN}`,
    "Content-Type": "application/json",
  };

  const data = {
    data: {
      "user:1": {
        id: 1,
        name: "Anakin Skywalker",
      },
      "user:2": {
        id: 2,
        name: "Obi-Wan Kenobi",
      },
    },
  };

  try {
    const response = await fetch(url, {
      method: "POST",
      headers: headers,
      body: JSON.stringify(data),
    });

    if (response.ok) {
      const result = await response.json();
      console.log(result);
    } else {
      console.error("Failed to write to LiteKV");
    }
  } catch (error) {
    console.error("An error occurred:", error);
  }
}

writeToLiteKV();

const LITEKV_API_TOKEN = "your_api_token"; // Replace with your actual API token

async function writeToLiteKV() {
  const url = "https://kv.litebase.io/v1/write";
  const headers = {
    Authorization: `Bearer ${LITEKV_API_TOKEN}`,
    "Content-Type": "application/json",
  };

  const data = {
    data: {
      "user:1": {
        id: 1,
        name: "Anakin Skywalker",
      },
      "user:2": {
        id: 2,
        name: "Obi-Wan Kenobi",
      },
    },
  };

  try {
    const response = await fetch(url, {
      method: "POST",
      headers: headers,
      body: JSON.stringify(data),
    });

    if (response.ok) {
      const result = await response.json();
      console.log(result);
    } else {
      console.error("Failed to write to LiteKV");
    }
  } catch (error) {
    console.error("An error occurred:", error);
  }
}

writeToLiteKV();

python

import requests

LITEKV_API_TOKEN = "your_api_token"  ## Replace with your actual API token
url = "https://kv.litebase.io/v1/write"
headers = {
    "Authorization": f"Bearer {LITEKV_API_TOKEN}",
    "Content-Type": "application/json",
}

data = {
    "data": {
        "user:1": {
            "id": 1,
            "name": "Anakin Skywalker",
        },
        "user:2": {
            "id": 2,
            "name": "Obi-Wan Kenobi",
        },
    }
}

try:
    response = requests.post(url, headers=headers, json=data)

    if response.status_code == 200:
        result = response.json()
        print(result)
    else:
        print("Failed to write to LiteKV")
except Exception as e:
    print("An error occurred:", e)

import requests

LITEKV_API_TOKEN = "your_api_token"  ## Replace with your actual API token
url = "https://kv.litebase.io/v1/write"
headers = {
    "Authorization": f"Bearer {LITEKV_API_TOKEN}",
    "Content-Type": "application/json",
}

data = {
    "data": {
        "user:1": {
            "id": 1,
            "name": "Anakin Skywalker",
        },
        "user:2": {
            "id": 2,
            "name": "Obi-Wan Kenobi",
        },
    }
}

try:
    response = requests.post(url, headers=headers, json=data)

    if response.status_code == 200:
        result = response.json()
        print(result)
    else:
        print("Failed to write to LiteKV")
except Exception as e:
    print("An error occurred:", e)

Once the command is executed, Lite Kv processes your update as part of a new transaction:

{
  "tx": 2,
  "duration": "621ns"
}

{
  "tx": 2,
  "duration": "621ns"
}

Let's dissect the response:

• tx This is new transaction id, moving from 1 to 2 indicates that a new transaction has been recorded in the system.
• duration The speed at which Lite Kv executed your update request, which is impressively swift at 621 nanoseconds.

Your database is now up-to-date, reflecting the latest narrative of user:1’s journey from Anakin Skywalker to Darth Vader.

List transactions

Transactions in Lite Kv are like diary entries for your database, each one telling a story about a change that occurred. To peek into this diary, here's what you'd do:

bash

## Let's check out the latest gossip (aka transactions)
curl -X GET https://kv.litebase.io/v1/tx \
    -H "Authorization: Bearer {LITEKV_API_TOKEN}" \
    -H "Content-Type: application/json"

## Let's check out the latest gossip (aka transactions)
curl -X GET https://kv.litebase.io/v1/tx \
    -H "Authorization: Bearer {LITEKV_API_TOKEN}" \
    -H "Content-Type: application/json"

typescript

const LITEKV_API_TOKEN = "your_api_token"; // Replace with your actual API token

async function queryLiteKVData() {
  const keys = "user:1,user:2";
  const url = `https://kv.litebase.io/v1/read?keys=${keys}`;
  const headers = {
    Authorization: `Bearer ${LITEKV_API_TOKEN}`,
    "Content-Type": "application/json",
  };

  const response = await fetch(url, {
    method: "GET",
    headers: headers,
  });
  return await response.json();
}

queryLiteKVData();

const LITEKV_API_TOKEN = "your_api_token"; // Replace with your actual API token

async function queryLiteKVData() {
  const keys = "user:1,user:2";
  const url = `https://kv.litebase.io/v1/read?keys=${keys}`;
  const headers = {
    Authorization: `Bearer ${LITEKV_API_TOKEN}`,
    "Content-Type": "application/json",
  };

  const response = await fetch(url, {
    method: "GET",
    headers: headers,
  });
  return await response.json();
}

queryLiteKVData();

python

import requests

LITEKV_API_TOKEN = "your_api_token"  ## Replace with your actual API token
url = "https://kv.litebase.io/v1/tx"

headers = {
    "Authorization": f"Bearer {LITEKV_API_TOKEN}",
    "Content-Type": "application/json",
}

response = requests.get(url, headers=headers)

import requests

LITEKV_API_TOKEN = "your_api_token"  ## Replace with your actual API token
url = "https://kv.litebase.io/v1/tx"

headers = {
    "Authorization": f"Bearer {LITEKV_API_TOKEN}",
    "Content-Type": "application/json",
}

response = requests.get(url, headers=headers)

Lite Kv will returns a list of transactions, providing a comprehensive overview of recent activities:

[
  {
    "tx": 2,
    "read_set": {
      "user:1": 1
    },
    "write_set": ["user:1"],
    "data": {
      "user:1": {
        "id": 1,
        "name": "Darth Vader"
      }
    }
  },
  {
    "tx": 1,
    "read_set": {},
    "write_set": ["user:1", "user:2"],
    "data": {
      "user:1": {
        "id": 1,
        "name": "Anakin Skywalker"
      },
      "user:2": {
        "id": 2,
        "name": "Obi-Wan Kenobi"
      }
    }
  }
]

[
  {
    "tx": 2,
    "read_set": {
      "user:1": 1
    },
    "write_set": ["user:1"],
    "data": {
      "user:1": {
        "id": 1,
        "name": "Darth Vader"
      }
    }
  },
  {
    "tx": 1,
    "read_set": {},
    "write_set": ["user:1", "user:2"],
    "data": {
      "user:1": {
        "id": 1,
        "name": "Anakin Skywalker"
      },
      "user:2": {
        "id": 2,
        "name": "Obi-Wan Kenobi"
      }
    }
  }
]

In this detailed report, you'll observe the following:

• tx The transaction identifier, which is a sequential number representing each unique operation.
• read_set The set of data that was read during the transaction, providing context for the changes.
• write_set: A list of keys that were written to or updated in this transaction.
• data The actual data that was modified. In the case of transaction tx: 2, it shows the evolution of user:1 from Anakin Skywalker to Darth Vader.

These transactions are immutable, serving as an unalterable history of your database's state changes. They are invaluable for auditing, debugging, and synchronizing distributed systems. With Lite Kv, you have the power to look back in time and understand the narrative of your data's evolution—a narrative that is consistent and reliable, thanks to the platform's strong consistency guarantees.

Get change feed (cdc)

The Change Data Capture (CDC) captures every moment of your data's life. Whenever a change occurs, CDC is there to snap a picture and record it. To access this feed, you'd do something like this:

bash

## Time to catch those data changes red-handed!
curl -X GET https://kv.litebase.io/v1/cdc \
    -H "Authorization: Bearer {LITEKV_API_TOKEN}" \
    -H "Content-Type: application/json"

## Time to catch those data changes red-handed!
curl -X GET https://kv.litebase.io/v1/cdc \
    -H "Authorization: Bearer {LITEKV_API_TOKEN}" \
    -H "Content-Type: application/json"

typescript

// Replace with your actual LiteKV API token
const LITEKV_API_TOKEN = 'your_api_token_here'

const headers = {
const response = await fetch('https://kv.litebase.io/v1/cdc', {
    method: 'GET',
    headers: {
        'Authorization': `Bearer ${LITEKV_API_TOKEN}`,
        'Content-Type': 'application/json'
    }
})

const data = await response.json()

// Replace with your actual LiteKV API token
const LITEKV_API_TOKEN = 'your_api_token_here'

const headers = {
const response = await fetch('https://kv.litebase.io/v1/cdc', {
    method: 'GET',
    headers: {
        'Authorization': `Bearer ${LITEKV_API_TOKEN}`,
        'Content-Type': 'application/json'
    }
})

const data = await response.json()

python

import requests

## Replace with your actual LiteKV API token
LITEKV_API_TOKEN = 'your_api_token_here'

response = requests.get('https://kv.litebase.io/v1/cdc',
    headers={
        'Authorization': f'Bearer {LITEKV_API_TOKEN}',
        'Content-Type': 'application/json'
    })
data = response.json()

import requests

## Replace with your actual LiteKV API token
LITEKV_API_TOKEN = 'your_api_token_here'

response = requests.get('https://kv.litebase.io/v1/cdc',
    headers={
        'Authorization': f'Bearer {LITEKV_API_TOKEN}',
        'Content-Type': 'application/json'
    })
data = response.json()

What you get is a chronicle of changes, each with a unique CDC ID (cdcid), the transaction it belongs to, and the details of what was altered:

[
  {
    "cdcid": 3,
    "tx": 2,
    "key": "user:1",
    "value": {
      "id": 1,
      "name": "Darth Vader"
    }
  },
  {
    "cdcid": 2,
    "tx": 1,
    "key": "user:2",
    "value": {
      "id": 2,
      "name": "Obi-Wan Kenobi"
    }
  },
  {
    "cdcid": 1,
    "tx": 1,
    "key": "user:1",
    "value": {
      "id": 1,
      "name": "Anakin Skywalker"
    }
  }
]

[
  {
    "cdcid": 3,
    "tx": 2,
    "key": "user:1",
    "value": {
      "id": 1,
      "name": "Darth Vader"
    }
  },
  {
    "cdcid": 2,
    "tx": 1,
    "key": "user:2",
    "value": {
      "id": 2,
      "name": "Obi-Wan Kenobi"
    }
  },
  {
    "cdcid": 1,
    "tx": 1,
    "key": "user:1",
    "value": {
      "id": 1,
      "name": "Anakin Skywalker"
    }
  }
]

With cdc, you can effectively replay or reverse changes, which is invaluable for debugging or syncing data across systems.

Wrapping up

As we conclude this quickstart guide, you have witnessed how Lite Kv is not just a mere repository for data but also a custodian of its chronology. It’s a testament to Lite Kv’s capacity to not only store but also narrate the evolution of your data across time.

You are now well-equipped to harness the full power of Lite Kv. Whether it's adding new data, updating existing entries, or monitoring changes with granular precision, Lite Kv empowers you to do so with confidence and ease.

We encourage you to continue exploring, secure in the knowledge that Lite Kv is more than a service—it's a time-honored guardian of your digital narrative. Happy coding! 🌟