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)

Some comments may only be visible to logged-in visitors. Sign in to view all comments.