Skip to main content

API Reference

Complete API documentation for the @pressw/threads-drizzle adapter.

DrizzleAdapter

The main adapter class that implements the ChatCoreAdapter interface for Drizzle ORM.

Constructor

new DrizzleAdapter(db: DrizzleDB, config: DrizzleAdapterConfig)

Parameters

  • db: Drizzle database instance
  • config: Adapter configuration object

Example

import { DrizzleAdapter } from '@pressw/threads-drizzle';
import { drizzle } from 'drizzle-orm/postgres-js';

const db = drizzle(connection);
const adapter = new DrizzleAdapter(db, {
provider: 'postgres',
tables: {
user: 'users',
thread: 'threads',
feedback: 'feedback',
},
});

Configuration

DrizzleAdapterConfig

interface DrizzleAdapterConfig extends AdapterConfig {
provider: DatabaseProvider;
tables: {
user: string;
thread: string;
feedback: string;
};
fields?: {
user?: FieldMapping;
thread?: FieldMapping;
feedback?: FieldMapping;
};
}

Properties

PropertyTypeRequiredDescription
provider'postgres' | 'mysql' | 'sqlite'YesDatabase provider
tablesobjectYesTable name mappings
fieldsobjectNoColumn name mappings
supportsJSONbooleanNoWhether database supports JSON (default: based on provider)
supportsDatesbooleanNoWhether database supports Date types (default: true)
supportsBooleansbooleanNoWhether database supports boolean types (default: true)
supportsReturningbooleanNoWhether database supports RETURNING clause (default: based on provider)
generateId() => stringNoCustom ID generation function
disableIdGenerationbooleanNoDisable automatic ID generation

Field Mapping

Map ChatCore field names to your database column names:

interface FieldMapping {
id?: string;
title?: string;
userId?: string;
organizationId?: string;
tenantId?: string;
metadata?: string;
createdAt?: string;
updatedAt?: string;
}

Example

{
fields: {
thread: {
id: 'thread_id',
userId: 'owner_id',
title: 'subject',
metadata: 'custom_data',
createdAt: 'created_date',
updatedAt: 'modified_date',
},
},
}

Methods

create

Creates a new record in the database.

create<T extends Record<string, unknown>>(params: {
model: string;
data: T;
select?: string[];
}): Promise<T>

Parameters

  • model: Model name ('user', 'thread', 'feedback')
  • data: Data to insert
  • select: Fields to return (optional)

Example

const thread = await adapter.create({
model: 'thread',
data: {
id: 'thread-123',
title: 'Support Thread',
userId: 'user-456',
metadata: { priority: 'high' },
createdAt: new Date(),
updatedAt: new Date(),
},
});

findOne

Finds a single record matching the criteria.

findOne<T>(params: {
model: string;
where: Where[];
select?: string[];
}): Promise<T | null>

Parameters

  • model: Model name
  • where: Array of where conditions
  • select: Fields to return (optional)

Example

const thread = await adapter.findOne({
model: 'thread',
where: [
{ field: 'id', value: 'thread-123' },
{ field: 'userId', value: 'user-456' },
],
});

findMany

Finds multiple records matching the criteria.

findMany<T>(params: {
model: string;
where?: Where[];
limit?: number;
offset?: number;
sortBy?: SortBy;
}): Promise<T[]>

Parameters

  • model: Model name
  • where: Array of where conditions (optional)
  • limit: Maximum records to return (default: 100)
  • offset: Number of records to skip
  • sortBy: Sort configuration

Example

const threads = await adapter.findMany({
model: 'thread',
where: [{ field: 'userId', value: 'user-456' }],
limit: 20,
offset: 0,
sortBy: {
field: 'createdAt',
direction: 'desc',
},
});

update

Updates records matching the criteria.

update<T>(params: {
model: string;
where: Where[];
data: Partial<T>;
}): Promise<T | null>

Parameters

  • model: Model name
  • where: Array of where conditions
  • data: Fields to update

Example

const updated = await adapter.update({
model: 'thread',
where: [{ field: 'id', value: 'thread-123' }],
data: {
title: 'Updated Title',
metadata: { status: 'resolved' },
updatedAt: new Date(),
},
});

delete

Deletes records matching the criteria.

delete(params: {
model: string;
where: Where[];
}): Promise<void>

Parameters

  • model: Model name
  • where: Array of where conditions

Example

await adapter.delete({
model: 'thread',
where: [{ field: 'id', value: 'thread-123' }],
});

count

Counts records matching the criteria.

count(params: {
model: string;
where?: Where[];
}): Promise<number>

Parameters

  • model: Model name
  • where: Array of where conditions (optional)

Example

const count = await adapter.count({
model: 'thread',
where: [{ field: 'userId', value: 'user-456' }],
});

getSchema

Returns the Drizzle table schema for a model.

getSchema(model: string): TableSchema | undefined

Parameters

  • model: Model name

Example

const threadSchema = adapter.getSchema('thread');
// Use with Drizzle for custom queries
const results = await db.select().from(threadSchema);

Where Conditions

Where Interface

interface Where {
field: string;
value: string | number | boolean | Date | null | string[] | number[];
operator?: WhereOperator;
connector?: 'AND' | 'OR';
}

Operators

OperatorDescriptionSQL Equivalent
eqEqual (default)=
neNot equal!=
gtGreater than>
gteGreater than or equal>=
ltLess than<
lteLess than or equal<=
inIn arrayIN
containsContains (text/JSON)LIKE %value% or @>
starts_withStarts withLIKE value%
ends_withEnds withLIKE %value

Examples

// Simple equality
{ field: 'userId', value: 'user-123' }

// With operator
{ field: 'createdAt', value: new Date('2024-01-01'), operator: 'gte' }

// Array contains
{ field: 'tags', value: ['support', 'billing'], operator: 'in' }

// Text search
{ field: 'title', value: 'customer', operator: 'contains' }

// JSON contains (PostgreSQL)
{ field: 'metadata', value: { status: 'active' }, operator: 'contains' }

// Multiple conditions with OR
[
{ field: 'status', value: 'active', connector: 'OR' },
{ field: 'status', value: 'pending', connector: 'OR' },
]

Sort Configuration

interface SortBy {
field: string;
direction: 'asc' | 'desc';
}

Example

// Sort by created date, newest first
{
field: 'createdAt',
direction: 'desc'
}

// Sort by title alphabetically
{
field: 'title',
direction: 'asc'
}

Data Type Handling

JSON Fields

The adapter automatically handles JSON serialization based on database support:

// PostgreSQL/MySQL with JSON support
const thread = await adapter.create({
model: 'thread',
data: {
metadata: { complex: { nested: 'object' } }, // Stored as native JSON
},
});

// SQLite without JSON support
// Same code works - adapter stringifies/parses automatically

Date Fields

Dates are automatically converted based on database support:

// All databases
const thread = await adapter.create({
model: 'thread',
data: {
createdAt: new Date(), // Stored appropriately for each DB
},
});

// SQLite: Stored as Unix timestamp
// PostgreSQL/MySQL: Stored as native timestamp

Boolean Fields

Booleans are handled based on database capabilities:

// PostgreSQL/MySQL
{
helpful: true;
} // Stored as native boolean

// SQLite without boolean support
{
helpful: true;
} // Stored as 1/0, converted automatically

Error Handling

The adapter throws standard errors that should be caught:

try {
await adapter.create({ model: 'thread', data });
} catch (error) {
if (error.code === 'P2002') {
// Unique constraint violation (Prisma/Drizzle)
} else if (error.message.includes('Required field')) {
// Validation error
} else {
// Other database error
}
}

Common Errors

ErrorDescriptionSolution
Table "x" not foundTable doesn't exist in schemaCheck table configuration
Required field "x" not foundMissing required columnAdd field mapping or column
Model "x" not foundInvalid model nameUse 'user', 'thread', or 'feedback'
Field "x" not found in tableColumn doesn't existCheck field mapping

Performance Tips

  1. Use indexes for frequently queried fields
  2. Limit result sets with pagination
  3. Use field selection to reduce data transfer
  4. Consider connection pooling for high traffic
  5. Use transactions for related operations

Next Steps