HelixDB Docs

This guide walks through common workflows and best practices for developing with Helix CLI v2.

Local Development Workflow

Initial Setup

Create project

mkdir my-app && cd my-app
helix init

Note that helix init with no arguments defaults to making a local instance called dev.

Define schema

Edit db/schema.hx:

N::User {
  name: String,
  INDEX email: String,
  created_at: Date DEFAULT NOW
}

N::Post {
  title: String,
  content: String,
  published: Boolean DEFAULT true,
  created_at: Date DEFAULT NOW
}

Create queries

Edit db/queries.hx:

QUERY createUser(name: String, email: String) =>
  user <- AddN<User>({
    name: name,
    email: email,
  })
  RETURN user

QUERY getUserByEmail(email: String) =>
  user <- N<User>({email: email})
  RETURN user

Validate

helix check

Build and deploy

helix push dev

Test connection

curl http://localhost:6969/health

Development Iteration

When making changes during development:

# Edit your .hx files
vim db/queries.hx

# Validate changes
helix check

# Deploy changes (rebuilds automatically if needed)
helix push dev

# Check status
helix status

# View logs
docker logs helix_my-app_dev

# Stop when done
helix stop dev

Working with Multiple Instances

Create different instances for different purposes:

# Add a testing instance
helix add local --name testing

# Configure different port in helix.toml
# [local.testing]
# port = 7070

# Run both instances
helix push dev
helix push testing

# Status shows all instances
helix status

Multi-Environment Setup

Development → Staging → Production

Setup
Deploy
Rollback

# Initialize with local dev
helix init

# Add staging environment
helix add cloud --name staging --region us-east-1

# Add production environment
helix add cloud --name production --region us-east-1

# Deploy to development
helix push dev

# Test thoroughly, then deploy to staging
helix push staging

# After staging validation, deploy to production
helix push production

# If issues arise, pull previous version
helix pull production

# Or stop the instance
helix stop production

# Fix issues and redeploy
helix build production
helix push production

Cloud Deployment Workflows

Helix Cloud Deployment

Authenticate

helix auth login

Initialize cloud instance

helix init cloud --region us-east-1 --name production

Configure production settings

Edit helix.toml:

[cloud.production]
type = "helix"
region = "us-east-1"
build_mode = "release"
mcp = true
bm25 = true

[cloud.production.vector_config]
m = 32
ef_construction = 256
ef_search = 1024

Deploy

helix build production
helix push production

Monitor

helix status

Fly.io Deployment

Prerequisites: Install and authenticate flyctl

# Install flyctl
curl -L https://fly.io/install.sh | sh

# Authenticate
fly auth login

Deploy to Fly.io:

Add Fly.io instance

helix add fly \
  --name production \
  --vm-size performance-4x \
  --volume-size 20 \
  --public false

Build and deploy

helix build production
helix push production

Check deployment

fly status -a my-app-production
fly logs -a my-app-production

Scale if needed

fly scale vm performance-8x -a my-app-production
fly scale count 3 -a my-app-production

AWS ECR Deployment

Prerequisites: Configure AWS CLI

# Configure AWS credentials
aws configure

Deploy to ECR:

Add ECR instance

helix add ecr --name staging

Build image

helix build staging

Push to ECR

helix push staging

This will:

Create ECR repository if needed
Authenticate Docker with ECR
Tag and push the image

Deploy to ECS/EKS

Use the pushed image in your container orchestration:

# ECS task definition
image: 123456789.dkr.ecr.us-west-2.amazonaws.com/my-app:latest

Best Practices

Development Best Practices

Always run helix check before deploying
Use descriptive instance names
Keep development and production configurations separate
Regularly clean up unused resources with helix prune
Version control your helix.toml file

Production Best Practices

Use build_mode = "release" for production
Configure appropriate vector parameters for your data scale
Enable monitoring and logging
Set up automated backups
Test migrations in staging first

Security Best Practices

Never commit credentials to version control
Use environment variables for sensitive data
Regularly rotate API keys
Keep CLI updated with helix update
Use private instances for production data

Getting Started

CLI

SDKs

Other Features

Common Workflows

Local Development Workflow

Initial Setup

Development Iteration

Working with Multiple Instances

Multi-Environment Setup

Development → Staging → Production

Cloud Deployment Workflows

Helix Cloud Deployment

Fly.io Deployment

AWS ECR Deployment

Best Practices

Next Steps

Troubleshooting

Configuration Guide

​Local Development Workflow

​Initial Setup

​Development Iteration

​Working with Multiple Instances

​Multi-Environment Setup

​Development → Staging → Production

​Cloud Deployment Workflows

​Helix Cloud Deployment

​Fly.io Deployment

​AWS ECR Deployment

​Best Practices

​Next Steps

Troubleshooting

Configuration Guide

Local Development Workflow

Initial Setup

Development Iteration

Working with Multiple Instances

Multi-Environment Setup

Development → Staging → Production

Cloud Deployment Workflows

Helix Cloud Deployment

Fly.io Deployment

AWS ECR Deployment

Best Practices

Next Steps