CLI Reference¶

Complete reference for the surql command-line interface.

Table of Contents¶

Overview
Global Options
Migration Commands
Schema Commands
Database Commands
Common Workflows
Configuration
Environment Variables

Overview¶

The surql CLI provides commands for managing database schemas, migrations, and inspecting your database.

surql [OPTIONS] COMMAND [ARGS]

Getting Help¶

# Show all commands
surql --help

# Show help for specific command
surql migrate --help

# Show help for subcommand
surql migrate up --help

Version Information¶

surql version

Output:

surql version 0.6.0
Environment: development

Global Options¶

These options work with any command:

`--verbose, -v`¶

Enable verbose logging for detailed output.

surql --verbose migrate up
surql -v schema show

`--help`¶

Show help message and exit.

surql --help
surql migrate --help

Migration Commands¶

All migration commands are under the migrate subcommand:

surql migrate [COMMAND] [OPTIONS]

`migrate up`¶

Apply pending migrations to the database.

surql migrate up [OPTIONS]

Options:

--directory PATH - Migration directory (default: migrations/)
--steps N - Number of migrations to apply (default: all)
--dry-run - Preview changes without applying
--verbose, -v - Enable verbose output

Examples:

# Apply all pending migrations
surql migrate up

# Apply only the next migration
surql migrate up --steps 1

# Apply next 3 migrations
surql migrate up --steps 3

# Preview what will be applied
surql migrate up --dry-run

# Use custom migration directory
surql migrate up --directory ./db/migrations

# Verbose output
surql migrate up --verbose

Output:

Discovering migrations in migrations
Found 2 pending migration(s):
  • 20260102_120000: Create user table
  • 20260102_130000: Create post table
Successfully applied 2 migration(s)

`migrate down`¶

Rollback the last applied migration(s).

surql migrate down [OPTIONS]

Options:

--directory PATH - Migration directory (default: migrations/)
--steps N - Number of migrations to rollback (default: 1)
--dry-run - Preview changes without applying
--verbose, -v - Enable verbose output

Examples:

# Rollback last migration
surql migrate down

# Rollback last 3 migrations
surql migrate down --steps 3

# Preview rollback
surql migrate down --dry-run

# Verbose output
surql migrate down --verbose

Output:

Will rollback 1 migration(s):
  • 20260102_130000: Create post table
Rollback migrations? [y/N]: y
Successfully rolled back 1 migration(s)

`migrate status`¶

Show migration status (applied vs pending).

surql migrate status [OPTIONS]

Options:

--directory PATH - Migration directory (default: migrations/)
--format FORMAT - Output format: table, json, yaml (default: table)
--verbose, -v - Enable verbose output

Examples:

# Show status as table
surql migrate status

# Show status as JSON
surql migrate status --format json

# Use custom directory
surql migrate status --directory ./db/migrations

Output (table):

Migration Status
┌────────────────────────────────────────┬─────────┐
│ Version                                │ Status  │
├────────────────────────────────────────┼─────────┤
│ 20260102_120000                        │ APPLIED │
│ 20260102_130000                        │ APPLIED │
│ 20260102_140000                        │ PENDING │
└────────────────────────────────────────┴─────────┘
Total: 3 | Applied: 2 | Pending: 1

Output (json):

[
  {
    "version": "20260102_120000",
    "description": "Create user table",
    "status": "APPLIED",
    "path": "20260102_120000_create_user_table.py"
  },
  {
    "version": "20260102_130000",
    "description": "Create post table",
    "status": "APPLIED",
    "path": "20260102_130000_create_post_table.py"
  },
  {
    "version": "20260102_140000",
    "description": "Add indexes",
    "status": "PENDING",
    "path": "20260102_140000_add_indexes.py"
  }
]

`migrate history`¶

Show applied migrations from database history.

surql migrate history [OPTIONS]

Options:

--format FORMAT - Output format: table, json, yaml (default: table)
--verbose, -v - Enable verbose output

Examples:

# Show history as table
surql migrate history

# Show history as JSON
surql migrate history --format json

Output:

Migration History
┌─────────────────┬───────────────────┬─────────────────────┬──────────────────┐
│ Version         │ Description       │ Applied At          │ Execution Time   │
├─────────────────┼───────────────────┼─────────────────────┼──────────────────┤
│ 20260102_120000 │ Create user table │ 2026-01-02 12:00:00 │ 45ms             │
│ 20260102_130000 │ Create post table │ 2026-01-02 13:00:00 │ 32ms             │
└─────────────────┴───────────────────┴─────────────────────┴──────────────────┘

`migrate create`¶

Create a new blank migration file.

surql migrate create DESCRIPTION [OPTIONS]

Arguments:

DESCRIPTION - Migration description (required)

Options:

--directory PATH - Migration directory (default: migrations/)
--verbose, -v - Enable verbose output

Examples:

# Create migration
surql migrate create "Add user indexes"

# Create in custom directory
surql migrate create "Add posts" --directory ./db/migrations

Output:

Created migration: 20260102_143000_add_user_indexes.py
Edit the file to add your migration SQL
Path: migrations/20260102_143000_add_user_indexes.py

`migrate validate`¶

Validate migration files for errors.

surql migrate validate [OPTIONS]

Options:

--directory PATH - Migration directory (default: migrations/)
--verbose, -v - Enable verbose output

Examples:

# Validate migrations
surql migrate validate

# Validate with verbose output
surql migrate validate --verbose

Output:

Validating migrations in migrations
All 3 migration(s) are valid
  ✓ 20260102_120000: Create user table
  ✓ 20260102_130000: Create post table
  ✓ 20260102_140000: Add indexes

`migrate generate`¶

Generate migration from schema changes (auto-generation).

surql migrate generate DESCRIPTION [OPTIONS]

Note: Full auto-generation is not yet implemented. Currently creates a blank migration.

Arguments:

DESCRIPTION - Migration description (required)

Options:

--directory PATH - Migration directory (default: migrations/)
--verbose, -v - Enable verbose output

Examples:

surql migrate generate "Update user schema"

Schema Commands¶

Commands for inspecting database schema:

surql schema [COMMAND] [OPTIONS]

`schema show`¶

Display database or table schema.

surql schema show [TABLE] [OPTIONS]

Arguments:

TABLE - Optional table name to show specific table schema

Examples:

# Show entire database schema
surql schema show

# Show specific table schema
surql schema show user

# Show post table schema
surql schema show post

Output (database):

Database: blog
Namespace: blog

Tables:
  - user
  - post
  - likes
  - follows
  - _migration_history

Output (table):

Table: user
Mode: SCHEMAFULL

Fields:
  - username: string
  - email: string
  - age: int
  - created_at: datetime
  - updated_at: datetime

Indexes:
  - username_idx: UNIQUE (username)
  - email_idx: UNIQUE (email)

Database Commands¶

Commands for database management:

surql db [COMMAND] [OPTIONS]

`db ping`¶

Check database connection.

surql db ping

Examples:

surql db ping

Output:

✓ Database connection successful
Connected to: ws://localhost:8000/rpc
Namespace: blog
Database: blog

`db info`¶

Show database information.

surql db info

Examples:

surql db info

Output:

Database Information

Connection:
  URL: ws://localhost:8000/rpc
  Namespace: blog
  Database: blog
  Status: Connected

Tables: 5
Migrations Applied: 3

Common Workflows¶

Initial Setup¶

# Create migrations directory
mkdir migrations

# Create first migration
surql migrate create "Initial schema"

# Edit migration file
# ... add your SQL statements ...

# Apply migration
surql migrate up

Development Workflow¶

# 1. Make schema changes in code
# 2. Create migration
surql migrate create "Add email verification"

# 3. Edit migration file with SQL
# 4. Preview changes
surql migrate up --dry-run

# 5. Apply migration
surql migrate up

# 6. Verify schema
surql schema show

Rollback Workflow¶

# Check current status
surql migrate status

# Preview rollback
surql migrate down --dry-run

# Rollback if needed
surql migrate down

# Verify
surql migrate status

Debugging Migrations¶

# Validate migration files
surql migrate validate

# Check what's pending
surql migrate status

# Try dry run first
surql migrate up --dry-run

# Apply with verbose logging
surql migrate up --verbose

Production Deployment¶

# 1. Check status on production
surql migrate status --format json > status.json

# 2. Preview changes
surql migrate up --dry-run

# 3. Apply migrations
surql migrate up

# 4. Verify
surql migrate history

# 5. Check database
surql db info

Configuration¶

Configuration Files¶

surql loads configuration from:

Environment variables
.env file in current directory
Default values

`.env` File¶

Create a .env file in your project root:

# Database Connection
SURREAL_URL=ws://localhost:8000/rpc
SURREAL_NAMESPACE=blog
SURREAL_DATABASE=blog
SURREAL_USERNAME=root
SURREAL_PASSWORD=root

# Connection Pool
SURREAL_MAX_CONNECTIONS=10

# Retry Configuration
SURREAL_RETRY_MAX_ATTEMPTS=3
SURREAL_RETRY_MIN_WAIT=1.0
SURREAL_RETRY_MAX_WAIT=10.0
SURREAL_RETRY_MULTIPLIER=2.0

# Logging
LOG_LEVEL=INFO

Multiple Environments¶

Use different .env files:

# Development
cp .env .env.development

# Staging
cp .env .env.staging

# Production
cp .env .env.production

Load specific environment:

# Linux/macOS
export $(cat .env.production | xargs) && surql migrate up

# Windows PowerShell
Get-Content .env.production | ForEach-Object {
  $name, $value = $_.split('=')
  Set-Content env:\$name $value
}
surql migrate up

Environment Variables¶

Required Variables¶

SURREAL_URL - Database URL (default: ws://localhost:8000/rpc)
SURREAL_NAMESPACE - Namespace name (required)
SURREAL_DATABASE - Database name (required)

Authentication¶

SURREAL_USERNAME - Database username (default: root)
SURREAL_PASSWORD - Database password (default: root)

Connection Pool¶

SURREAL_MAX_CONNECTIONS - Max concurrent connections (default: 10)

Retry Configuration¶

SURREAL_RETRY_MAX_ATTEMPTS - Max retry attempts (default: 3)
SURREAL_RETRY_MIN_WAIT - Min wait between retries in seconds (default: 1.0)
SURREAL_RETRY_MAX_WAIT - Max wait between retries in seconds (default: 10.0)
SURREAL_RETRY_MULTIPLIER - Exponential backoff multiplier (default: 2.0)

Logging¶

LOG_LEVEL - Logging level: DEBUG, INFO, WARNING, ERROR (default: INFO)

Setting Environment Variables¶

Linux/macOS:

export SURREAL_NAMESPACE=blog
export SURREAL_DATABASE=blog

Windows Command Prompt:

set SURREAL_NAMESPACE=blog
set SURREAL_DATABASE=blog

Windows PowerShell:

$env:SURREAL_NAMESPACE="blog"
$env:SURREAL_DATABASE="blog"

Exit Codes¶

The CLI uses standard exit codes:

0 - Success
1 - General error
130 - Interrupted (Ctrl+C)

Check exit code:

# Linux/macOS
surql migrate up
echo $?

# Windows Command Prompt
surql migrate up
echo %ERRORLEVEL%

# Windows PowerShell
surql migrate up
echo $LASTEXITCODE

Shell Completion¶

surql supports shell completion for shell, zsh, and fish.

shell¶

# Add to ~/.shellrc
eval "$(_surql_COMPLETE=shell_source surql)"

Zsh¶

# Add to ~/.zshrc
eval "$(_surql_COMPLETE=zsh_source surql)"

Fish¶

# Add to ~/.config/fish/config.fish
eval (env _surql_COMPLETE=fish_source surql)

Troubleshooting¶

Connection Errors¶

# Check database is running
surql db ping

# Test connection with verbose output
surql --verbose db info

Migration Errors¶

# Validate migration files
surql migrate validate

# Check migration status
surql migrate status

# View migration history
surql migrate history

Permission Errors¶

# Check directory permissions
ls -la migrations/

# Create directory if missing
mkdir -p migrations

Output Format Issues¶

# Use JSON for script parsing
surql migrate status --format json | jq '.[] | select(.status == "PENDING")'

# Use table for human-readable output
surql migrate status --format table

Scripting Examples¶

shell Script¶

#!/bin/shell
set -e

# Apply migrations in CI/CD
echo "Checking migration status..."
surql migrate status

echo "Applying migrations..."
surql migrate up

echo "Verifying migrations..."
surql migrate history

echo "Done!"

Python Script¶

import subprocess
import sys

def run_migrations():
  """Run database migrations."""
  try:
    # Check status
    result = subprocess.run(
      ['surql', 'migrate', 'status', '--format', 'json'],
      capture_output=True,
      text=True,
      check=True,
    )

    print("Migration status:", result.stdout)

    # Apply migrations
    subprocess.run(
      ['surql', 'migrate', 'up'],
      check=True,
    )

    print("Migrations applied successfully")

  except subprocess.CalledProcessError as e:
    print(f"Error: {e}", file=sys.stderr)
    sys.exit(1)

if __name__ == '__main__':
  run_migrations()

Best Practices¶

Always validate before applying migrations
Use dry-run to preview changes
Check status before and after migrations
Keep migrations in version control
Test rollbacks in development
Use verbose mode when debugging
Set environment variables properly
Backup database before major changes
Review migration history regularly
Document breaking changes in migrations

Next Steps¶

Learn about Migrations in detail
Explore Schema Definition
See Query Building for data operations
Check Examples for common patterns

CLI Reference¶

Table of Contents¶

Overview¶

Getting Help¶

Version Information¶

Global Options¶

--verbose, -v¶

--help¶

Migration Commands¶

migrate up¶

migrate down¶

migrate status¶

migrate history¶

migrate create¶

migrate validate¶

migrate generate¶

Schema Commands¶

schema show¶

Database Commands¶

db ping¶

db info¶

Common Workflows¶

Initial Setup¶

Development Workflow¶

Rollback Workflow¶

Debugging Migrations¶

Production Deployment¶

Configuration¶

Configuration Files¶

.env File¶

Multiple Environments¶

Environment Variables¶

Required Variables¶

Authentication¶

Connection Pool¶

Retry Configuration¶

Logging¶

Setting Environment Variables¶

Exit Codes¶

Shell Completion¶

shell¶

Zsh¶

Fish¶

Troubleshooting¶

Connection Errors¶

Migration Errors¶

Permission Errors¶

Output Format Issues¶

Scripting Examples¶

shell Script¶

Python Script¶

Best Practices¶

Next Steps¶

`--verbose, -v`¶

`--help`¶

`migrate up`¶

`migrate down`¶

`migrate status`¶

`migrate history`¶

`migrate create`¶

`migrate validate`¶

`migrate generate`¶

`schema show`¶

`db ping`¶

`db info`¶

`.env` File¶