Open Source • Type-Safe • Zero Runtime Overhead

Type-safe ORM for
Azure CosmosDB

Build faster with full type safety. CosmosQL prevents costly mistakes at compile time, not in production.

Get Started →Documentation

npm install cosmosql • TypeScript 5+ • Node 18+

app.ts
TypeScript
import { createClient, container, field } from 'cosmosql';

// Define your schema with full type safety
const users = container('users', {
  id: field.string(),
  email: field.string(),
  name: field.string(),
  age: field.number()
}).partitionKey('email');

const db = createClient({
  connectionString: process.env.COSMOS_CONNECTION_STRING!,
  database: 'myapp'
}).withContainers({ users });

// TypeScript catches errors before runtime
const user = await db.users.findUnique({
  where: {
    id: 'user_123',
    email: 'john@example.com' // Partition key required!
  }
});

// Fully typed result
console.log(user.name); // ✓ TypeScript knows this exists

Why CosmosQL?

Stop fighting with CosmosDB. Start building.

🎯

Catch Errors Early

TypeScript catches mistakes before production

⚡

Zero Overhead

Direct REST calls. Compile-time validation only

🧠

Best Practices Built-in

Partition keys enforced. Cross-partition queries prevented

// Create a new user with full type safety
const newUser = await db.users.create({
  data: {
    id: 'user_123',
    email: 'john@example.com',
    name: 'John Doe',
    age: 30,
    isActive: true,
    createdAt: new Date()
  }
});

// TypeScript ensures all required fields are provided
// and types match your schema exactly

Everything you need, built-in

Migrations, management, and bulk operations - no extra setup required

🔄

Migrations

Schema evolution with versioning, rollback support, and dry-run previews

Learn more →
⚙️

Database Management

Health checks, schema validation, and container management tools

Learn more →
📦

Bulk Operations

Efficient batch updates and deletes with progress tracking and error handling

Learn more →
migrations.ts
const migration = defineMigration({
  version: 1,
  name: 'add-preferences',
  async up({ db, logger }) {
    await db.users.updateMany({
      where: {},
      data: (doc) => ({
        preferences: { theme: 'light' }
      }),
      enableCrossPartitionQuery: true
    });
  }
});

await db.migrations.apply({
  target: 'latest',
  confirm: true
});
management.ts
// Health check
const health = await db.management
  .healthCheck();
console.log(health.overallHealth);

// Schema diff
const diff = await db.management
  .diffSchema();
if (diff.requiresAction) {
  console.log('Schema drift!');
}

// Database info
const info = await db.management
  .getDatabaseInfo();

Get started in 60 seconds

Three steps to type-safe CosmosDB queries

01

Install

npm install cosmosql
02

Define schema

const users = container('users', {
  id: field.string(),
  email: field.string()
}).partitionKey('email');
03

Query with type safety

const user = await db.users.findUnique({
  where: { id: '123', email: 'user@example.com' }
});
Read the full guide →

Start building today

Join developers using CosmosQL to build type-safe applications on Azure CosmosDB

Get Started →View Documentation