Quick Start Guide

Get started with DataBridge in 5 minutes - generate type-safe APIs and Angular clients from your database schema

Quick Start Guide

Get DataBridge running in 5 minutes!

Prerequisites

Node.js 20 or higher
Database: MySQL, PostgreSQL, SQL Server, SQLite, or CockroachDB (local or remote)
Basic terminal knowledge

Version 0.2.9 - Now supports 5 major databases and custom queries/schemas!

Installation

Install the universal package (works on all platforms):

npm install -g @databridge-cli/cli

# Verify installation
databridge --version

5-Minute Quick Start

1. Choose Your Database

DataBridge supports 5 databases. Pick one:

MySQL:

docker run -d --name mysql-dev \
  -e MYSQL_ROOT_PASSWORD=password \
  -e MYSQL_DATABASE=mydb \
  -p 3306:3306 mysql:8

PostgreSQL:

docker run -d --name postgres-dev \
  -e POSTGRES_PASSWORD=password \
  -e POSTGRES_DB=mydb \
  -p 5432:5432 postgres:16

SQL Server:

docker run -d --name sqlserver-dev \
  -e 'ACCEPT_EULA=Y' \
  -e 'SA_PASSWORD=YourStrong@Passw0rd' \
  -p 1433:1433 \
  mcr.microsoft.com/mssql/server:2022-latest

SQLite:

# No Docker needed - file-based database
# Connection: file:./dev.db

CockroachDB:

docker run -d --name cockroach-dev \
  -p 26257:26257 -p 8080:8080 \
  cockroachdb/cockroach:latest start-single-node --insecure

2. Initialize Your Project

# Create project directory
mkdir my-app
cd my-app

# Initialize DataBridge
databridge init

Answer the prompts:

? Select database provider: (Use arrow keys)
  ❯ MySQL
    PostgreSQL
    SQL Server
    SQLite
    CockroachDB

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

? API output path: api
? Angular SDK output path: src/app/databridge

⚠️ SQL Server Users: After init, add these additional environment variables to .env:
DB_SERVER=127.0.0.1
DB_PORT=1433
DB_NAME=mydb
DB_USER=sa
DB_PASSWORD=YourStrong@Passw0rd
These are required by the Prisma 7 SQL Server adapter.

Files created:

.databridge.json - Configuration
prisma/schema.prisma - Database schema template
.env - Environment variables

3. Create Database Tables

# Connect to MySQL
mysql -h localhost -u root -ppassword mydb

# Create sample tables
CREATE TABLE users (
  id INT AUTO_INCREMENT PRIMARY KEY,
  email VARCHAR(255) NOT NULL UNIQUE,
  name VARCHAR(100) NOT NULL,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE products (
  id INT AUTO_INCREMENT PRIMARY KEY,
  name VARCHAR(255) NOT NULL,
  description TEXT,
  price DECIMAL(10, 2) NOT NULL,
  stock INT DEFAULT 0
);

# Exit MySQL
exit

4. Introspect Database

databridge introspect

Output:

Introspecting database schema...

✅ Schema introspection complete!
Found 2 models: users, products

Check generated schema:

cat prisma/schema.prisma

5. Generate Code

databridge generate

Output:

⛙️  Generating code from Prisma schema...

Found 2 models

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

✅ Code generation complete!

Generated:
  API routes:      api/routes/
  Angular services: src/app/databridge/services/
  TypeScript models: src/app/databridge/models/
  Logger utility:  api/utils/logger.ts
  Test script:      test-api.sh

What was generated:

✅ Zod validation - Automatic validation with smart constraints (positive prices, non-negative stock)
✅ Error handling - 400, 404, 409, 500 responses with detailed messages
✅ Production logging - Pino logger with structured JSON logs
✅ Test suite - Automated bash script with 14+ comprehensive tests
✅ Health endpoints - /health and /metrics for monitoring

6. Start API Server

# Navigate to API directory
cd apps/api

# Start the development server
npm run dev

Output:

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

✅ Server running at http://localhost:3000 Swagger UI: http://localhost:3000/docs OpenAPI spec: http://localhost:3000/openapi.json Health check: http://localhost:3000/health Metrics: http://localhost:3000/metrics

7. Explore Interactive Docs ⭐ NEW

Visit http://localhost:3000/docs for Swagger UI:

Test all endpoints in your browser
See request/response schemas
Search and filter operations
Download OpenAPI spec

Quick test:

Open http://localhost:3000/docs
Find POST /users endpoint
Click “Try it out”
Click “Execute”
See your new user created!

8. Test Your API (Alternative: cURL)

Open a new terminal:

# Health check
curl http://localhost:3000/health

# Get all users
curl http://localhost:3000/users

# Create a user
curl -X POST http://localhost:3000/users \
  -H "Content-Type: application/json" \
  -d '{"email": "alice@example.com", "name": "Alice"}'

# Get all products
curl http://localhost:3000/products

# Create a product
curl -X POST http://localhost:3000/products \
  -H "Content-Type: application/json" \
  -d '{"name": "Laptop", "price": 999.99, "stock": 10}'

9. Generate Client SDKs ⭐ NEW

# Python SDK
databridge generate-sdk --lang python
cd sdks/python
pip install -e .

# Go SDK
databridge generate-sdk --lang go
cd sdks/go
go mod init myapp

# TypeScript SDK
databridge generate-sdk --lang typescript-axios
cd sdks/typescript-axios
npm install

Use Python SDK:

from databridge_client import ApiClient, ProductApi

api = ProductApi(ApiClient(host="http://localhost:3000"))
products = api.list_products(page=1, limit=10)
print(products)

Learn more: Multi-Language SDK Generation

10. Run Automated Tests

# Go back to project root
cd ../..

# Run the auto-generated test suite
bash test-api.sh

Output:

=========================================
DataBridge API Test Suite
=========================================

Test: Health Check
✅ Pass

Test: GET /users (List all)
✅ Pass

Test: POST /users (Create valid)
✅ Pass

Test: POST /users (Missing required field)
✅ Pass - Validation caught missing field

Test: POST /users (Empty email)
✅ Pass - Validation caught empty string

... (9 more tests)

=========================================
Test Suite Complete: 14/14 passed
=========================================

Success! You now have:

✅ REST API running on port 3000
✅ Full CRUD operations with Zod validation
✅ Comprehensive error handling (400, 404, 409, 500)
✅ Production-ready logging
✅ Automated test suite (14+ tests)
✅ Health and metrics endpoints
✅ TypeScript services for Angular

Using in Angular

1. Create Angular App

# Install Angular CLI
npm install -g @angular/cli

# Create new app
ng new my-angular-app
cd my-angular-app

# Copy generated services
cp -r ../my-app/src/app/databridge ./src/app/

2. Use Generated Services

app.component.ts:

import { Component, OnInit } from '@angular/core';
import { CommonModule } from '@angular/common';
import { HttpClientModule } from '@angular/common/http';
import { ProductsService } from './databridge/services/products.service';
import { Product } from './databridge/models/product.model';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [CommonModule, HttpClientModule],
  template: `
    <h1>Products</h1>
    
    <div *ngFor="let product of products">
      <h2>{{ product.name }}</h2>
      <p>Price: \${{ product.price }}</p>
      <p>Stock: {{ product.stock }}</p>
    </div>
  `
})
export class AppComponent implements OnInit {
  products: Product[] = [];

  constructor(private productsService: ProductsService) {}

  ngOnInit() {
    this.productsService.list().subscribe(data => {
      this.products = data;
    });
  }
}

3. Run Angular App

ng serve

# Visit http://localhost:4200

Built-in Error Handling

All generated endpoints include comprehensive error handling:

Invalid ID Format (400)

curl http://localhost:3000/users/abc
# {"error":"Invalid ID format","message":"ID must be a number"}

Record Not Found (404)

curl http://localhost:3000/users/99999
# {"error":"users not found"}

Unique Constraint Violation (409)

curl -X POST http://localhost:3000/users \
  -H "Content-Type: application/json" \
  -d '{"email":"alice@example.com","name":"Alice"}'
# {"error":"Conflict","message":"A record with this unique value already exists","field":"email"}

Validation Error (400)

curl -X POST http://localhost:3000/products \
  -H "Content-Type: application/json" \
  -d '{"name":"","price":-10}'
# {"error":"Validation failed","details":[{"path":["name"],"message":"Name is required"},{"path":["price"],"message":"Price must be positive"}]}

Foreign Key Violation (400)

curl -X POST http://localhost:3000/orders \
  -H "Content-Type: application/json" \
  -d '{"user_id":99999,"total":100}'
# {"error":"Bad Request","message":"Referenced record does not exist","field":"user_id"}

Common Commands

View All Commands

databridge --help

Get Help for Specific Command

databridge init --help
databridge generate --help

Use Custom Database URL

databridge introspect --db mysql://user:pass@host:3306/db

Skip Prompts (Use Defaults)

databridge init --skip-prompts

Project Structure

After running all commands, your project looks like:

my-app/
├── .databridge.json              # DataBridge config
├── .env                          # Environment variables
├── test-api.sh                   # Auto-generated test suite
├── prisma/
│   └── schema.prisma             # Database schema
├── apps/
│   └── api/
│       └── src/
│           ├── server.ts         # Main server with logging
│           ├── plugins/
│           │   └── prisma.ts     # Prisma plugin
│           ├── utils/
│           │   └── logger.ts     # Pino logger config
│           └── routes/
│               ├── _generated.ts # Route registry
│               ├── users.ts      # User CRUD + validation
│               └── products.ts   # Product CRUD + validation
└── src/
    └── app/
        └── databridge/
            ├── models/
            │   ├── index.ts           # All models exported
            │   ├── user.model.ts      # User TypeScript interface
            │   └── product.model.ts   # Product TypeScript interface
            └── services/
                ├── users.service.ts    # User Angular service
                └── products.service.ts # Product Angular service

Next Steps

Add More Tables

# 1. Add tables to your database
# 2. Re-run introspect
databridge introspect

# 3. Re-generate code
databridge generate

# 4. Restart server
databridge serve

The new tables are automatically added!

Customize Configuration

Edit .databridge.json:

{
  "version": "0.1.0",
  "database": {
    "url": "mysql://root:password@localhost:3306/mydb"
  },
  "api": {
    "outputPath": "api",
    "port": 3000,              // Change server port
    "cors": "*"                // Change CORS policy
  },
  "angular": {
    "outputPath": "src/app/databridge"
  },
  "auth": {
    "jwtSecret": "your-secret-here"
  }
}

Add Authentication

Coming soon! DataBridge will support JWT authentication out of the box.

Deploy to Production

See Deployment Guide for:

Docker deployment
Environment variables
Production best practices

Troubleshooting

Cannot connect to MySQL

Error: Can't reach database server at `localhost:3306`

Solution:

Check MySQL is running: docker ps or systemctl status mysql
Verify port: mysql -h localhost -P 3306 -u root -p
Check firewall settings

Port 3000 already in use

Error: listen EADDRINUSE: address already in use :::3000

Solution:

Kill process: lsof -ti:3000 | xargs kill -9 (Mac/Linux)
Or change port in .databridge.json

Prisma Client not found

Error: @prisma/client did not initialize yet

Solution:

npm install @prisma/client
npx prisma generate

TypeScript errors in generated code

Solution:

Ensure @prisma/client is installed
Run npx prisma generate
Restart your IDE/editor

Getting Help

GitHub Issues: Report a bug

What’s Next?

Congratulations! You’ve successfully:

✅ Set up DataBridge
✅ Generated a REST API with OpenAPI 3.0 spec
✅ Explored interactive Swagger UI docs
✅ Generated client SDKs
✅ Created Angular services
✅ Tested your endpoints

Explore OpenAPI Ecosystem ⭐ NEW

API Tutorials Index - Complete guide to OpenAPI features
Interactive Swagger UI - Master the /docs endpoint
SDK Generation - Generate Python, Go, C#, Java, and 50+ languages
Contract Testing - Validate APIs with Dredd
Mock Servers - Frontend dev without backend

Learn More

Core Concepts - Understand how DataBridge works

Ready to build something awesome? Start coding! 🚀

Was this page helpful?

Edit this page on GitHub