Convex Adapter

Relevant source files

The following files were used as context for generating this wiki page:

• packages/adapters/convex/src/index.ts
• packages/adapters/convex/src/transform/index.ts
• packages/adapters/convex/src/generate-schema/generate-schema-builder.ts
• packages/adapters/convex/test/schema.test.ts
• packages/adapters/convex/test/adapter.test.ts
• packages/adapters/convex/README.md
• packages/adapters/convex/src/generate-schema/index.ts

The Convex Adapter for Better Auth Kit is a database adapter designed to integrate the better-auth authentication framework with the Convex backend-as-a-service platform. It acts as a translation layer, converting Better Auth's generic database commands into Convex-specific queries and mutations. This allows developers to use Convex as the data persistence layer for user, session, and account management within a Better Auth application.

Important Note: This adapter is marked as deprecated. It is not recommended for use in new projects.

Sources: packages/adapters/convex/README.md, packages/adapters/convex/package.json

Core Functionality

The adapter is initialized by calling the convexAdapter factory function, which requires a ConvexHttpClient instance. This function returns an AdapterInstance that conforms to the better-auth adapter interface, providing implementations for standard data manipulation methods like create, findOne, findMany, update, and delete.

Sources: packages/adapters/convex/src/index.ts:12-15, packages/adapters/convex/test/adapter.test.ts:11-17

Initialization

The adapter can be configured with an optional ConvexAdapterOptions object, which can be used to enable debug logging.

// packages/adapters/convex/test/adapter.test.ts:12-15
const client = new ConvexClient(process.env.CONVEX_URL as string);

const auth = betterAuth({
    database: convexAdapter(client),
});

The following diagram illustrates the initialization flow of the Convex adapter.

Database Operations

The adapter implements the full set of database operations required by Better Auth. It uses a set of internal handler functions (queryDb, insertDb, updateDb, deleteDb) to communicate with the Convex backend via internal mutations and queries defined in convex/betterAuth.ts.

Sources: packages/adapters/convex/src/transform/index.ts:74-118, packages/adapters/convex/src/index.ts:28-238

Query Operations (findOne, findMany)

For read operations, the adapter constructs a query string using a queryBuilder. This builder translates the where clauses from Better Auth's format into a Convex query expression. The findMany operation supports pagination through offset and limit, which it implements by repeatedly fetching pages of data from Convex until the desired offset and limit are satisfied.

The diagram below shows the sequence of a findOne call.

Write Operations (create, update, delete)

Write operations (create, update, delete) also use the queryBuilder to target specific documents for updates and deletions. For create and update operations, input data is passed through transformInput before being sent to Convex. The results are then processed by transformOutput.

Sources: packages/adapters/convex/src/index.ts:40-57, packages/adapters/convex/src/index.ts:136-212

Data Transformation

A crucial part of the adapter is its data transformation layer, which bridges the differences between Better Auth's data conventions and Convex's. This is handled by the createTransform utility.

Sources: packages/adapters/convex/src/transform/index.ts

Input Transformation (transformInput)

This function prepares data before it's sent to the Convex database.

• It converts Date objects to ISO 8601 strings.
• It applies default values for fields during create operations.
• It maps Better Auth's conventional field names (e.g., id) to the corresponding fields in the database schema, although it explicitly removes the id and createdAt fields from the transformed data, as Convex manages these automatically (_id, _creationTime).

The following diagram shows the input transformation flow.

Output Transformation (transformOutput)

This function processes data returned from Convex to match Better Auth's expectations.

• It renames Convex's internal _id field to id.
• It renames Convex's internal _creationTime field to createdAt and converts it into a Date object.
• It converts any other fields of type date from strings back into Date objects.

Sources: packages/adapters/convex/src/transform/index.ts:151-166

Operator Transformation (transformWhereOperators)

Convex's query engine has a limited set of operators. This function translates operators that are not natively supported. For example, it converts a where clause with an in operator into a series of eq clauses joined by OR.

Sources: packages/adapters/convex/src/transform/index.ts:21-36

Schema Generation

The adapter includes a utility to automatically generate and update the convex/schema.ts file based on the Better Auth configuration, including any schemas provided by plugins.

Sources: packages/adapters/convex/src/generate-schema/index.ts

Generation Process

The generateSchema function orchestrates the process:

1. Reads the existing convex/schema.ts file.
2. Ensures the necessary imports (defineSchema, defineTable, v) are present.
3. Parses the existing schema to identify user-defined tables and fields.
4. Retrieves the required auth tables (user, session, account, verification) and any tables from plugins.
5. Converts the Better Auth schema definitions into Convex defineTable syntax.
6. Merges the generated auth tables with the existing user-defined tables.
7. Formats the final schema string using Prettier and returns it.

This flow is visualized below:

Data Type Mapping

The schema generator maps Better Auth field types to Convex validation types (v values).

Better Auth Type	Convex Type (v)	Required	Optional	Notes
string	v.string()	✅	✅
boolean	v.boolean()	✅	✅
number	v.number()	✅	✅
date	v.string()	✅	✅	Dates are stored as ISO strings.
string[]	v.array()	✅	✅	The array contains strings.
number[]	v.array()	✅	✅	The array contains numbers.
references	v.id("model")	✅	✅	Creates a reference to another table.

Sources: packages/adapters/convex/src/generate-schema/generate-schema-builder.ts:100-112, packages/adapters/convex/test/schema.test.ts:182-198

Default Database Schema

The adapter relies on a default schema for core authentication functionality. This schema defines the user, session, account, and verification tables.

This ER diagram shows the relationships between the default tables.

Conclusion

The Better Auth Kit Convex Adapter provides a comprehensive bridge to use Convex as a backend for better-auth. It handles the translation of database operations, manages data transformations between the two systems, and includes a powerful schema generation tool to keep the Convex schema in sync with the application's auth configuration. However, as the package is deprecated, developers should avoid using it for new projects and seek alternative solutions.

Sources: packages/adapters/convex/README.md