JamesDBBApi (JamesDB Bridge API)

⚠️ Project under active development: Some features may be incomplete, unstable, or not working as expected. Please open an issue for any bug or suggestion!

JamesDBBApi (JamesDB Bridge API)

A robust and modern database management API built with Hono, Sequelize, and TypeScript. JamesDBBApi provides a powerful RESTful interface to manage multiple databases, create dynamic schemas, and execute queries securely.

🚀 Features

Multi-Database Management

Multiple DBMS support: SQLite, PostgreSQL, MySQL, MariaDB, MSSQL
Simultaneous connections: Manage multiple databases in parallel
Health checks: Real-time monitoring of connection status
Dynamic configuration: Add/remove databases on the fly

Complete Schema API

Dynamic table creation: REST API to define your schemas
Advanced validation: Strict validation of data structures
Extended types: Support for 25+ SQL data types
Constraints and indexes: Complete management of constraints and indexes

Advanced Security

JWT authentication: Token-based authentication system
Role-based authorization: Granular access control
Rate limiting: Protection against abuse and DDoS attacks
Security headers: CORS, CSRF, HSTS, and more

Performance and Monitoring

Structured logging: Detailed logs with configurable levels
Real-time metrics: Monitoring endpoints and metrics
Optimizations: Connection pooling, cache, and SQL optimizations

📋 Prerequisites

Node.js >= 18.0.0 or Bun >= 1.0.0
A supported database (optional, SQLite by default)

🛠️ Installation

Quick Installation

Not using Bun yet ?

Windows : powershell -c "irm bun.sh/install.ps1 | iex"
Linux/Macos : curl -fsSL https://bun.sh/install | bash

# Clone the project
git clone https://github.com/Nokaji/JamesDBBApi
cd JamesDBBApi

# Install dependencies
bun install

# Copy configuration
cp .env.example .env

# Start in development mode
bun run dev

Configuration

Edit the .env file according to your needs:

# Application configuration
NODE_ENV=development
APP_PORT=3000
APP_HOST=localhost
API_VERSION=v1

# Primary database (SQLite by default)
DB_DIALECT=sqlite
SQLITE_PATH=./data/james.db

# Security
# IMPORTANT : Ne pas mettre de guillemets autour de la valeur !
JWT_SECRET=your-super-secret-jwt-key-here
CORS_ORIGINS=http://localhost:3000

🚀 Quick Start

1. Start the server

# Development with auto-reload
bun run dev

# Production
bun run prod

# With Docker
docker build -t JamesDBBApi .
docker run -p 3000:3000 JamesDBBApi

2. Verify operation

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

# API info
curl http://localhost:3000/api

3. Create your first table

curl -X POST http://localhost:3000/api/_schema/primary/tables \
  -H "Content-Type: application/json" \
  -d '{
    "table_name": "users",
    "columns": [
      {
        "name": "id",
        "type": "integer",
        "primary_key": true,
        "auto_increment": true
      },
      {
        "name": "email",
        "type": "email",
        "unique": true,
        "nullable": false
      },
      {
        "name": "name",
        "type": "string",
        "length": 100,
        "nullable": false
      },
      {
        "name": "created_at",
        "type": "timestamp",
        "default_value": "CURRENT_TIMESTAMP"
      }
    ]
  }'

📚 API Documentation

Main Endpoints

Method	Endpoint	Description
GET	`/`	Root endpoint (Welcome + info)
GET	`/api`	API information
GET	`/health`	Health check
GET	`/metrics`	System metrics
GET	`/docs`	Documentation (Swagger UI)
GET	`/swagger.json`	OpenAPI/Swagger spec

API v1 Endpoints

Method	Endpoint	Description
GET	`/api/v1/`	API info (versionné)
GET	`/api/v1/schema`	Schema routes
GET	`/api/v1/database`	Database routes
GET	`/api/v1/relation`	Relation routes

Les routes /api/v1/schema, /api/v1/database, /api/v1/relation sont des points d'entrée pour les sous-routes définies dans routes/schema.routes.ts, routes/database.routes.ts, routes/relation.routes.ts.

Authentification

The authtification is in the header: Authorization : Bearer {JWT_SECRET IN YOUR .ENV}

Exemples de routes (selon les sous-modules)

/api/v1/schema : gestion des schémas de BDD
/api/v1/database : gestion des connexions et opérations BDD
/api/v1/relation : gestion des relations entre tables

Connect a PostgreSQL database

curl -X POST http://localhost:3000/api/_database/connect \
  -H "Content-Type: application/json" \
  -d '{
    "name": "postgres_main",
    "config": {
      "dialect": "postgres",
      "host": "localhost",
      "port": 5432,
      "user": "postgres",
      "password": "password",
      "database": "my_app"
    }
  }'

Create a table with constraints

curl -X POST http://localhost:3000/api/_schema/postgres_main/tables \
  -H "Content-Type: application/json" \
  -d '{
    "table_name": "products",
    "columns": [
      {
        "name": "id",
        "type": "uuid",
        "primary_key": true,
        "default_value": "uuid_generate_v4()"
      },
      {
        "name": "name",
        "type": "string",
        "length": 255,
        "nullable": false
      },
      {
        "name": "price",
        "type": "decimal",
        "precision": 10,
        "scale": 2,
        "validate": {
          "min": 0
        }
      },
      {
        "name": "category_id",
        "type": "integer",
        "foreign_key": {
          "table": "categories",
          "column": "id",
          "on_delete": "CASCADE"
        }
      }
    ],
    "indexes": [
      {
        "name": "idx_products_name",
        "columns": ["name"],
        "unique": false
      },
      {
        "name": "idx_products_category",
        "columns": ["category_id"],
        "type": "BTREE"
      }
    ]
  }'

Execute a query

curl -X POST http://localhost:3000/api/_database/postgres_main/query \
  -H "Content-Type: application/json" \
  -d '{
    "query": "SELECT * FROM products WHERE price > 100 ORDER BY name LIMIT 10",
    "type": "SELECT"
  }'

🔧 Advanced Configuration

Environment Variables

Variable	Description	Default	Example
`NODE_ENV`	Runtime environment	`development`	`production`
`APP_PORT`	Listening port	`3000`	`8080`
`LOG_LEVEL`	Log level	`info`	`debug`
`JWT_SECRET`	JWT secret key	Auto-generated	`your-secret-key`
`RATE_LIMIT_MAX_REQUESTS`	Request limit	`100`	`1000`

Supported Data Types

Numeric Types

integer, int - Standard integer
smallint - Small integer
bigint - Large integer
float, double - Floating point numbers
decimal, numeric - Precise decimal numbers

Text Types

string, varchar - Variable character string
char - Fixed character string
text - Long text
email - Email with validation
url - URL with validation

Date/Time Types

timestamp, datetime - Date and time
date - Date only
time - Time only

Special Types

boolean - Boolean
uuid - Unique identifier
json, jsonb - JSON data
blob - Binary data

Authentication and Security

JWT Token Generation

// Client-side example
const response = await fetch("/api/auth/login", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    username: "admin",
    password: "password",
  }),
});

const { token } = await response.json();

// Using the token
const apiResponse = await fetch("/api/_database", {
  headers: {
    Authorization: `Bearer ${token}`,
  },
});
```javascript

#### Authorization Middleware

```typescript
import { authenticate, authorize, requireRole } from "./middlewares/auth";

// Protected routes
app.use("/api/_database/*", authenticate());
app.use("/api/_schema/*/tables", authorize("database:write"));
app.use("/api/admin/*", requireRole("admin"));

🧪 Testing and Development

Available Scripts

# Development
bun run dev          # Start with auto-reload
bun run build        # Build for production
bun run start        # Run built version

# Testing
bun run test         # Run tests
bun run test:watch   # Tests in watch mode

# Code quality
bun run lint         # Check code style
bun run format       # Format code

# Database
bun run db:migrate   # Apply migrations
bun run db:seed      # Seed with test data
bun run db:reset     # Reset database

# Docker
bun run docker:build # Build Docker image
bun run docker:run   # Run container

Project Structure

JamesDBBApi/
├── controllers/           # Controllers (to be implemented)
├── managers/
│   └── ConfigManager.ts   # Configuration manager
├── middlewares/
│   ├── auth.ts           # JWT authentication
│   ├── databaseManager.ts # Database manager
│   └── rateLimiter.ts    # Rate limiting
├── routes/
│   ├── _database.routes.ts # Database routes
│   └── _schema.routes.ts   # Schema routes
├── utils/
│   ├── convert.ts        # Schema conversion
│   ├── logging.ts        # Logging system
│   ├── runtime.ts        # Runtime detection
│   └── types.ts          # TypeScript types
├── index.ts              # Entry point
├── package.json
├── tsconfig.json
└── .env.example

🔍 Monitoring and Debugging

Monitoring Endpoints

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

# System metrics
curl http://localhost:3000/metrics

# Rate limiter status
curl http://localhost:3000/api/_database/rate-limit-status

Logs

Logs are structured and include:

Timestamp: Precise timestamp
Logger: Log source (DatabaseManager, AuthManager, etc.)
Level: Log level (DEBUG, INFO, WARN, ERROR)
Message: Detailed message

Example:

[2025-07-11T10:30:45.123Z] [DatabaseManager] [INFO]: Database 'primary' added and connected successfully
[2025-07-11T10:30:45.456Z] [AuthManager] [WARN]: Token expired for user john.doe

🚨 Security and Best Practices

Built-in Security

HTTPS required in production
Strict input validation
Rate limiting by IP and user
Automatic security headers
SQL sanitization via Sequelize

Recommendations

Change default secrets in production
Use HTTPS only in production
Limit database user permissions
Monitor logs regularly
Update dependencies regularly

🤝 Contributing

Contribution Guide

Fork the project
Create a branch for your feature
Develop following conventions
Test your code
Create a Pull Request

Code Standards

Strict TypeScript enabled
ESLint and Prettier for style
Unit tests required for new features
Public API documentation

📈 Roadmap

Version 1.1 (Coming Soon)

GraphQL interface
Integrated Redis cache
Automatic migrations
Web administration interface

Version 1.2 (Planned)

Clustering and load balancing
Complete audit trail
Automatic backup
API Analytics

🆘 Support and Troubleshooting

Common Issues

Database connection error

# Check configuration
curl http://localhost:3000/health

# Check logs
tail -f logs/app.log

Rate limiting too strict

# Adjust in .env
RATE_LIMIT_MAX_REQUESTS=1000
RATE_LIMIT_WINDOW_MS=3600000

JWT errors

# Generate new secret
JWT_SECRET=$(openssl rand -base64 32)

Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Documentation: Wiki

📄 License

This project is licensed under the MIT License. See the LICENSE file for more details.

JamesDBBApi - A modern database API for your applications 🚀

Developed with ❤️ by Nokaji

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
.vscode		.vscode
docs		docs
src		src
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
DOCKER.md		DOCKER.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
bun.lock		bun.lock
docker-compose.yml		docker-compose.yml
docker-entrypoint.sh		docker-entrypoint.sh
nginx.conf		nginx.conf
package.json		package.json
test-shutdown.sh		test-shutdown.sh
tsconfig.json		tsconfig.json
validate.sh		validate.sh

Latest commit

History

Folders and files

Repository files navigation

JamesDBBApi (JamesDB Bridge API)

🚀 Features

Multi-Database Management

Complete Schema API

Advanced Security

Performance and Monitoring

📋 Prerequisites

🛠️ Installation

Quick Installation

Configuration

🚀 Quick Start

1. Start the server

2. Verify operation

3. Create your first table

📚 API Documentation

Main Endpoints

API v1 Endpoints

Authentification

Exemples de routes (selon les sous-modules)

Connect a PostgreSQL database

Create a table with constraints

Execute a query

🔧 Advanced Configuration

Environment Variables

Supported Data Types

Numeric Types

Text Types

Date/Time Types

Special Types

Authentication and Security

JWT Token Generation

🧪 Testing and Development

Available Scripts

Project Structure

🔍 Monitoring and Debugging

Monitoring Endpoints

Logs

🚨 Security and Best Practices

Built-in Security

Recommendations

🤝 Contributing

Contribution Guide

Code Standards

📈 Roadmap

Version 1.1 (Coming Soon)

Version 1.2 (Planned)

🆘 Support and Troubleshooting

Common Issues

Database connection error

Rate limiting too strict

JWT errors

Support

📄 License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages