{"id":21725734,"url":"https://github.com/Archetype-Dynamics/OstrichDB-CLI","last_synced_at":"2025-07-18T18:30:57.446Z","repository":{"id":245202935,"uuid":"817126064","full_name":"Solitude-Software-Solutions/OstrichDB","owner":"Solitude-Software-Solutions","description":"WIP | A document-based NoSQL, JSON-esque database for local machine use","archived":false,"fork":false,"pushed_at":"2024-10-24T02:42:31.000Z","size":1348,"stargazers_count":24,"open_issues_count":20,"forks_count":5,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-10-25T12:06:42.710Z","etag":null,"topics":["database","document-database","hacktoberfest","hacktoberfest-accepted","linux","macos","nosql","odin"],"latest_commit_sha":null,"homepage":"","language":"Odin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Solitude-Software-Solutions.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-06-19T04:43:03.000Z","updated_at":"2024-10-23T02:19:03.000Z","dependencies_parsed_at":"2024-06-27T04:39:13.442Z","dependency_job_id":"329ffb03-72fc-417a-b9b4-2de7c3aebb2d","html_url":"https://github.com/Solitude-Software-Solutions/OstrichDB","commit_stats":null,"previous_names":["schoolyb/ostrich","solitude-software-solutions/ostrichdb","solitude-solutions/ostrichdb"],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Solitude-Software-Solutions%2FOstrichDB","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Solitude-Software-Solutions%2FOstrichDB/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Solitude-Software-Solutions%2FOstrichDB/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Solitude-Software-Solutions%2FOstrichDB/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Solitude-Software-Solutions","download_url":"https://codeload.github.com/Solitude-Software-Solutions/OstrichDB/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":226434131,"owners_count":17624399,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["database","document-database","hacktoberfest","hacktoberfest-accepted","linux","macos","nosql","odin"],"created_at":"2024-11-26T03:19:57.887Z","updated_at":"2025-07-18T18:30:57.438Z","avatar_url":"https://github.com/Solitude-Software-Solutions.png","language":"Odin","funding_links":[],"categories":["Libraries"],"sub_categories":["Webdev"],"readme":"# **OstrichDB CLI**\n\nBuilt from scratch, the OstrichDB engine powers the OstrichDB CLI—a lightweight yet powerful database management tool for your terminal. Written in [Odin](https://odin-lang.org/), 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.\n\n\n---\n\n## **Key Features**\n\n- Three Ways To Interact:\n  - Manually enter queries via the Command-line Interface\n  - Enable the built-in HTTP server and interact via a client in your favorite language\n  - (Experimental) Use natural language queries to quickly interact with your data!(Requries a bit of setup)\n- User Authentication\n- User Role-Based Access\n- Database permissions\n- Database encryption \u0026 decryption\n- Custom Hierarchical Data Structure\n- .CSV \u0026 .JSON file importing\n- Dot Notation Syntax when using the serverless CLI\n- Query Chaining\n- Built-in benchmarking, configurations, and user query history\n- macOS \u0026 Linux Support\n\n## **Installation**\n\n### **Prerequisites:**\n- A Unix-based system (macOS, Linux).\n- The [Go](https://go.dev/) programming language installed, and properly set in the systems PATH. Ideal Go version: `go1.23.1`\n- The [Odin](https://odin-lang.org/) programming language installed, built, and properly set in the system's PATH. Ideal Odin Version: `dev-2024-11:764c32fd3`\n*Note: You can achieve the previous step by following the [Odin Installation Guide](https://odin-lang.org/docs/install/)*\n\n\n### Building and Running The OstrichDB CLI Locally:\n#### **Steps:**\n\n1. **Clone the Repository**:\n   ```bash\n   git clone https://github.com/Solitude-Software-Solutions/OstrichDB.git\n   ```\n\n2. **Navigate to the root directory of the OstrichDB CLI project**:\n   ```bash\n   cd path/to/OstrichDB\n   ```\n\n3. **Make the Build, Run \u0026 Restart Scripts Executable**:\n   ```bash\n   chmod +x scripts/local_build_run.sh \u0026\u0026 chmod +x scripts/local_build.sh \u0026\u0026 chmod +x scripts/restart.sh\n   ```\n\n4. **Run The Build Script**:\n   ```bash\n   ./scripts/local_build_run.sh\n   ```\n\n\n### Building and Running The OstrichDB CLI in a Docker Container:\n#### **Steps:**\n1. **Ensure that you have Docker installed**: https://docs.docker.com/engine/install/\n\n2. **Navigate to the root directory of the OstrichDB CLI project**:\n   ```bash\n   cd /path/to/OstrichDB\n   ```\n\n3. **Build the Docker container**:\n    ```bash\n    docker compose build\n    ```\n    Alternatively, build and run the container in detached mode\n    ```bash\n    docker compose up -d\n    ```\n4. **Run the OstrichDB CLI**\n    ```bash\n    docker exec -it ostrichdb /app/main.bin\n    ```\n*Note: You can find data for OstrichDB in `.ostrichdb/data` in the project's directory, which is mapped to `/data` inside the container.\nYou 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.\n```\nports:\n  - \"8089:8080\"\n```\n\n---\n\n\n## **Data Structure Overview**\n\nOstrichDB organizes data into three levels:\n\n- **Records**: The smallest unit of data. e.g user_name, age, email. Format: [name] :[type]: [value]\n- **Clusters**: Groups of related records. Given a name and an id upon creation.\n- **Collections**: Database files containing clusters, Have the '.ostrichdb' extension.\n\n---\n\n## **Query Structure (CLPs)**\n\nFrom the OstrichDB CLI, queries are typically broken into **three types of tokens**, called **CLPs**, to improve readability and ensure clear instructions.\n\n**Note:** Not all queries require all 3 tokens.\n\n1. **(C)ommand Token**: Specifies the operation to perform (e.g., `NEW`, `ERASE`, `RENAME`).\n2. **(L)ocation Token**: The path using dot notation that the query will be performed on (e.g., `foo.bar.baz`).\n3. **(P)arameter Token(s)**: Additional parameters that change the behavior of the query (e.g., `TO`, `OF_TYPE`).\n\n---\n\n### **Query Walkthrough**\n\n```bash\nNEW foo.bar.baz OF_TYPE []STRING\n```\nExplanation:\n- **`NEW`**: Create a new data structure (Command token).\n- **`foo`**: The first data structure always points to a collection. (Location token).\n- **`bar`**: The second data structure always to a cluster within the collection. (Location token).\n- **`baz`**: The third data structure is always a record within the cluster. (Location token).\n- **`OF_TYPE`**: Specifies the data type of the record (Parameter token). Note: Only records are given data types.\n- **`[]STRING`**: Token mapped to the Parameter token that precedes it. The record will be an array of strings.\n\n---\n\n## **Supported Command Tokens**\n\n### **Single-Token Operations**\nThese tokens perform a task without any additional arguments.\n\n- **`AGENT`**: Starts the OstrichDB natural language processor. Requires the server to be running in another terminal.\n- **`VERSION`**: Displays the current version of OstrichDB.\n- **`LOGOUT`**: Logs out the current user.\n- **`EXIT`**: Ends the session and closes the DBMS.\n- **`RESTART`**: Restarts the program.\n- **`REBUILD`**: Rebuilds the DBMS and restarts the program.\n- **`SERVE/SERVER`**: Turns on the OstrichDB server allowing http requests to be made.\n- **`HELP`**: Displays general help information or detailed help when chained with specific tokens.\n- **`TREE`**: Displays the entire data structure in a tree format.\n- **`CLEAR`**: Clears the console screen.\n- **`HISTORY`**: Shows the current users command history.\n- **`DESTROY`**: Completeley destorys the entire DBMS. Including all databases, users, configs, and logs.\n- **`BENCHMARK`**: Runs a benchmark test on the DBMS to test performance. Can be run with or without parameters.\n\n---\n\n### **Multi-Token Tokens**\nThese tokens are used to construct queries and require one or more additional tokens.\n\n- **`NEW`**: Create a new collection, cluster, record, or user.\n- **`ERASE`**: Delete a collection, cluster, or record.\n- **`RENAME`**: Rename an existing object.\n- **`FETCH`**: Retrieve data from a collection, cluster, or record.\n- **`SET`**: Assign a value to a record or configuration.\n- **`BACKUP`**: Create a backup of a specific collection.\n- **`PURGE`**: Removes all data from an object while maintaining the object structure.\n- **`COUNT`**: Returns the number of objects within a scope. Paired with the plural form of the object type (e.g., `RECORDS`, `CLUSTERS`).\n- **`SIZE_OF`**: Returns the size in bytes of an object.\n- **`TYPE_OF`**: Returns the type of a record.\n- **`CHANGE_TYPE`**: Allows you to change the type of a record.\n- **`HELP`**: Displays help information for a specific token.\n- **`ISOLATE`**: Quarantines a collection file. Preventing any further changes to the file\n- **`WHERE`**: Searches for the location of a single or several record(s) or cluster(s). DOES NOT WORK WITH COLLECTIONS.\n- **`VALIDATE`**: Validates a collection file for any errors or corruption.\n- **`BENCHMARK`**: Runs a benchmark test on the DBMS to test performance. Can be run with or without parameters.\n- **`LOCK`**: Used to change the access mode of a collection. Using `LOCK {collection_name} -r` sets a collection to Read-Only. Removing the `-r` will set a collection to Inaccessible.\n- **`UNLOCK`**: Changes the access mode of a collection to the default Read-Write.\n- **`ENC`** : Encrypts a collection.\n- **`DEC`** : Decrypts a currently encrypted collection.  Use at own discretion.\n- **`IMPORT`**: Allows the user to import a .csv or .json files into OstrichDB.\n---\n\n### **Parameters**\nModifiers adjust the behavior of queries. The current supported modifiers are:\n\n- **`OF_TYPE`**: Specifies the type of a new record (e.g., INT, STR, []BOOL)\n- **`WITH`**: Used to assign a value to a record in the same command you are creating it(e.g `NEW {collection_name}.{cluster_name}.{record_name} OF_TYPE {record_type} WITH {record_value}`)\n- **`TO`**: Used to assign a new value or name to a data structure or config(e.g `RENAME {old_collection_name} to {new_collection_name}`)\n\n### **Query Chaining**\nOstrichDB supports query chaining, allowing you to execute multiple queries in sequence with a single input. To chain queries together add the `\u0026\u0026` operator at the end of each valid query, and they will be executed in the order they appear.\n\nExample:\n```bash\nRENAME foo.bar.baz TO goob \u0026\u0026 FETCH fetch foo.bar.goob\n```\n\n\n## **Supported Record Data Type Tokens**\nWhen 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.\n\n### Primary data types include:\n  - **`INTEGER`**: Integer values. Short-hand: `INT`.\n  - **`STRING`**: Any text value longer than 1 character. Short-hand: `STR`.\n  - **`FLOAT`**: Floating-point numbers. Short-hand: `FLT`.\n  - **`BOOLEAN`**: true or false values. Short-hand: `BOOL`.\n  - **`CHAR`**: Single character values. No short-hand.\n\n### Complex data types include:\n*NOTE: When setting array values, separate each element with a comma WITHOUT spaces.*\n  - **`[]STRING`**: String arrays. Short-hand: `[]STR`.\n  - **`[]INTEGER`**: Integer arrays. Short-hand: `[]INT`.\n  - **`[]FLOAT`**: Float arrays. Short-hand: `[]FLT`.\n  - **`[]BOOLEAN`**: Boolean arrays. Short-hand: `[]BOOL`.\n  - **`[]CHAR`**: Character arrays. No short-hand.\n\n\n### Other supported data types include:\n  - **`DATE`**: Must be in `YYYY-MM-DD` format. No short-hand.\n  - **`TIME`**: Must be in `HH:MM:SS` format. No short-hand.\n  - **`DATETIME`**: Must be in `YYYY-MM-DDTHH:MM:SS` format. No short-hand.\n  - **`[]DATE`**: Date arrays. Each value must follow the above format. No short-hand.\n  - **`[]TIME`**: Time arrays. Each value must follow the above format. No short-hand.\n  - **`[]DATETIME`**: Date and time arrays. Each value must follow the above format. No short-hand.\n  - **`NULL`**: Null value. No short-hand.\n\n    *Note: UUIDs can only have `0-9` and `a-f` characters and must be in the format `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`.*\n  - **`UUID`**: Universally unique identifier. Must follow the above format. No short-hand.\n  - **`[]UUID`**: UUID arrays. Each value must follow the above format. No short-hand.\n\n---\n\n## **Usage Examples**\n   ```bash\n\n   # Create a new record:\n   # Note: If collection staff and cluster engineering do not exist\n   # Don't worry, that will be created all at once!\n   NEW staff.engineering.team_one OF_TYPE []STRING WITH \"John\",\"Ana\",\"Wayne\"\n   # Fetch the record value:\n   FETCH staff.engineers.team_one\n   # Rename a cluster:\n   RENAME staff.engineering TO HR\n   # Get the size of a cluster:\n   SIZE_OF staff.HR\n   # Erase a record:\n   ERASE staff.HR.team_one\n   # Get a count of all collections in the database:\n   COUNT COLLECTIONS\n   #Get help information for a specific token:\n   HELP {TOKEN_NAME}\n   # Get general help information\n   HELP\n   # Create a new user\n   NEW USER\n   ```\n---\n\n## **Configs**\nOstrichDB has a configuration file that allows the user to customize certain aspects of the DBMS to their liking.\n\n- **`HELP_IS_VERBOSE`**: Decide whether help information is simple or verbose. Default is `false`\n- **`SUPPRESS_ERRORS`**: Show or hide error messages. Default is `false`\n- **`LIMIT_HISTORY`**: Ensure whether a users query history does or does not exceed the built in limit(100) Default is `true`\n- **`AUTO_SERVE`**: Determines if the built-in OstrichDB server automatically starts the moment the user logs in. Default is `true`\n- **`LIMIT_SESSION_TIME`**: Determines if the CLI session timer is enabled or disabled. If enabled a user can only be logged in for 24hrs. Default is `true`\n\n**Note: ALL configs must be set using the following query:**\nConfig values can only be `true` or `false`\n\n```\nSET CONFIG {CONFIG_NAME} TO {VALUE}\n```\n\n---\n## **Future Plans**\n\n- A new and improved engine!\n- More configuration options\n- Several new Command tokens:\n  - `EXPORT`: Export data to various formats\n  - `RESTORE`: Restores a collection backup in the place of the original collection\n  - `MERGE`: Combine multiple collections or clusters into one\n- OstrichDB web application\n- Windows support\n- External API support for even more programming languages!\n- Integration with the planned Feather query language!\n\n---\n\n## **Contributing**\n\nPlease refer to the [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines on how to contribute.\n\n---\n\n## **License**\n\nOstrichDB is released under the **Apache License 2.0**. For the full license text, see [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FArchetype-Dynamics%2FOstrichDB-CLI","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FArchetype-Dynamics%2FOstrichDB-CLI","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FArchetype-Dynamics%2FOstrichDB-CLI/lists"}