CLI Command Reference

Complete reference for all DataBridge commands, flags, and usage examples.

Table of Contents

• Installation
• Getting Help
• Commands
  • init
  • introspect
  • generate
  • generate-sdk
  • serve
• Common Workflows

Installation

Install the DataBridge CLI globally:

npm install -g @databridge-cli/cli

Note: The universal @databridge-cli/cli package works on Windows, macOS, and Linux. The old platform-specific packages (@databridge-cli/cli-win32, @databridge-cli/cli-darwin, @databridge-cli/cli-linux) are deprecated.

Verify installation:

databridge --version

Getting Help

# General help
databridge --help

# Help for specific command
databridge init --help
databridge generate --help
databridge introspect --help
databridge generate-sdk --help
databridge serve --help

Commands

init - Initialize Project

Create a new DataBridge project with database connection and configuration.

Basic Usage

# Interactive mode (recommended)
databridge init

# With project name
databridge init my-api

# Skip all prompts (uses defaults)
databridge init my-api --skip-prompts

All Flags

Examples

Interactive setup (best for first time):

databridge init my-api

Full automation (init + introspect + generate in one command):

databridge init my-api --auto-generate

With Angular SDK:

databridge init my-api --auto-generate --frameworks angular

Multiple frameworks:

databridge init my-api --frameworks angular,react,vue

Quick setup with defaults:

databridge init my-api --skip-prompts

Interactive Prompts

When running without --skip-prompts, you’ll answer:

1. Database provider - Choose from:

   • MySQL
   • PostgreSQL
   • SQL Server
   • SQLite
   • CockroachDB

2. Database URL - Connection string examples:

   MySQL:       mysql://root:password@localhost:3306/mydb
   PostgreSQL:  postgresql://postgres:password@localhost:5432/mydb
   SQL Server:  sqlserver://localhost:1433;database=mydb;user=sa;password=pass
   SQLite:      file:./dev.db
   CockroachDB: postgresql://root@localhost:26257/mydb?sslmode=disable

3. API output path - Where to generate API code (default: apps/api/src)

4. Angular SDK path - Where to generate Angular services (default: src/app/databridge)

What Gets Created

After running init, you’ll have:

my-api/
├── .databridge.json        # Project configuration
├── .env                    # Environment variables (DATABASE_URL)
├── .gitignore             # Git ignore file
├── package.json           # Node.js dependencies
├── prisma/
│   ├── schema.prisma      # Database schema template
│   └── prisma.config.ts   # Prisma 7 configuration
└── (apps/api/src - created after generate)

SQL Server Special Note

⚠️ SQL Server users: After init, add these variables to .env:

DB_SERVER=localhost
DB_PORT=1433
DB_NAME=mydb
DB_USER=sa
DB_PASSWORD=YourStrong@Passw0rd

These are required by the Prisma 7 SQL Server adapter architecture.

introspect - Read Database Schema

Read your database structure and generate a Prisma schema file.

Basic Usage

# Use DATABASE_URL from .env
databridge introspect

# Specify database URL directly
databridge introspect --db mysql://user:pass@localhost:3306/mydb

All Flags

Examples

Standard usage (reads from .env file):

databridge introspect

With custom database URL:

databridge introspect --db mysql://root:password@localhost:3306/testdb

Different environments:

# Development
databridge introspect --db mysql://localhost:3306/dev_db

# Staging
databridge introspect --db mysql://staging-host:3306/staging_db

What It Does

1. ✅ Connects to your database
2. ✅ Reads all tables, columns, and relationships
3. ✅ Auto-detects database provider (MySQL, PostgreSQL, SQL Server, SQLite, CockroachDB)
4. ✅ Generates prisma/schema.prisma with:
   • Correct provider setting
   • All models (tables)
   • Field types
   • Relations (foreign keys)
   • Indexes and constraints

Example Output

Introspecting database schema...

✅ Schema introspection complete!
Found 5 models: users, products, orders, order_items, categories
Provider auto-detected: mysql

Generated schema (prisma/schema.prisma):

generator client {
  provider = "prisma-client-js"
}

datasource db {
  provider = "mysql"
  url      = env("DATABASE_URL")
}

model users {
  id         Int       @id @default(autoincrement())
  email      String    @unique @db.VarChar(255)
  name       String    @db.VarChar(100)
  created_at DateTime  @default(now())
}

model products {
  id          Int      @id @default(autoincrement())
  name        String   @db.VarChar(255)
  description String?  @db.Text
  price       Decimal  @db.Decimal(10, 2)
  stock       Int      @default(0)
}

Auto-Detect Provider Feature

New in v0.2.5: DataBridge automatically detects your database type from the connection string:

• mysql://... → provider = "mysql"
• postgresql://... → provider = "postgresql"
• sqlserver://... → provider = "sqlserver"
• file:... → provider = "sqlite"
• cockroachdb://... → provider = "cockroachdb"

No manual editing needed!

Troubleshooting

Error: Database connection failed

• ✓ Check DATABASE_URL in .env file
• ✓ Ensure database server is running
• ✓ Verify username, password, and database name
• ✓ Check firewall/network access

Error: No models found

• ✓ Your database might be empty (create tables first)
• ✓ Verify you’re connecting to the correct database
• ✓ Check user has read permissions on tables

SQL Server: Authentication error

• ✓ Make sure all environment variables are set (DB_SERVER, DB_PORT, DB_NAME, DB_USER, DB_PASSWORD)
• ✓ Use encrypt=true;trustServerCertificate=true in connection string

generate - Create API Code

Generate API routes, server, OpenAPI docs, and optional frontend SDKs from your Prisma schema.

Basic Usage

# Interactive mode
databridge generate

# Skip prompts (no SDK generation)
databridge generate --skip-prompts

# Force regeneration even if schema unchanged
databridge generate --update

All Flags

Examples

Standard generation (interactive):

databridge generate

No prompts, no SDK:

databridge generate --skip-prompts

With Angular SDK:

databridge generate --frameworks angular

Multiple SDKs:

databridge generate --frameworks angular,react,vue

Force regeneration:

databridge generate --update

Full automation with SDKs:

databridge generate --skip-prompts --frameworks angular,react --language typescript

What Gets Generated

Always Generated

1. API Routes (apps/api/src/routes/)

   • One file per database table
   • Full CRUD operations:
     • GET /{model} - List all (with pagination)
     • GET /{model}/:id - Get one by ID
     • POST /{model} - Create new
     • PATCH /{model}/:id - Update existing
     • DELETE /{model}/:id - Delete by ID
   • ✅ Zod validation on all inputs
   • ✅ Comprehensive error handling (400, 404, 409, 500)

2. Server (apps/api/src/server.ts)

   • Fastify HTTP server
   • All routes registered
   • CORS enabled
   • Health check: /health
   • Metrics: /metrics
   • OpenAPI spec: /openapi.json
   • Swagger UI: /docs

3. Database Plugin (apps/api/src/plugins/prisma.ts)

   • Prisma Client with Prisma 7 adapters
   • Correct adapter for your database (MySQL, PostgreSQL, SQL Server, SQLite, CockroachDB)
   • Connection pool management
   • Graceful shutdown

4. Logger Utility (apps/api/src/utils/logger.ts)

   • Structured JSON logging with Pino
   • Request/response logging
   • Error tracking
   • Performance monitoring

5. OpenAPI Specification (apps/api/openapi.json)

   • Complete API documentation
   • Request/response schemas
   • Works with Postman, Insomnia, Swagger UI

6. Test Suite (test-api.sh)

   • Automated bash script
   • Tests all CRUD operations
   • Validates error handling
   • Checks validation rules

7. TypeScript Models (apps/api/src/models/index.ts)

   • Type definitions for all database models
   • Shared across API and SDKs

Optional (With --frameworks)

8. Angular Services (src/databridge/services/)

   • One service per model
   • HTTP methods for all CRUD operations
   • TypeScript types included
   • Observable-based (RxJS)
   • ✅ Production-ready

9. React Hooks (src/databridge/hooks/)

   • Custom hooks per model (useProducts, useOrders)
   • useState for state management
   • fetch API for HTTP requests
   • TypeScript types included
   • ⚠️ Code complete, needs testing

10. Vue Composables (src/databridge/composables/)

• Composables per model (useProducts, useOrders)
• ref() for reactive state
• fetch API for HTTP requests
• TypeScript types included
• ⚠️ Code complete, needs testing

11. Svelte Stores (src/lib/databridge/stores/)

• Stores per model (products, orders)
• writable() for reactive state
• fetch API for HTTP requests
• TypeScript types included
• ⚠️ Code complete, needs testing

Learn more: See Frontend Framework SDKs for complete usage guides

Database Adapter Selection

DataBridge automatically selects the correct Prisma 7 adapter based on your database:

All adapters are automatically installed and configured!

Example Output

⚙️  Generating API from Prisma schema...

Found 5 models

  Generating API route: users.ts
  Generating API route: products.ts
  Generating API route: orders.ts
  Generating API route: order_items.ts
  Generating API route: categories.ts
  Generating Angular service: usersService
  Generating Angular service: productsService
  Generating Angular service: ordersService
  Generating Angular service: order_itemsService
  Generating Angular service: categoriesService
  Generated TypeScript models: models/index.ts
  Generated test script: test-api.sh
  Generated logger utility: utils/logger.ts
  Generated server: server.ts

✔ Generated Prisma Client (7.1.0) to ./generated/prisma in 250ms

✅ Code generation complete!

Generated:
  API routes:       apps/api/src/routes/
  Angular services: frontend-sdks/angular/services/
  TypeScript models: apps/api/src/models/
  Logger utility:   apps/api/src/utils/logger.ts
  Test script:      test-api.sh

Smart Incremental Generation

DataBridge only regenerates files when needed:

# First run - generates everything
databridge generate

# Second run - detects no changes
databridge generate
# Output: ⏭️ Schema unchanged, skipping API regeneration (use --update to force)

# Force regeneration
databridge generate --update

What to Do Next

After generation:

1. Start the server:

   cd apps/api
   npm run dev

2. Test API at http://localhost:3000/docs (Swagger UI)

3. Run test suite:

   bash test-api.sh

4. Use generated SDKs in your frontend app

generate-sdk - Create Client SDKs

Generate client SDKs in 50+ programming languages using OpenAPI Generator.

⚠️ Java Requirement: Multi-language SDK generation requires Java 11+. Built-in SDKs (Angular/React/Vue/Svelte via --frameworks flag in generate command) do NOT require Java.

Basic Usage

# List all available languages
databridge generate-sdk --list-languages

# Generate Python SDK
databridge generate-sdk --lang python

# Generate multiple SDKs
databridge generate-sdk --lang python,go,csharp

# Custom output directory
databridge generate-sdk --lang python --output ./my-sdks

All Flags

Supported Languages (50+)

Backend Languages:

• python - Python with requests
• go - Go SDK
• csharp - C# (.NET)
• java - Java SDK
• kotlin - Kotlin SDK
• php - PHP SDK
• ruby - Ruby SDK
• rust - Rust SDK
• scala - Scala SDK

Frontend Languages:

• typescript-axios - TypeScript with Axios
• typescript-fetch - TypeScript with Fetch API
• javascript - JavaScript SDK

Mobile:

• swift5 - Swift 5 (iOS)
• kotlin - Kotlin (Android)
• dart - Dart (Flutter)

Other:

• r - R language
• perl - Perl
• elixir - Elixir
• haskell - Haskell

See full list of 50+ languages

Examples

Single language:

databridge generate-sdk --lang python

Multiple languages:

databridge generate-sdk --lang python,go,csharp,typescript-axios

Custom output directory:

databridge generate-sdk --lang python --output ./client-sdks

For monorepo structure:

databridge generate-sdk --lang python --api-dir ./packages/api --output ./packages/sdks

Example Output

Generating SDKs...

Generating Python SDK...
✅ Python SDK generated: ./sdks/python

Generating Go SDK...
✅ Go SDK generated: ./sdks/go

Generating C# SDK...
✅ C# SDK generated: ./sdks/csharp

✅ SDK generation complete!

Generated SDKs in:
  - sdks/python
  - sdks/go
  - sdks/csharp

Next steps:
  Python: cd sdks/python && pip install -e .
  Go:     cd sdks/go && go mod init myapp
  C#:     cd sdks/csharp && dotnet build

Using Generated SDKs

Python SDK

# Install
cd sdks/python
pip install -e .

Usage:

from databridge_client import ApiClient, Configuration, ProductApi

# Configure client
config = Configuration(host="http://localhost:3000")
client = ApiClient(config)

# Use API
product_api = ProductApi(client)
products = product_api.list_products(page=1, limit=10)

for product in products:
    print(f"{product.name}: ${product.price}")

Go SDK

# Setup
cd sdks/go
go mod init myapp
go mod tidy

Usage:

package main

import (
    "context"
    "fmt"
    databridge "myapp/client"
)

func main() {
    config := databridge.NewConfiguration()
    config.Servers[0].URL = "http://localhost:3000"
    
    client := databridge.NewAPIClient(config)
    ctx := context.Background()
    
    products, _, err := client.ProductAPI.ListProducts(ctx).Execute()
    if err != nil {
        panic(err)
    }
    
    for _, p := range products {
        fmt.Printf("%s: $%.2f\n", p.Name, p.Price)
    }
}

TypeScript SDK

# Install
cd sdks/typescript-axios
npm install

Usage:

import { Configuration, ProductApi } from './client';

const config = new Configuration({
  basePath: 'http://localhost:3000'
});

const productApi = new ProductApi(config);

async function getProducts() {
  const response = await productApi.listProducts(1, 10);
  console.log(response.data);
}

getProducts();

C# SDK

# Build
cd sdks/csharp
dotnet build

Usage:

using DataBridge.Client.Api;
using DataBridge.Client.Client;

var config = new Configuration 
{ 
    BasePath = "http://localhost:3000" 
};

var productApi = new ProductApi(config);
var products = productApi.ListProducts(1, 10);

foreach (var product in products)
{
    Console.WriteLine($"{product.Name}: ${product.Price}");
}

Prerequisites

Java 11+ is required (used by OpenAPI Generator under the hood):

# Check Java version
java -version
# Need: Java 11 or higher

Important Notes:

• ✅ Built-in SDKs (Angular, React, Vue, Svelte via databridge generate --frameworks) do NOT require Java
• ⚠️ Multi-language SDKs (Python, Go, C#, etc. via databridge generate-sdk) DO require Java 11+
• 🔧 DataBridge auto-installs openapi-generator-cli globally on first use
• ✓ Global install is one-time (works across all projects)

Installation guides:

• Windows: choco install zulu11 or download from Adoptium
• macOS: brew install openjdk@11
• Linux: sudo apt install openjdk-11-jre

Corrupted Java Installation? If you see errors about <JAVA_HOME> or Java Virtual Machine:

1. Uninstall existing Java
2. Reinstall from Adoptium or Azul Zulu
3. Set JAVA_HOME environment variable (Windows users)

Don’t want to install Java? Use built-in SDKs instead:

# No Java required - uses ts-morph instead
databridge generate --frameworks angular,react,vue,svelte

Error: OpenAPI spec not found

• ✓ Run databridge generate first to create openapi.json
• ✓ Check --api-dir flag points to correct directory
• ✓ Verify apps/api/openapi.json exists

serve - Start Development Server

Start the DataBridge API server with hot reload.

Basic Usage

# Default (port 3000)
databridge serve

# Custom port
databridge serve --port 4000

# Custom host
databridge serve --host 127.0.0.1

All Flags

Examples

Standard development:

databridge serve

Custom port:

databridge serve --port 4000

Localhost only (don’t expose to network):

databridge serve --host 127.0.0.1

Custom port and host:

databridge serve --port 8080 --host 0.0.0.0

Alternative: npm scripts

Instead of databridge serve, you can use npm scripts (recommended):

cd apps/api
npm run dev        # Development with hot reload
npm run build      # Production build
npm start          # Production server

Example Output

{"level":30,"time":1734374400000,"pid":12345,"hostname":"localhost","msg":"Starting DataBridge API server...","node_env":"development","node_version":"v20.19.3"}
{"level":30,"time":1734374401000,"pid":12345,"hostname":"localhost","msg":"Server listening","address":"0.0.0.0","port":3000}

Available Endpoints

Once running:

• Swagger UI: http://localhost:3000/docs
• OpenAPI spec: http://localhost:3000/openapi.json
• Health check: http://localhost:3000/health
• Metrics: http://localhost:3000/metrics
• Your API: http://localhost:3000/{model}

Environment Variables

Control server behavior with .env:

# Server
API_PORT=3000
API_HOST=0.0.0.0
NODE_ENV=development

# Database
DATABASE_URL=mysql://root:password@localhost:3306/mydb

# SQL Server (if using)
DB_SERVER=localhost
DB_PORT=1433
DB_NAME=mydb
DB_USER=sa
DB_PASSWORD=password

# CORS
CORS_ORIGIN=*

# JWT (if enabled)
JWT_SECRET=your-secret-key

Stopping the Server

• Press Ctrl+C to stop
• Server performs graceful shutdown (closes database connections)

Common Workflows

Complete Setup (First Time)

# 1. Initialize project
databridge init my-api
cd my-api

# 2. Create database tables (MySQL example)
mysql -u root -p
CREATE DATABASE mydb;
USE mydb;
CREATE TABLE products (
  id INT PRIMARY KEY AUTO_INCREMENT,
  name VARCHAR(255) NOT NULL,
  price DECIMAL(10,2) NOT NULL
);
EXIT;

# 3. Introspect database
databridge introspect

# 4. Generate API
databridge generate --frameworks angular

# 5. Start server
cd apps/api
npm run dev

Quick Setup (Automation)

# One command: init + introspect + generate
databridge init my-api --auto-generate --frameworks angular

# Start server
cd my-api/apps/api
npm run dev

Updating After Schema Changes

# 1. Modify database (add columns, tables, etc.)

# 2. Re-introspect
databridge introspect

# 3. Force regeneration
databridge generate --update

# 4. Restart server (Ctrl+C, then npm run dev)

Generate Multiple SDKs

# Generate Python, Go, and TypeScript SDKs
databridge generate-sdk --lang python,go,typescript-axios

# Install and test Python SDK
cd sdks/python
pip install -e .
python -c "from databridge_client import ProductApi; print('SDK installed!')"

Working with Different Databases

# Switch from MySQL to PostgreSQL
# 1. Update .env
DATABASE_URL=postgresql://postgres:password@localhost:5432/mydb

# 2. Re-introspect (auto-detects provider)
databridge introspect

# 3. Regenerate with new adapter
databridge generate --update

# 4. Restart server
cd apps/api
npm run dev

Testing Your API

# 1. Generate with test suite
databridge generate

# 2. Start server
cd apps/api
npm run dev

# 3. Run tests (in another terminal)
cd ../..
bash test-api.sh

Using Swagger UI for Development

# 1. Start server
cd apps/api
npm run dev

# 2. Open browser
# Visit: http://localhost:3000/docs

# 3. Test endpoints interactively
# - Click any endpoint
# - Click "Try it out"
# - Fill in request body
# - Click "Execute"
# - See response

Tips & Best Practices

Use Environment Variables

Never commit credentials to .databridge.json:

{
  "database": {
    "url": "${DATABASE_URL}"
  }
}

Keep secrets in .env (add to .gitignore):

DATABASE_URL=mysql://root:password@localhost:3306/mydb

Incremental Development

# Only regenerate when needed
databridge generate           # Skips if schema unchanged
databridge generate --update  # Forces regeneration

Multiple Environments

# Development
DATABASE_URL=mysql://localhost:3306/dev_db databridge introspect

# Staging
DATABASE_URL=mysql://staging-host:3306/staging_db databridge introspect

# Production
DATABASE_URL=mysql://prod-host:3306/prod_db databridge introspect

Quick Testing

# Use --skip-prompts for rapid iteration
databridge init test-project --skip-prompts --auto-generate
cd test-project/apps/api
npm run dev

SDK Version Control

# Commit generated SDKs if sharing with team
git add sdks/
git commit -m "Update SDKs for v1.2.3"

# Or regenerate on each machine
# Add to .gitignore: sdks/

Getting Help

Command-Specific Help

databridge init --help
databridge introspect --help
databridge generate --help
databridge generate-sdk --help
databridge serve --help

Common Issues

“Command not found: databridge”

# Reinstall CLI
npm install -g @databridge-cli/cli

“Database connection failed”

• Check DATABASE_URL in .env
• Ensure database server is running
• Verify credentials

“No models found”

• Create tables in your database first
• Run databridge introspect after adding tables

“Port 3000 already in use”

# Use different port
databridge serve --port 4000
# Or update .env: API_PORT=4000

Resources

• Getting Started Guide
• Database Setup
• Core Concepts
• Testing Guide
• Deployment Guide
• GitHub Issues

Quick Reference Card

# Setup
databridge init my-api                          # Initialize project
databridge init my-api --auto-generate          # Full automation
databridge introspect                           # Read database schema
databridge generate                             # Create API code
databridge generate --frameworks angular        # With Angular SDK
databridge generate-sdk --lang python,go        # Multi-language SDKs

# Development
cd apps/api && npm run dev                      # Start server
bash test-api.sh                                # Run tests
databridge serve --port 4000                    # Custom port

# Updates
databridge introspect                           # After DB changes
databridge generate --update                    # Force regeneration

# Help
databridge --help                               # General help
databridge <command> --help                     # Command help

Ready to build? Start with the Quick Start Guide or Getting Started Guide!