DEV Community

Water Run
Water Run

Posted on

Bat-KV: Lightweight Key-Value Store for Windows Batch

#database #programming #tooling #opensource

Bat-KV: An Ultra-Lightweight Database for Windows Batch (.bat)

Windows batch scripting is notoriously tricky, especially when it comes to persisting simple data.

Bat-KV is an open-source, single-file key-value database designed for .bat scripts. It provides the basic CRUD operations, wraps some simple APIs, and is quick to pick up.

If this project helps you, consider giving it a Star on GitHub.

GitHub

Bat-KV Basics

Storage Files

  • File Extension: .bkv (Batch Key-Value)
  • Format: One key-value pair per line, separated by a backslash \ 
  username\Alice
  age\25
  city\Beijing
Enter fullscreen mode Exit fullscreen mode
  • Default Filename: _BATKV.bkv
  • Encoding: ANSI recommended for platform compatibility
  • Key Constraints:
    • Only English letters, digits, and underscores allowed
    • Maximum length of 36 characters
    • Case-sensitive

Naming Conventions

  • Public Functions: Start with BKV., e.g., BKV.New, BKV.Fetch
  • Private Functions: Start with BKV.Private., not intended for external use
  • Internal Variables: Start with BKV.Inner., not intended for external access
  • Return Variables:
    • BKV_STATUS: Execution result (OK / NotOK)
    • BKV_RESULT: Data returned by queries (e.g., BKV.Fetch value)
    • BKV_ERR: Error detail if failure occurs, in the format Bat-KV ERR: [message]

Download & Installation

Getting Bat-KV

  1. Go to the GitHub Release page
  2. Download Bat-KV.zip
  3. Extract and locate the core file Bat-KV.bat

Importing

  • Local Use: Place Bat-KV.bat in the same directory as your batch script, call it directly
  • Relative Path: If the file is in a subdirectory or parent directory, prefix the path
  • Global Use: Add the directory containing Bat-KV.bat to your system PATH environment variable

Example:

REM Current directory
call Bat-KV.bat :BKV.New

REM Subdirectory
call lib\Bat-KV.bat :BKV.New "mydata.bkv"

REM Parent directory
call ..\Bat-KV.bat :BKV.Fetch "username"
Enter fullscreen mode Exit fullscreen mode

Quick Start

A minimal example including creating a database, writing, reading, and deleting data:

@echo off

REM Create database
call Bat-KV.bat :BKV.New
echo Create status: %BKV_STATUS%

REM Insert data
call Bat-KV.bat :BKV.Append "name" "Alice"
call Bat-KV.bat :BKV.Append "age" "25"

REM Read data
call Bat-KV.bat :BKV.Fetch "name"
echo Name: %BKV_RESULT%

REM Check key existence
call Bat-KV.bat :BKV.Include "email"
if "%BKV_RESULT%"=="No" (
    call Bat-KV.bat :BKV.Append "email" "alice@example.com"
)

REM Delete data
call Bat-KV.bat :BKV.Remove "age"
echo Remove status: %BKV_STATUS%

pause
Enter fullscreen mode Exit fullscreen mode

API Quick Reference

BKV.New

Create a new database file. Existing files are not overwritten.

call Bat-KV.bat :BKV.New "config.bkv"
Enter fullscreen mode Exit fullscreen mode

BKV.Append

Insert or update a key-value pair.

call Bat-KV.bat :BKV.Append "username" "Alice"
Enter fullscreen mode Exit fullscreen mode

BKV.Fetch

Read the value of a given key.

call Bat-KV.bat :BKV.Fetch "username"
echo User: %BKV_RESULT%
Enter fullscreen mode Exit fullscreen mode

BKV.Remove

Remove a key-value pair. Returns success even if the key does not exist.

call Bat-KV.bat :BKV.Remove "username"
Enter fullscreen mode Exit fullscreen mode

BKV.Include

Check if a key exists.

call Bat-KV.bat :BKV.Include "db_host"
if "%BKV_RESULT%"=="No" (
    call Bat-KV.bat :BKV.Append "db_host" "localhost"
)
Enter fullscreen mode Exit fullscreen mode

Full Documentation

For complete documentation and example programs, refer to the GitHub main repository and the scripts attached to the Release.

Top comments (0)