______ _ _ ____________
| ___ \ | | | | | _ \ ___ \
| |_/ / __ _| |_| |_ ___ _ __| | | | |_/ /
| ___ \/ _' | __| __/ _ \ '__| | | | ___ \
| |_/ / (_| | |_| || __/ | | |/ /| |_/ /
\____/ \__,_|\__|\__\___|_| |___/ \____/
batterdb operates as a stack-based database. It functions by pushing Elements onto Stacks. Consequently, you can only interact with the topmost Element, while the remaining elements are stored beneath it.
---
title: Overview of batterDB
---
graph LR
REPO["Repository"] --> DB1[(database 1)]
DB1 --> DB1S1([stack 1])
DB1S1 --> DB1S1V1{{element 1}}
REPO --> DB2[(database 2)]
DB2 --> DB2S1([stack 2])
DB2S1 --> DB2S1V1{{element 3}}
DB2S1V1 --> DB2S1V2{{element 4}}
DB2 --> DB2S2([stack 3])
DB2S2 --> DB2S2V1{{element 2}}
batterdb is a server program that initializes the Repository. It provides an HTTP interface for external users, allowing operations such as creating or deleting Databases, Stacks, and performing stack (PUSH, POP, etc.) operations on Elements.
The Repository is the central component of batterdb. It houses all the Databases that you create, and listens for incoming connections.
A Database is a collection of Stacks. You have the flexibility to create multiple Databases, each operating independently of the others.
A Stack represents a linear data structure that contains Elements, based on the LIFO (Last in, First out) principle, and in which only these operations are allowed:
PUSH: Introduces an Element into the Stack.POP: Removes the topmost Element of the Stack.PEEK: Returns the topmost Element of the Stack, but this is not modified.SIZE: Returns the size of the Stack.FLUSH: Delete all Elements of the Stack, leaving it empty.
Every operation applied to a Stack has a O(1) complexity, and will block further incoming or concurrent operations, which ensures consistent responses within a reasonable amount of time.
An Element refers to a data unit that can be pushed into a Stack. It is compatible with the JSON format. Examples of data types that batterdb can handle:
- Number:
42,3.14,.333,3.7E-5. - String:
foo,PilaDB,\thello\nworld, - Boolean:
true,false. - Array:
["🍎","🍊","🍋"],[{"foo":false}, true, 3, "bar"]. - Object:
{},{"key": "Value"},{"bob":{"age":32,"married":false,"comments":{}}}. null.
Windows, macOS, and Linux binaries are available. You can download the latest release from the releases page.
Alternativelm, you can install the project from source by:
go install github.com/jh125486/batterdb@latestUsage: batterdb <command> [flags]
A simple stacked-based database 🔋.
Flags:
-h, --help Show context-sensitive help.
-p, --port=1205 Port to listen on.
-s, --store Persist the database to disk.
--repo-file=".batterdb.gob" The file to persist the database to.
-S, --secure Enable HTTPS.
-v, --version Show version.
Commands:
server [flags]
Start the server.
open-api [flags]
Output the OpenAPI specification version.
Run "batterdb <command> --help" for more information on a command.Note: The --store flag will store the repository by default as .batterdb.gob in the current directory, but you can change it with the --repo-file flag.
batterdb uses OpenAPI to document its API, and when the server is running it is available at http://localhost:1205/openapi.yaml.
To dump the spec for use in generators, you can use the open-api subcommand flag with the version (3.1 or 3.0.3) you want to use. The specs are also available committed to the repo:
Generating a client is beyond the scope of this README, but many are available at OpenAPI Generator.
This project is inspired by PilaDB, and the name is a pun on "stack" ➟ "pila" ➟ "battery" ➟ "battery DB" ➟ "batterdb".