https://github.com/hitoshyamamoto/hayai
Instantly create and manage local SQL, NoSQL, and Vector databases with Docker using a fast and extensible CLI tool for backend developers.
https://github.com/hitoshyamamoto/hayai
backend cli database database-management developer-tools
Last synced: 23 days ago
JSON representation
Instantly create and manage local SQL, NoSQL, and Vector databases with Docker using a fast and extensible CLI tool for backend developers.
- Host: GitHub
- URL: https://github.com/hitoshyamamoto/hayai
- Owner: hitoshyamamoto
- License: mit
- Created: 2025-07-07T03:41:06.000Z (12 months ago)
- Default Branch: master
- Last Pushed: 2025-07-09T05:17:20.000Z (12 months ago)
- Last Synced: 2025-10-11T16:08:03.888Z (9 months ago)
- Topics: backend, cli, database, database-management, developer-tools
- Language: TypeScript
- Homepage:
- Size: 1.81 MB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
Hayai โก
Instantly create and manage local databases with one command
## ๐ฏ๐ต About the Name
**Hayai** (้ใ) means "fast" or "quick" in Japanese. This CLI tool lives up to its name by instantly creating and managing local databases with a single command.
## ๐ What is Hayai?
Fast, modern CLI tool for managing local SQL and NoSQL databases with Docker. Built for backend developers who need quick database instances for development and testing.
**Perfect for:**
- ๐๏ธ **Local Development** - Spin up databases instantly
- ๐งช **Testing Environments** - Isolated database instances
- ๐ฌ **Experimentation** - Try different databases quickly
- ๐ **Learning** - Explore various database technologies
## ๐ Support & Community
If you find Hayai useful, please consider giving us a โญ **Star** on GitHub! It helps us understand that people are using and appreciating the project, and motivates us to keep improving it.
### ๐ฌ Get Involved
We're building Hayai to be the best database management tool for developers, and your input matters:
- **๐ Found a bug?** Report it in our [Issues](https://github.com/hitoshyamamoto/hayai/issues) section
- **๐ก Have an idea?** Share it in [Discussions](https://github.com/hitoshyamamoto/hayai/discussions)
- **๐ Want a new database?** Request it through [Feature Requests](https://github.com/hitoshyamamoto/hayai/issues/new?template=feature_request.md)
- **๐ Need help?** Ask questions in [Discussions](https://github.com/hitoshyamamoto/hayai/discussions/categories/q-a)
### ๐ค Contributing
Hayai is open-source and welcomes contributions! Whether it's:
- ๐ง Code improvements
- ๐ Documentation updates
- ๐ Bug reports
- ๐ก Feature suggestions
- ๐ Translations
Check out our [Contributing Guide](CONTRIBUTING.md) to get started!
## โก Quick Start
```bash
# Install globally
npm install -g hayai-db
# Initialize a PostgreSQL database
hayai init
# Start all databases
hayai start
# Open admin dashboards
hayai studio
```
## ๐ฏ Key Features
- **๐ 100% Open-Source**: Only includes databases with permissive licenses
- **โก One Command Setup**: Initialize any database with a single command
- **๐ณ Docker-Powered**: Automated container management with health checks
- **๐ง Smart Port Management**: Intelligent port allocation (5000-6000 range)
- **๐ Admin Dashboards**: Built-in web interfaces for database management
- **๐ Environment Integration**: Automatic `.env` file updates with connection URIs
- **โจ Modern CLI**: Interactive prompts with beautiful output
## ๐ฆ Supported Databases
All databases are **100% open-source** with permissive licenses:
SQL Databases (2)
- **PostgreSQL** (PostgreSQL License) - Most popular open-source relational database
- **MariaDB** (GPL v2) - MySQL community fork with enhanced features
Analytics Databases (1)
- **DuckDB** (MIT) - Analytics-focused columnar SQL database for OLAP workloads
Embedded Databases (2)
- **SQLite** (Public Domain) - Lightweight embedded SQL database
- **LMDB** (OpenLDAP Public License) - Ultra-fast memory-mapped embedded key-value store
Key-Value Databases (3)
- **Redis** (BSD 3-Clause) - High-performance in-memory key-value store
- **LevelDB** (BSD) - High-performance embedded key-value storage library
- **TiKV** (Apache 2.0) - CNCF graduated distributed transactional key-value store
Wide Column Databases (1)
- **Apache Cassandra** (Apache 2.0) - Distributed wide column store
Vector Databases (3)
- **Qdrant** (Apache 2.0) - Vector database with REST API
- **Weaviate** (BSD 3-Clause) - Vector search engine with ML models
- **Milvus** (Apache 2.0) - Vector database for AI applications
Graph Databases (2)
- **ArangoDB** (Apache 2.0) - Multi-model database (graph, document, key-value)
- **NebulaGraph** (Apache 2.0) - Distributed graph database with millisecond latency
Search Databases (2)
- **Meilisearch** (MIT) - Modern full-text search engine
- **Typesense** (GPL v3) - Fast, typo-tolerant search engine
Time Series Databases (6)
- **InfluxDB 2.x** (MIT) - Modern time series platform with full features
- **InfluxDB 3 Core** (MIT/Apache 2.0) - Latest generation time series database
- **TimescaleDB** (Timescale License) - PostgreSQL-based time series database
- **QuestDB** (Apache 2.0) - High-performance time series with SQL support
- **VictoriaMetrics** (Apache 2.0) - Prometheus-compatible metrics database
- **Apache HoraeDB** (Apache 2.0) - Cloud-native distributed time series database
**Total: 22 databases across 9 categories**
## ๐ ๏ธ Installation
### Prerequisites
- **Node.js** 18.0.0 or higher
- **Docker** and **Docker Compose**
### Install Hayai
```bash
npm install -g hayai-db
```
### Verify Installation
```bash
hayai --version
```
## ๐ Commands Reference
### Core Commands
| Command | Description | Example |
|---------|-------------|---------|
| `hayai init` | Initialize a new database instance | `hayai init -n mydb -e postgresql` |
| `hayai start [name]` | Start database instances | `hayai start` or `hayai start mydb` |
| `hayai stop [name]` | Stop database instances | `hayai stop` or `hayai stop mydb` |
| `hayai list` | List all database instances | `hayai list --running` |
| `hayai studio [name]` | Open admin dashboards | `hayai studio mydb` |
### Configuration Commands
| Command | Description | Example |
|---------|-------------|---------|
| `hayai init --config .hayaidb` | Initialize from configuration file | `hayai init --config .hayaidb` |
| `hayai validate --config .hayaidb` | Validate configuration file | `hayai validate --config .hayaidb` |
| `hayai config check` | Check configuration syntax | `hayai config check` |
๐ **See [HAYAIDB.md](HAYAIDB.md) for complete configuration file documentation**
### Management Commands
| Command | Description | Example |
|---------|-------------|---------|
| `hayai remove ` | Remove database instance | `hayai remove mydb --force` |
| `hayai logs ` | View database logs | `hayai logs mydb --follow` |
| `hayai snapshot ` | Create database snapshot | `hayai snapshot mydb --compress` |
| `hayai clone ` | Clone database instances | `hayai clone --from prod --to staging` |
| `hayai merge ` | Merge two databases bidirectionally | `hayai merge --source dbA --target dbB --preview` |
๐ธ **For complete backup and snapshot documentation, see: [ABOUT_BACKUP.md](ABOUT_BACKUP.md)**
### Detailed Usage
hayai init - Initialize Database
```bash
# Interactive mode
hayai init
# Quick setup
hayai init -n mydb -e postgresql -p 5432 -y
# With admin dashboard
hayai init --admin-dashboard
# Custom configuration
hayai init -n cache -e redis -p 6379 --memory 512mb
```
**Options:**
- `-n, --name ` - Database name
- `-e, --engine ` - Database engine
- `-p, --port ` - Port number
- `-y, --yes` - Skip confirmations
- `--admin-dashboard` - Enable admin dashboard
hayai start - Start Databases
```bash
# Start all databases
hayai start
# Start specific database
hayai start mydb
# Start with custom options
hayai start --detach --timeout 60
```
hayai clone - Clone Database Instances
```bash
# Simple 1:1 clone
hayai clone --from prod --to staging
hayai clone -f prod -t staging -y
# Clone to multiple databases (1:N)
hayai clone --from prod --to-multiple "test1,test2,test3"
hayai clone -f prod -tm "dev,staging,qa" -y
# Preview clone without executing
hayai clone -f prod -t staging --dry-run
# Force overwrite existing databases
hayai clone -f prod -t staging --force -y
```
**Options:**
- `-f, --from ` - Source database name
- `-t, --to ` - Target database name (1:1 clone)
- `-tm, --to-multiple ` - Target database names (comma-separated, 1:N clone)
- `-y, --confirm` - Skip confirmation prompt
- `--force` - Overwrite existing target databases
- `--dry-run` - Show what would be cloned without executing
**Supported Engines:** PostgreSQL, MariaDB, Redis, SQLite, DuckDB, and all other engines with generic data copying.
hayai merge - Merge Database Instances
```bash
# Preview merge operation
hayai merge --source dbA --target dbB --preview
hayai merge -s dbA -t dbB --preview
# Execute merge operation
hayai merge --source dbA --target dbB --execute
hayai merge -s dbA -t dbB --execute
# Force merge without confirmation
hayai merge -s dbA -t dbB --execute --force
```
**Options:**
- `-s, --source ` - Source database name
- `-t, --target ` - Target database name
- `--preview` - Preview the merge operation without executing
- `--execute` - Execute the merge operation
- `--backup-both` - Create backups of both databases before merging
- `--force` - Skip confirmation prompts
**How Merge Works:**
- Data from source is copied to target
- Data from target is copied to source
- Both databases end up with combined data
- Conflicts are resolved automatically when possible
**Supported Engines:** PostgreSQL (SQL-level), MariaDB (SQL-level), Redis (key-level with REPLACE), others (generic file-based).
hayai list - List Databases
```bash
# List all databases
hayai list
# Show only running databases
hayai list --running
# JSON output
hayai list --format json
# Detailed view
hayai list --verbose
```
## ๐ง Configuration
Hayai uses a `hayai.config.yaml` file for global configuration:
```yaml
version: '1.0.0'
docker:
network_name: hayai-network
compose_file: docker-compose.yml
data_directory: ./data
logging:
level: info
file: hayai.log
defaults:
port_range:
start: 5000
end: 6000
volume_driver: local
restart_policy: unless-stopped
```
## ๐ .hayaidb - Declarative Database Configuration
The `.hayaidb` file provides a **declarative approach** to database management, allowing you to define multiple databases with their configurations in a single file.
### โ
**Key Benefits**
- **๐ง Centralized Configuration**: Define all databases in one place
- **๐ Declarative Setup**: Specify what you want, not how to achieve it
- **๐ Reproducible Environments**: Share configurations across team members
- **โก Batch Operations**: Initialize, start, or stop multiple databases at once
### ๐ **Quick Example**
```yaml
version: "1.0"
project: my-app
databases:
main-postgres:
engine: postgresql
port: 5432
environment:
POSTGRES_DB: myapp
POSTGRES_USER: admin
POSTGRES_PASSWORD: password
cache-redis:
engine: redis
port: 6379
environment:
REDIS_PASSWORD: password
metrics-influxdb2:
engine: influxdb2
port: 8086
environment:
DOCKER_INFLUXDB_INIT_USERNAME: admin
DOCKER_INFLUXDB_INIT_PASSWORD: password
DOCKER_INFLUXDB_INIT_ORG: myapp-org
DOCKER_INFLUXDB_INIT_BUCKET: metrics
```
### ๐ง **Usage**
```bash
# Initialize all databases from .hayaidb
hayai init --config .hayaidb
# Start all databases
hayai start --config .hayaidb
# Stop all databases
hayai stop --config .hayaidb
```
๐ **For complete documentation and examples, see: [HAYAIDB.md](HAYAIDB.md)**
## ๐ Usage Examples
### Development Environment Setup
```bash
# Main database
hayai init -n maindb -e postgresql -y
# Caching layer
hayai init -n cache -e redis -y
# Search functionality
hayai init -n search -e meilisearch -y
# Start all services
hayai start
# Check status
hayai list
```
### AI/ML Development Stack
```bash
# Vector database for embeddings
hayai init -n vectors -e qdrant -y
# Time series for metrics
hayai init -n metrics -e influxdb3 -y
# Traditional data storage
hayai init -n data -e postgresql -y
# Launch everything
hayai start
hayai studio # Open all dashboards
```
### Microservices Testing
```bash
# User service database
hayai init -n users -e postgresql -p 5432 -y
# Session store
hayai init -n sessions -e redis -p 6379 -y
# Analytics database
hayai init -n analytics -e questdb -p 9000 -y
# Graph relationships
hayai init -n graph -e arangodb -p 8529 -y
```
## ๐ Why Choose Hayai?
### ๐ฏ Developer Experience
- **Interactive CLI** - Beautiful prompts with validation
- **Smart Defaults** - Sensible configuration out of the box
- **Error Handling** - Clear error messages and recovery suggestions
- **Auto-completion** - Shell completion support
### ๐ Performance & Flexibility
- **Fast Setup** - Databases ready in seconds
- **Resource Efficient** - Optimized Docker configurations
- **Multi-Database** - Run multiple instances simultaneously
- **Environment Isolation** - Clean separation between projects
### ๐ Comprehensive Database Support
- **SQL Databases** - PostgreSQL, MariaDB, SQLite, DuckDB
- **Time Series** - InfluxDB 2.x, InfluxDB 3 Core, TimescaleDB, QuestDB, VictoriaMetrics, HoraeDB
- **Vector Search** - Qdrant, Weaviate, Milvus
- **Search Engines** - Meilisearch, Typesense
- **Specialized** - Redis, Cassandra, ArangoDB, LevelDB
## ๐ Dependency Management
### Core Dependencies
- **chalk** ^5.4.1 - Terminal colors and styling
- **commander** ^12.1.0 - Command-line interface framework
- **dockerode** ^4.0.7 - Docker Engine API client
- **inquirer** ^9.2.12 - Interactive command-line prompts
- **ora** ^8.2.0 - Loading spinners and progress indicators
- **yaml** ^2.8.0 - YAML parser and stringifier
### Development Dependencies
- **typescript** ^5.8.3 - TypeScript compiler
- **@types/node** ^22.10.6 - Node.js type definitions
- **eslint** ^8.57.1 - Code linting
- **jest** ^29.7.0 - Testing framework
All dependencies are regularly updated and security-audited.
## ๐จ Project Branding
### Logo Usage
The Hayai logo is located in the `assets/` directory:
- **Main Logo**: `assets/logo_hayai.png` - Primary logo for README and documentation
- **Complete Logo**: `assets/complete_logo_hayai.png` - Full logo with text
- **Format**: PNG with transparent background
- **Usage**: Free for open-source projects, attribution appreciated
### GitHub Repository Settings
To use the logo in different GitHub contexts:
1. **Social Preview**: Repository Settings โ General โ Social Preview (1280x640px)
2. **README Header**: Already configured using `logo_hayai.png`
3. **Issues/PRs**: Reference using ``
## ๐ค Contributing
We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
### Development Setup
```bash
# Clone the repository
git clone https://github.com/hitoshyamamoto/hayai.git
# Install dependencies
npm install
# Run in development mode
npm run dev
# Run tests
npm test
# Run linting
npm run lint
```
### ๐ Documentation
- [Contributing Guide](CONTRIBUTING.md) - How to contribute to the project
- [Development Guide](DEVELOPMENT.md) - Development setup and workflow
- [.hayaidb Configuration](HAYAIDB.md) - Declarative database configuration guide
- [Backup & Snapshots](ABOUT_BACKUP.md) - Complete backup and restoration guide
## ๐ License
MIT License - see [LICENSE](LICENSE) for details.
## ๐ Acknowledgments
- **Docker** - Container platform that makes everything possible
- **Open-source database communities** - For creating amazing databases
- **Node.js ecosystem** - For excellent tooling and libraries
- **Professional experience** - Real-world development needs and pain points that inspired this solution
- **Personal curiosity** - The desire to create my first own project and learn through building
---
Built to simplify and accelerate your development by hitoshyamamoto
Making database management ้ใ (hayai) since 2025