or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

adapter-configuration.mddrizzle-integration.mdindex.mdmigration-system.md
tile.json

tessl/npm-payloadcms--db-sqlite

The officially supported SQLite database adapter for PayloadCMS with Drizzle ORM integration.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@payloadcms/db-sqlite@3.54.x

To install, run

npx @tessl/cli install tessl/npm-payloadcms--db-sqlite@3.54.0

index.mddocs/

Payload SQLite Adapter

The officially supported SQLite database adapter for PayloadCMS, providing seamless integration between Payload and SQLite databases. This adapter enables developers to use SQLite as the database backend for Payload projects, offering a lightweight, file-based database solution ideal for development, testing, and small to medium-scale applications.

Package Information

  • Package Name: @payloadcms/db-sqlite
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @payloadcms/db-sqlite

Core Imports

import { sqliteAdapter } from "@payloadcms/db-sqlite";

For type imports:

import type { SQLiteAdapterArgs, SQLiteAdapter, MigrateUpArgs, MigrateDownArgs } from "@payloadcms/db-sqlite";

CommonJS:

const { sqliteAdapter } = require("@payloadcms/db-sqlite");

Basic Usage

import { buildConfig } from 'payload/config';
import { sqliteAdapter } from '@payloadcms/db-sqlite';

export default buildConfig({
  db: sqliteAdapter({
    client: {
      url: process.env.DATABASE_URI || './payload.db',
    },
  }),
  // ...rest of config
});

Architecture

The SQLite adapter is built around several key components:

  • Database Adapter: Core sqliteAdapter function that creates a Payload-compatible database adapter
  • Drizzle Integration: Utilizes Drizzle ORM for type-safe database operations and query building
  • LibSQL Support: Supports both traditional SQLite and LibSQL (Turso) clients for flexible deployment
  • Schema Management: Automatic schema generation, migration handling, and table management
  • Type Safety: Full TypeScript integration with comprehensive type definitions
  • Hook System: Before/after schema initialization hooks for custom schema transformations

Capabilities

SQLite Adapter Configuration

Core adapter factory function for creating SQLite database adapters with comprehensive configuration options.

function sqliteAdapter(args: SQLiteAdapterArgs): DatabaseAdapterObj<SQLiteAdapter>;

interface SQLiteAdapterArgs {
  /** LibSQL client configuration (required) */
  client: {
    url: string;
    authToken?: string;
    [key: string]: any;
  };
  /** ID type selection - 'number' for auto-increment integers, 'uuid' for UUIDs */
  idType?: 'number' | 'uuid';
  /** Enable custom ID specification during create operations */
  allowIDOnCreate?: boolean;
  /** Enable AUTOINCREMENT for Primary Keys to prevent ID reuse */
  autoIncrement?: boolean;
  /** Store blocks as JSON column instead of relational structure */
  blocksAsJSON?: boolean;
  /** SQLite transaction configuration */
  transactionOptions?: false | SQLiteTransactionConfig;
  /** Migration directory path */
  migrationDir?: string;
  /** Suffix for locale tables */
  localesSuffix?: string;
  /** Suffix for relationship tables */
  relationshipsSuffix?: string;
  /** Suffix for version tables */
  versionsSuffix?: string;
  /** Schema name */
  schemaName?: string;
  /** Generated schema output file path */
  generateSchemaOutputFile?: string;
  /** Drizzle logger configuration */
  logger?: DrizzleConfig['logger'];
  /** Production migration definitions */
  prodMigrations?: {
    down: (args: MigrateDownArgs) => Promise<void>;
    name: string;
    up: (args: MigrateUpArgs) => Promise<void>;
  }[];
  /** Enable schema push mode */
  push?: boolean;
  /** Pre-schema initialization hooks */
  beforeSchemaInit?: SQLiteSchemaHook[];
  /** Post-schema initialization hooks */
  afterSchemaInit?: SQLiteSchemaHook[];
}

Adapter Configuration

Migration System

Comprehensive migration utilities for database schema management and data transformations.

interface MigrateUpArgs {
  /** SQLite Drizzle instance for direct SQL execution within transaction */
  db: Drizzle;
  /** Payload instance for Local API method execution */
  payload: Payload;
  /** PayloadRequest object containing current transaction */
  req: PayloadRequest;
}

interface MigrateDownArgs {
  /** SQLite Drizzle instance for direct SQL execution within transaction */
  db: Drizzle;
  /** Payload instance for Local API method execution */
  payload: Payload;
  /** PayloadRequest object containing current transaction */
  req: PayloadRequest;
}

Migration System

Drizzle ORM Integration

Direct access to Drizzle ORM functionality for advanced database operations and custom queries.

// Re-exported from drizzle-orm
import { sql } from "@payloadcms/db-sqlite";

// Access to Drizzle modules via subpaths
import * as drizzleCore from "@payloadcms/db-sqlite/drizzle";
import * as sqliteCore from "@payloadcms/db-sqlite/drizzle/sqlite-core";
import * as libsql from "@payloadcms/db-sqlite/drizzle/libsql";
import * as relations from "@payloadcms/db-sqlite/drizzle/relations";

Drizzle Integration

Types

interface SQLiteAdapter extends DrizzleAdapter {
  /** Schema transformation hooks executed after schema building */
  afterSchemaInit: SQLiteSchemaHook[];
  /** Enable AUTOINCREMENT for Primary Keys */
  autoIncrement: boolean;
  /** Schema transformation hooks executed before schema building */
  beforeSchemaInit: SQLiteSchemaHook[];
  /** LibSQL client instance */
  client: Client;
  /** Original client configuration */
  clientConfig: SQLiteAdapterArgs['client'];
  /** Count distinct values utility */
  countDistinct: CountDistinct;
  /** Default Drizzle snapshot */
  defaultDrizzleSnapshot: any;
  /** Conditional delete utility */
  deleteWhere: DeleteWhere;
  /** Drizzle database instance */
  drizzle: Drizzle;
  /** Drop database utility */
  dropDatabase: DropDatabase;
  /** SQL execution utility */
  execute: Execute<unknown>;
  /** Field constraint mappings for error handling */
  fieldConstraints: Record<string, Record<string, string>>;
  /** ID type configuration */
  idType: 'number' | 'uuid';
  /** Initialization promise */
  initializing: Promise<void>;
  /** Insert operation utility */
  insert: Insert;
  /** Locale table suffix */
  localesSuffix?: string;
  /** Drizzle logger */
  logger: DrizzleConfig['logger'];
  /** Query operators mapping */
  operators: Operators;
  /** Production migrations */
  prodMigrations?: {
    down: (args: MigrateDownArgs) => Promise<void>;
    name: string;
    up: (args: MigrateUpArgs) => Promise<void>;
  }[];
  /** Schema push mode enabled */
  push: boolean;
  /** Initialization rejection handler */
  rejectInitializing: () => void;
  /** Database relations */
  relations: Record<string, GenericRelation>;
  /** Relationship table suffix */
  relationshipsSuffix?: string;
  /** Initialization resolution handler */
  resolveInitializing: () => void;
  /** Complete database schema */
  schema: Record<string, GenericRelation | GenericTable>;
  /** Schema name */
  schemaName?: string;
  /** Table name mappings */
  tableNameMap: Map<string, string>;
  /** Database tables */
  tables: Record<string, GenericTable>;
  /** SQLite transaction configuration */
  transactionOptions: SQLiteTransactionConfig;
  /** Version table suffix */
  versionsSuffix?: string;
}

type SQLiteSchemaHook = (args: {
  extendTable: typeof extendDrizzleTable;
  schema: {
    relations: Record<string, GenericRelation>;
    tables: Record<string, SQLiteTableWithColumns<any>>;
  };
}) => Promise<SQLiteSchema> | SQLiteSchema;

type IDType = 'integer' | 'numeric' | 'text';

type GenericTable = SQLiteTableWithColumns<{
  columns: GenericColumns;
  dialect: string;
  name: string;
  schema: string;
}>;

type GenericColumns = {
  [x: string]: AnySQLiteColumn;
};

type GenericRelation = Relations<string, Record<string, Relation<string>>>;