@dataql/typeorm-adapter

Migrate from TypeORM to DataQL with zero API changes. This adapter provides a TypeORM-compatible API that runs on DataQL with automatic scaling, caching, and offline support.

Installation

npm install @dataql/core @dataql/typeorm-adapter reflect-metadata

Quick Start

import "reflect-metadata";
import {
  createDataSource,
  Entity,
  Column,
  PrimaryGeneratedColumn,
  Repository,
} from "@dataql/typeorm-adapter";

// Define your entities exactly like TypeORM
@Entity("users")
class User {
  @PrimaryGeneratedColumn()
  id!: number;

  @Column({ type: "varchar", length: 255 })
  name!: string;

  @Column({ type: "varchar", length: 255, unique: true })
  email!: string;

  @Column({ type: "integer", nullable: true })
  age?: number;
}

// Initialize DataQL with proper configuration
const dataSource = createDataSource({
  appToken: "your-app-token", // Required for DataQL authentication
  env: "prod", // Environment: 'dev' or 'prod'
  dbName: "your_app_db", // Database name for data isolation
});

await dataSource.initialize();

// Get repository and use familiar TypeORM syntax
const userRepository: Repository<User> = dataSource.getRepository(User);

const user = await userRepository.save({
  name: "John Doe",
  email: "[email protected]",
  age: 30,
});

const allUsers = await userRepository.find();
const activeUser = await userRepository.findOneBy({
  email: "[email protected]",
});

Configuration

const dataSource = createDataSource({
  appToken: "your-app-token", // Required - authentication for DataQL
  env: "prod", // Optional - 'dev' or 'prod' (default: 'prod')
  devPrefix: "dev_", // Optional - prefix for dev environment tables
  dbName: "your_app_db", // Optional - database name for data isolation
  customConnection: undefined, // Optional - for custom integrations
});

Configuration Options

• appToken (required): Authentication token for DataQL
• env: Environment - 'dev' or 'prod' (default: 'prod')
• devPrefix: Table prefix for development environment (default: 'dev_')
• dbName: Database name for data isolation (each client gets dedicated database)
• customConnection: Advanced option for custom integrations

Benefits Over Direct TypeORM

While maintaining 100% TypeORM API compatibility, you get DataQL's enhanced capabilities:

• Simplified Setup: No need to manage database connections, credentials, or servers
• Auto-scaling: Automatic scaling based on usage
• Offline-first: Built-in offline support with automatic sync when online
• Real-time: Live data updates across all connected clients
• Global Performance: Data served from edge locations worldwide for low latency
• Data Isolation: Each client gets their own dedicated database automatically
• Multi-layer Caching: Optimized performance with intelligent caching

Migration Guide

From TypeORM

1. Replace imports:

   // Before
   import { DataSource, Entity, Column, PrimaryGeneratedColumn } from "typeorm";
   
   // After
   import "reflect-metadata";
   import {
     createDataSource,
     Entity,
     Column,
     PrimaryGeneratedColumn,
   } from "@dataql/typeorm-adapter";

2. Update data source configuration:

   // Before - Direct database connection
   const dataSource = new DataSource({
     type: "postgres",
     host: "localhost",
     port: 5432,
     username: "user",
     password: "password",
     database: "mydb",
     entities: [User, Post],
   });
   
   // After - DataQL powered
   const dataSource = createDataSource({
     appToken: "your-app-token", // Required for DataQL authentication
     dbName: "your_app_db", // Your database name
   });

3. Your entities work exactly the same:

   // This works exactly the same - but now routes through DataQL infrastructure
   @Entity("users")
   class User {
     @PrimaryGeneratedColumn()
     id!: number;
   
     @Column()
     name!: string;
   }

API Compatibility

Supported TypeORM Features

Decorators

• ✅ @Entity() - Entity definition
• ✅ @Column() - Column definition with options
• ✅ @PrimaryColumn() - Primary key columns
• ✅ @PrimaryGeneratedColumn() - Auto-generated primary keys

Column Types

• ✅ varchar, text, int, integer, decimal, boolean, timestamp, date, json
• ✅ Column options: nullable, unique, default, length

Repository Methods

• ✅ find() - Find multiple entities
• ✅ findOne() - Find single entity
• ✅ findOneBy() - Find by criteria
• ✅ findBy() - Find multiple by criteria
• ✅ save() - Save entity or array of entities
• ✅ insert() - Insert new records
• ✅ update() - Update existing records
• ✅ delete() - Delete records
• ✅ remove() - Remove entities
• ✅ count() - Count records

Query Builder

• ✅ createQueryBuilder() - Create query builder
• ✅ .where(), .andWhere() - Filter conditions
• ✅ .orderBy() - Sorting
• ✅ .take(), .skip() - Pagination
• ✅ .getMany(), .getOne() - Execute queries

Find Operators

• ✅ MoreThan, LessThan, MoreThanOrEqual, LessThanOrEqual
• ✅ Like, ILike
• ✅ In, Not
• ✅ IsNull, Between

Advanced Features

• ✅ Transactions via DataSource.transaction()
• ✅ Entity Manager for transaction contexts
• ✅ TypeScript type inference
• ✅ Data source initialization and cleanup

DataQL Enhancements

While maintaining TypeORM compatibility, you also get DataQL's additional features:

• Offline-first: Automatic offline support and sync
• Real-time: Built-in real-time updates
• Multi-region: Global data distribution
• Schema evolution: Dynamic schema updates
• WAL support: Write-ahead logging for reliability
• Unique document creation: Enhanced duplicate prevention

TypeScript Support

Full TypeScript support with proper decorators and metadata:

import "reflect-metadata"; // Required for decorators

@Entity("users")
class User {
  @PrimaryGeneratedColumn()
  id!: number;

  @Column({ type: "varchar", length: 255, nullable: false })
  name!: string;

  @Column({ type: "varchar", length: 255, unique: true })
  email!: string;
}

// Full type inference
const userRepository: Repository<User> = dataSource.getRepository(User);
const user: User | null = await userRepository.findOneBy({
  email: "[email protected]",
});

Prerequisites

This adapter requires reflect-metadata for decorator support:

npm install reflect-metadata

Import it at the top of your main application file:

import "reflect-metadata";

Limitations

Some advanced TypeORM features are not yet supported:

• Relations (@OneToMany, @ManyToOne, etc.)
• Complex entity inheritance
• Custom repositories
• Migration system
• Advanced query builder features (joins, subqueries)
• Raw SQL queries

If you need these features, please open an issue.

Performance Considerations

DataQL automatically optimizes your queries through:

• Edge caching: Frequently accessed data cached globally
• Query optimization: Automatic query plan optimization
• Connection pooling: Managed automatically
• Auto-scaling: Resources scale based on demand

No manual optimization required!

License

MIT