Getting Started with OstrichDB CLI

The OstrichDB CLI is a powerful, lightweight database management tool built from scratch and written in Odin. It provides an intuitive query structure, hierarchical data organization, and built-in security systems, making it ideal for developers seeking an easy-to-use, flexible, high-performance database solution directly from the terminal.

Overview

What is the OstrichDB CLI?

The OstrichDB CLI is a terminal-based database management system that offers:

Direct Terminal Access: Manage your database directly from the command line
Intuitive Query Language: Simple, readable query syntax using dot notation
Hierarchical Data Structure: Organized data in Collections → Clusters → Records
Built-in Security: User authentication, role-based access, and database encryption
Multiple Interaction Methods: CLI queries, HTTP server, and natural language processing
High Performance: Native compiled code for maximum speed
Cross-Platform: Support for macOS and Linux systems

Key Features

🖥️ Three Ways to Interact:
- Manual query entry via command-line interface
- Built-in HTTP server for client applications
- Experimental natural language processing
🔐 Security First: User authentication, role-based access, database permissions and encryption
📊 Hierarchical Data: Custom three-level data structure (Collections → Clusters → Records)
📁 File Import: CSV and JSON file importing capabilities
🔗 Query Chaining: Execute multiple queries in sequence
⚡ Performance Tools: Built-in benchmarking, configurations, and query history
🌐 Cross-Platform: macOS and Linux support

Understanding the Data Structure

OstrichDB organizes data into three hierarchical levels:

Data Hierarchy

Collection (.ostrichdb files)
└── Cluster (Named groups with IDs)
    └── Record (name:type:value format)

Collections:

Database files with .ostrichdb extension
Top-level containers for related data
Can be encrypted, locked, or isolated

Clusters:

Groups of related records within collections
Given a name and ID upon creation
Logical organization within collections

Records:

Smallest unit of data storage
Format: [name] : [type] : [value]
Strongly typed with validation

Practical Example

# A company database structure
staff.ostrichdb                    # Collection
├── engineering                    # Cluster
│   ├── team_lead: STRING: "Alice" # Record
│   ├── members: []STRING: "Bob,Carol,Dave" # Record
│   └── budget: INTEGER: 50000     # Record
└── marketing                      # Cluster
    ├── manager: STRING: "Eve"     # Record
    └── campaigns: INTEGER: 3      # Record

Query Language Basics

CLP Structure

OstrichDB queries use CLPs (Command, Location, Parameter) tokens for clarity:

(C)ommand Token: Operation to perform (NEW, FETCH, ERASE)
(L)ocation Token: Dot notation path (collection.cluster.record)
(P)arameter Token: Additional modifiers (OF_TYPE, WITH, TO)

Basic Query Examples

# Create a new record
NEW staff.engineering.team_lead OF_TYPE STRING WITH "Alice"

# Fetch data
FETCH staff.engineering.team_lead

# Create with automatic structure
NEW inventory.electronics.laptops OF_TYPE INTEGER WITH 25

# Rename objects
RENAME staff.engineering TO development

# Count objects
COUNT RECORDS

# Get help
HELP NEW

First Steps

1. Start the CLI

After installation, launch OstrichDB:

./main.bin

2. Create Your First Database

# Create a simple user database
NEW users.active.john_doe OF_TYPE STRING WITH "John Doe"
NEW users.active.john_email OF_TYPE STRING WITH "john@example.com"
NEW users.active.john_age OF_TYPE INTEGER WITH 30

# View the data structure
TREE

# Fetch user data
FETCH users.active.john_doe
FETCH users.active

3. Explore Basic Operations

# Create additional records
NEW users.active.jane_doe OF_TYPE STRING WITH "Jane Smith"
NEW users.inactive.old_user OF_TYPE STRING WITH "Former Employee"

# Count records in different clusters
COUNT RECORDS IN users.active
COUNT RECORDS IN users.inactive

# Get collection information
SIZE_OF users
COUNT CLUSTERS IN users

# Search for records
WHERE john

4. Learn Query Chaining

# Execute multiple operations together
NEW products.electronics.laptop OF_TYPE INTEGER WITH 5 && FETCH products.electronics.laptop

# Chain operations across different collections
NEW inventory.warehouse.location OF_TYPE STRING WITH "Building A" && COUNT RECORDS IN inventory.warehouse && TREE

Three Interaction Methods

1. Direct CLI Queries

The primary method - enter queries directly in the terminal:

OstrichDB> NEW blog.posts.welcome OF_TYPE STRING WITH "Welcome to my blog!"
OstrichDB> FETCH blog.posts.welcome
OstrichDB> COUNT RECORDS IN blog.posts

2. HTTP Server Mode

Enable the built-in server for application integration:

# Start the server
OstrichDB> SERVE

# Server runs on default port 8080
# Make HTTP requests from your applications
curl http://localhost:8080/api/...

3. Natural Language Processing (Experimental)

Use natural language queries:

# Start the agent (requires server running in another terminal)
OstrichDB> AGENT

# Then use natural language
"Create a new user record for Alice with email alice@example.com"
"Show me all products in the electronics category"
"Delete the old test data"

Common Use Cases

Personal Data Management

# Personal finance tracker
NEW finances.income.salary OF_TYPE FLOAT WITH 5000.00
NEW finances.expenses.rent OF_TYPE FLOAT WITH 1200.00
NEW finances.expenses.utilities OF_TYPE []FLOAT WITH 200.00,150.00,100.00

# View financial summary
FETCH finances.income
FETCH finances.expenses

Development Project Tracking

# Project management
NEW projects.webapp.status OF_TYPE STRING WITH "In Progress"
NEW projects.webapp.team_size OF_TYPE INTEGER WITH 3
NEW projects.webapp.technologies OF_TYPE []STRING WITH "React,Node.js,OstrichDB"
NEW projects.webapp.deadline OF_TYPE DATE WITH 2024-06-15

# Track progress
FETCH projects.webapp
COUNT RECORDS IN projects.webapp

Inventory Management

# Store inventory
NEW inventory.electronics.laptops OF_TYPE INTEGER WITH 25
NEW inventory.electronics.phones OF_TYPE INTEGER WITH 50
NEW inventory.books.fiction OF_TYPE INTEGER WITH 200
NEW inventory.books.technical OF_TYPE INTEGER WITH 75

# Check stock levels
FETCH inventory.electronics
COUNT COLLECTIONS
SIZE_OF inventory

Session Management

User Authentication

# Create new user (if needed)
NEW USER

# Login/logout
# (Authentication handled automatically on startup)
LOGOUT

# View command history
HISTORY

# Clear session
CLEAR

Session Tools

# View current data structure
TREE

# Check performance
BENCHMARK

# Get version information
VERSION

# Exit the CLI
EXIT

Best Practices

1. Naming Conventions

Use clear, descriptive names:

# Good naming
NEW company.employees.john_smith_email OF_TYPE STRING WITH "john@company.com"
NEW inventory.products.laptop_dell_xps OF_TYPE INTEGER WITH 10

# Avoid unclear names
NEW stuff.things.data OF_TYPE STRING WITH "something"

2. Data Organization

Structure data logically:

# Organize by domain
NEW users.active.*
NEW users.inactive.*
NEW products.electronics.*
NEW products.books.*

# Group related data
NEW blog.posts.*
NEW blog.comments.*
NEW blog.authors.*

3. Use Query Chaining Efficiently

# Efficient: Related operations together
NEW users.staff.alice OF_TYPE STRING WITH "Alice Johnson" && NEW users.staff.alice_role OF_TYPE STRING WITH "Developer" && COUNT RECORDS IN users.staff

# Less efficient: Separate queries for related data
NEW users.staff.alice OF_TYPE STRING WITH "Alice Johnson"
NEW users.staff.alice_role OF_TYPE STRING WITH "Developer"
COUNT RECORDS IN users.staff

4. Regular Maintenance

# Regular housekeeping
COUNT COLLECTIONS
SIZE_OF large_collection
VALIDATE collection_name

# Create backups
BACKUP important_collection

# Monitor performance
BENCHMARK collection_operations

Getting Help

Built-in Help System

# General help
HELP

# Specific command help
HELP NEW
HELP FETCH
HELP COUNT

# View all available commands
HELP COMMANDS

Troubleshooting

# Validate collections for errors
VALIDATE collection_name

# Check data structure
TREE

# View command history for debugging
HISTORY

# Restart if needed
RESTART

Next Steps

Now that you understand the basics:

Install OstrichDB CLI - Set up your development environment
Learn Query Structure - Master the CLP system and dot notation
Explore Commands - Complete reference of all available commands
Understand Data Types - Work with different data types effectively
Configure Your Setup - Customize OstrichDB for your workflow

The OstrichDB CLI provides a powerful, direct way to manage hierarchical data with an intuitive query language. Whether you’re prototyping, managing personal data, or building applications, the CLI offers the flexibility and performance you need.