@dataql/drizzle-adapter

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

Installation

npm install @dataql/core @dataql/drizzle-adapter

Quick Start

import { drizzle } from "@dataql/drizzle-adapter";
import { pgTable, serial, varchar, integer } from "@dataql/drizzle-adapter";

// Define your schema exactly like Drizzle
const users = pgTable("users", {
  id: serial("id").primaryKey(),
  name: varchar("name", { length: 256 }),
  email: varchar("email", { length: 256 }),
  age: integer("age"),
});

const posts = pgTable("posts", {
  id: serial("id").primaryKey(),
  title: varchar("title", { length: 256 }),
  content: varchar("content", { length: 1000 }),
  authorId: integer("author_id").references(() => users.id),
});

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

// Register your tables
db.registerTable(users);
db.registerTable(posts);

// Use familiar Drizzle syntax - all operations powered by DataQL
const allUsers = await db.select().from(users).execute();

const user = await db.insert(users).values({
  name: "John Doe",
  email: "john@example.com",
  age: 30,
});

const userPosts = await db
  .select()
  .from(posts)
  .leftJoin(users, eq(posts.authorId, users.id))
  .where(eq(users.id, 1))
  .execute();

Configuration

const db = drizzle({
  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 Drizzle

While maintaining 100% Drizzle 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 Drizzle ORM

1. Replace imports:

   // Before
   import { drizzle } from "drizzle-orm/postgres-js";
   import { pgTable, serial, varchar } from "drizzle-orm/pg-core";
   
   // After
   import { drizzle, pgTable, serial, varchar } from "@dataql/drizzle-adapter";

2. Update database connection:

   // Before - Direct database connection
   const db = drizzle(postgres(connectionString));
   
   // After - DataQL powered
   const db = drizzle({
     appToken: "your-app-token", // Required for DataQL authentication
     dbName: "your_app_db", // Your database name
   });

3. Register tables (new requirement):

   // Register your tables with DataQL
   db.registerTable(users);
   db.registerTable(posts);

4. Your queries work exactly the same:

   // This works exactly the same - but now routes through DataQL infrastructure
   const users = await db.select().from(usersTable).execute();

API Compatibility

Supported Drizzle Features

Table Definition

• ✅ pgTable(), mysqlTable(), sqliteTable()
• ✅ Column types: serial, varchar, text, integer, decimal, boolean, timestamp, date, json, jsonb
• ✅ Column modifiers: .primaryKey(), .notNull(), .unique(), .default()
• ✅ Foreign key references: .references()

Query Builder

• ✅ select() - Select data
• ✅ insert() - Insert new records
• ✅ update() - Update existing records
• ✅ delete() - Delete records
• ✅ .from() - Specify table
• ✅ .where() - Filter conditions
• ✅ .leftJoin(), .innerJoin() - Table joins
• ✅ .limit(), .offset() - Pagination
• ✅ .orderBy() - Sorting

Operators

• ✅ eq, ne, gt, gte, lt, lte
• ✅ like, ilike
• ✅ isNull, isNotNull
• ✅ inArray, notInArray

Advanced Features

• ✅ Transactions
• ✅ TypeScript type inference
• ✅ Schema validation

DataQL Enhancements

While maintaining Drizzle 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: createUnique() method to prevent duplicates

TypeScript Support

Full TypeScript support with inferred types:

import { InferSelectModel, InferInsertModel } from "@dataql/drizzle-adapter";

type User = InferSelectModel<typeof users>;
type NewUser = InferInsertModel<typeof users>;

const user: User = await db
  .select()
  .from(users)
  .where(eq(users.id, 1))
  .execute();
const newUser: NewUser = { name: "Jane", email: "jane@example.com" };

Limitations

Some advanced Drizzle features are not yet supported:

• Custom schema names
• Advanced SQL functions
• Raw SQL queries
• Prepared statements
• Complex subqueries

If you need these features, please open an issue.

License

MIT