@mdxdb/payload

Payload CMS database adapter for mdxdb - supports SQLite (Durable Objects) and ClickHouse backends on Cloudflare Workers.

Installation

pnpm add @mdxdb/payload payload

Usage

SQLite Adapter (Durable Objects)

import { buildConfig } from 'payload'
import { sqliteAdapter, getNativeCollections } from '@mdxdb/payload'

export default buildConfig({
  db: sqliteAdapter({
    binding: env.MDXDB,
    namespace: 'example.com',
  }),
  collections: [
    ...getNativeCollections(),
    // Your custom collections
  ],
})

ClickHouse Adapter

import { buildConfig } from 'payload'
import { clickhouseAdapter } from '@mdxdb/payload/clickhouse'

export default buildConfig({
  db: clickhouseAdapter({
    url: env.CLICKHOUSE_URL,
    username: env.CLICKHOUSE_USERNAME,
    password: env.CLICKHOUSE_PASSWORD,
    namespace: 'example.com',
  }),
  collections: [...],
})

Native Collections

mdxdb's core entities can be exposed as Payload collections:

import { getNativeCollections } from '@mdxdb/payload'

// Include all native collections
const collections = getNativeCollections()

// Or select specific ones
const collections = getNativeCollections({
  things: true,        // Graph nodes
  relationships: true, // Graph edges
  search: true,        // Indexed content with embeddings
  events: true,        // Immutable event log
  actions: true,       // Jobs/Tasks/Workflows queue
  artifacts: true,     // Cached compiled content
})

Available Collections

| Collection | Description | |------------|-------------| | things | Graph nodes - the core entity type | | relationships | Graph edges connecting Things | | search | Indexed content with vector embeddings | | events | Immutable event log (audit/analytics) | | actions | Jobs queue - Tasks, Workflows, Background Jobs | | artifacts | Cached compiled content and build artifacts |

Virtual Collections

Create Payload collections that map to mdxdb Thing types:

import { createVirtualCollection } from '@mdxdb/payload'

const PostsCollection = createVirtualCollection({
  slug: 'posts',
  type: 'Post',
  fields: [
    {
      name: 'author',
      type: 'relationship',
      relationTo: 'users',
    },
    {
      name: 'tags',
      type: 'json',
    },
  ],
})

How It Works

Collections → Things

Payload documents are stored as mdxdb Things:

• Collection slug → Thing type (PascalCase)
• Document ID → Thing ID
• Document data → Thing data
• Timestamps → Thing timestamps

Relationships → Graph Edges

Payload relationship fields are converted to mdxdb Relationships:

• Each relationship field creates an edge
• hasMany creates multiple edges
• Join fields query reverse relationships

Jobs/Tasks → Actions

Payload's jobs queue maps to mdxdb Actions:

• Jobs → Actions with status: 'pending'
• Tasks → Actions with verb conjugations (act, action, activity)
• Workflows → Actions with parent/children hierarchy

Versions → Branches

Payload's version history maps to mdxdb's branching:

• Drafts → Things with branch: 'draft'
• Published → Things with branch: 'main'
• Version history → Thing versions within branch

API

sqliteAdapter(config)

Create a SQLite adapter using Durable Objects.

interface SQLiteAdapterConfig {
  binding: DurableObjectNamespace  // env.MDXDB
  namespace?: string               // Default namespace
  idType?: 'uuid' | 'number'       // ID type
  debug?: boolean                  // Enable debug logging
}

clickhouseAdapter(config)

Create a ClickHouse adapter using HTTP.

interface ClickHouseAdapterConfig {
  url: string                    // ClickHouse HTTP URL
  username?: string              // Authentication
  password?: string
  database?: string              // Database name (default: mdxdb)
  namespace?: string             // Default namespace
  cacheTtl?: number              // Cache TTL in seconds
  debug?: boolean
}

getNativeCollections(options)

Get Payload collections for mdxdb's native entities.

createVirtualCollection(options)

Create a Payload collection backed by mdxdb Things of a specific type.

License

MIT