Built from scratch, the OstrichDB engine powers the OstrichDB CLI—a lightweight yet powerful database management tool for your terminal. Written in Odin, it features an intuitive query structure, hierarchical data organization, and built-in security systems, making it ideal for anyone seeking an easy-to-use, flexible, high-performance database solution.
- Three Ways To Interact:
- Manually enter queries via the Command-line Interface
- Enable the built-in HTTP server and interact via a client in your favorite language
- (Experimental) Use natural language queries to quickly interact with your data!(Requries a bit of setup)
- User Authentication
- User Role-Based Access
- Database permissions
- Database encryption & decryption
- Custom Hierarchical Data Structure
- .CSV & .JSON file importing
- Dot Notation Syntax when using the serverless CLI
- Query Chaining
- Built-in benchmarking, configurations, and user query history
- macOS & Linux Support
- A Unix-based system (macOS, Linux).
- The Go programming language installed, and properly set in the systems PATH. Ideal Go version:
go1.23.1 - The Odin programming language installed, built, and properly set in the system's PATH. Ideal Odin Version:
dev-2024-11:764c32fd3Note: You can achieve the previous step by following the Odin Installation Guide
-
Clone the Repository:
git clone https://github.com/Solitude-Software-Solutions/OstrichDB.git
-
Navigate to the root directory of the OstrichDB CLI project:
cd path/to/OstrichDB -
Make the Build, Run & Restart Scripts Executable:
chmod +x scripts/local_build_run.sh && chmod +x scripts/local_build.sh && chmod +x scripts/restart.sh
-
Run The Build Script:
./scripts/local_build_run.sh
-
Ensure that you have Docker installed: https://docs.docker.com/engine/install/
-
Navigate to the root directory of the OstrichDB CLI project:
cd /path/to/OstrichDB -
Build the Docker container:
docker compose build
Alternatively, build and run the container in detached mode
docker compose up -d
-
Run the OstrichDB CLI
docker exec -it ostrichdb /app/main.bin
*Note: You can find data for OstrichDB in .ostrichdb/data in the project's directory, which is mapped to /data inside the container.
You can also change the port mapping to the host machine by updating the docker-compose.yml file in case port 8080 is already in use, i.e.
ports:
- "8089:8080"
OstrichDB organizes data into three levels:
- Records: The smallest unit of data. e.g user_name, age, email. Format: [name] :[type]: [value]
- Clusters: Groups of related records. Given a name and an id upon creation.
- Collections: Database files containing clusters, Have the '.ostrichdb' extension.
From the OstrichDB CLI, queries are typically broken into three types of tokens, called CLPs, to improve readability and ensure clear instructions.
Note: Not all queries require all 3 tokens.
- (C)ommand Token: Specifies the operation to perform (e.g.,
NEW,ERASE,RENAME). - (L)ocation Token: The path using dot notation that the query will be performed on (e.g.,
foo.bar.baz). - (P)arameter Token(s): Additional parameters that change the behavior of the query (e.g.,
TO,OF_TYPE).
NEW foo.bar.baz OF_TYPE []STRINGExplanation:
NEW: Create a new data structure (Command token).foo: The first data structure always points to a collection. (Location token).bar: The second data structure always to a cluster within the collection. (Location token).baz: The third data structure is always a record within the cluster. (Location token).OF_TYPE: Specifies the data type of the record (Parameter token). Note: Only records are given data types.[]STRING: Token mapped to the Parameter token that precedes it. The record will be an array of strings.
These tokens perform a task without any additional arguments.
AGENT: Starts the OstrichDB natural language processor. Requires the server to be running in another terminal.VERSION: Displays the current version of OstrichDB.LOGOUT: Logs out the current user.EXIT: Ends the session and closes the DBMS.RESTART: Restarts the program.REBUILD: Rebuilds the DBMS and restarts the program.SERVE/SERVER: Turns on the OstrichDB server allowing http requests to be made.HELP: Displays general help information or detailed help when chained with specific tokens.TREE: Displays the entire data structure in a tree format.CLEAR: Clears the console screen.HISTORY: Shows the current users command history.DESTROY: Completeley destorys the entire DBMS. Including all databases, users, configs, and logs.BENCHMARK: Runs a benchmark test on the DBMS to test performance. Can be run with or without parameters.
These tokens are used to construct queries and require one or more additional tokens.
NEW: Create a new collection, cluster, record, or user.ERASE: Delete a collection, cluster, or record.RENAME: Rename an existing object.FETCH: Retrieve data from a collection, cluster, or record.SET: Assign a value to a record or configuration.BACKUP: Create a backup of a specific collection.PURGE: Removes all data from an object while maintaining the object structure.COUNT: Returns the number of objects within a scope. Paired with the plural form of the object type (e.g.,RECORDS,CLUSTERS).SIZE_OF: Returns the size in bytes of an object.TYPE_OF: Returns the type of a record.CHANGE_TYPE: Allows you to change the type of a record.HELP: Displays help information for a specific token.ISOLATE: Quarantines a collection file. Preventing any further changes to the fileWHERE: Searches for the location of a single or several record(s) or cluster(s). DOES NOT WORK WITH COLLECTIONS.VALIDATE: Validates a collection file for any errors or corruption.BENCHMARK: Runs a benchmark test on the DBMS to test performance. Can be run with or without parameters.LOCK: Used to change the access mode of a collection. UsingLOCK {collection_name} -rsets a collection to Read-Only. Removing the-rwill set a collection to Inaccessible.UNLOCK: Changes the access mode of a collection to the default Read-Write.ENC: Encrypts a collection.DEC: Decrypts a currently encrypted collection. Use at own discretion.IMPORT: Allows the user to import a .csv or .json files into OstrichDB.
Modifiers adjust the behavior of queries. The current supported modifiers are:
OF_TYPE: Specifies the type of a new record (e.g., INT, STR, []BOOL)WITH: Used to assign a value to a record in the same command you are creating it(e.gNEW {collection_name}.{cluster_name}.{record_name} OF_TYPE {record_type} WITH {record_value})TO: Used to assign a new value or name to a data structure or config(e.gRENAME {old_collection_name} to {new_collection_name})
OstrichDB supports query chaining, allowing you to execute multiple queries in sequence with a single input. To chain queries together add the && operator at the end of each valid query, and they will be executed in the order they appear.
Example:
RENAME foo.bar.baz TO goob && FETCH fetch foo.bar.goobWhen setting a record value, you must specify the records data type by using the OF_TYPE modifier. Some types have a shorthand notation for convenience.
INTEGER: Integer values. Short-hand:INT.STRING: Any text value longer than 1 character. Short-hand:STR.FLOAT: Floating-point numbers. Short-hand:FLT.BOOLEAN: true or false values. Short-hand:BOOL.CHAR: Single character values. No short-hand.
NOTE: When setting array values, separate each element with a comma WITHOUT spaces.
[]STRING: String arrays. Short-hand:[]STR.[]INTEGER: Integer arrays. Short-hand:[]INT.[]FLOAT: Float arrays. Short-hand:[]FLT.[]BOOLEAN: Boolean arrays. Short-hand:[]BOOL.[]CHAR: Character arrays. No short-hand.
-
DATE: Must be inYYYY-MM-DDformat. No short-hand. -
TIME: Must be inHH:MM:SSformat. No short-hand. -
DATETIME: Must be inYYYY-MM-DDTHH:MM:SSformat. No short-hand. -
[]DATE: Date arrays. Each value must follow the above format. No short-hand. -
[]TIME: Time arrays. Each value must follow the above format. No short-hand. -
[]DATETIME: Date and time arrays. Each value must follow the above format. No short-hand. -
NULL: Null value. No short-hand.Note: UUIDs can only have
0-9anda-fcharacters and must be in the formatxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. -
UUID: Universally unique identifier. Must follow the above format. No short-hand. -
[]UUID: UUID arrays. Each value must follow the above format. No short-hand.
# Create a new record:
# Note: If collection staff and cluster engineering do not exist
# Don't worry, that will be created all at once!
NEW staff.engineering.team_one OF_TYPE []STRING WITH "John","Ana","Wayne"
# Fetch the record value:
FETCH staff.engineers.team_one
# Rename a cluster:
RENAME staff.engineering TO HR
# Get the size of a cluster:
SIZE_OF staff.HR
# Erase a record:
ERASE staff.HR.team_one
# Get a count of all collections in the database:
COUNT COLLECTIONS
#Get help information for a specific token:
HELP {TOKEN_NAME}
# Get general help information
HELP
# Create a new user
NEW USEROstrichDB has a configuration file that allows the user to customize certain aspects of the DBMS to their liking.
HELP_IS_VERBOSE: Decide whether help information is simple or verbose. Default isfalseSUPPRESS_ERRORS: Show or hide error messages. Default isfalseLIMIT_HISTORY: Ensure whether a users query history does or does not exceed the built in limit(100) Default istrueAUTO_SERVE: Determines if the built-in OstrichDB server automatically starts the moment the user logs in. Default istrueLIMIT_SESSION_TIME: Determines if the CLI session timer is enabled or disabled. If enabled a user can only be logged in for 24hrs. Default istrue
Note: ALL configs must be set using the following query:
Config values can only be true or false
SET CONFIG {CONFIG_NAME} TO {VALUE}
- A new and improved engine!
- More configuration options
- Several new Command tokens:
EXPORT: Export data to various formatsRESTORE: Restores a collection backup in the place of the original collectionMERGE: Combine multiple collections or clusters into one
- OstrichDB web application
- Windows support
- External API support for even more programming languages!
- Integration with the planned Feather query language!
Please refer to the CONTRIBUTING.md for detailed guidelines on how to contribute.
OstrichDB is released under the Apache License 2.0. For the full license text, see Apache License 2.0.