🇯🇵 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.

$3

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 section
- 💡 Have an idea? Share it in Discussions
- 🚀 Want a new database? Request it through Feature Requests
- 📖 Need help? Ask questions in Discussions

$3

Hayai is open-source and welcomes contributions! Whether it's:
- 🔧 Code improvements
- 📝 Documentation updates
- 🐛 Bug reports
- 💡 Feature suggestions
- 🌐 Translations

Check out our Contributing Guide 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

$3

- Node.js 18.0.0 or higher
- Docker and Docker Compose

$3

`bash
npm install -g hayai-db
`

$3

`bash
hayai --version
`

📋 Commands Reference

$3

| 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 |

$3

| 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 for complete configuration file documentation

$3

| 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

$3

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.

$3

- 🔧 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

$3

`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
`

$3

`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

📚 Usage Examples

$3

`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
`

$3

`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
`

$3

`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?

$3

- 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

$3

- Fast Setup - Databases ready in seconds
- Resource Efficient - Optimized Docker configurations
- Multi-Database - Run multiple instances simultaneously
- Environment Isolation - Clean separation between projects

$3

- 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

$3

- 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

$3

- 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

$3

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

$3

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 !Hayai Logo

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

$3

`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
``

$3

- Contributing Guide - How to contribute to the project
- Development Guide - Development setup and workflow
- .hayaidb Configuration - Declarative database configuration guide
- Backup & Snapshots - Complete backup and restoration guide

📄 License

MIT License - see 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