@capawesome/capacitor-sqlite-drizzle

Drizzle ORM adapter for @capawesome-team/capacitor-sqlite.

[!WARNING] This package is in early development and may have breaking changes. Feedback and contributions are welcome!

Installation

npm install @capawesome/capacitor-sqlite-drizzle drizzle-orm@^0.45.0

Usage

Setup

import { Sqlite } from '@capawesome-team/capacitor-sqlite';
import { drizzle } from '@capawesome/capacitor-sqlite-drizzle';

const { databaseId } = await Sqlite.open({ path: 'my.db' });
const db = drizzle(Sqlite, { databaseId });

You can pass any Drizzle configuration options alongside databaseId:

import * as schema from './schema';

const db = drizzle(Sqlite, { databaseId, schema, logger: true });

Define a Schema

Create a schema.ts file using Drizzle's schema builder:

import { integer, sqliteTable, text } from 'drizzle-orm/sqlite-core';

export const users = sqliteTable('users', {
  id: integer('id').primaryKey({ autoIncrement: true }),
  name: text('name').notNull(),
  email: text('email').notNull().unique(),
  createdAt: integer('created_at', { mode: 'timestamp' })
    .notNull()
    .$defaultFn(() => new Date()),
});

export const posts = sqliteTable('posts', {
  id: integer('id').primaryKey({ autoIncrement: true }),
  title: text('title').notNull(),
  content: text('content'),
  authorId: integer('author_id')
    .notNull()
    .references(() => users.id),
});

Queries

import { eq } from 'drizzle-orm';
import { users, posts } from './schema';

// Insert
await db.insert(users).values({ name: 'Alice', email: '[email protected]' });

// Select all
const allUsers = await db.select().from(users);

// Select with filter
const user = await db.select().from(users).where(eq(users.email, '[email protected]'));

// Update
await db.update(users).set({ name: 'Bob' }).where(eq(users.id, 1));

// Delete
await db.delete(users).where(eq(users.id, 1));

Relational Queries

When passing a schema to drizzle(), you can use Drizzle's relational query API:

const usersWithPosts = await db.query.users.findMany({
  with: { posts: true },
});

Transactions

Drizzle sends BEGIN, COMMIT, and ROLLBACK statements automatically:

await db.transaction(async (tx) => {
  await tx.insert(users).values({ name: 'Alice', email: '[email protected]' });
  await tx.insert(posts).values({ title: 'Hello', content: 'World', authorId: 1 });
});

Migrations

The migrate helper accepts the bundled migrations format generated by drizzle-kit.

1. Configure drizzle-kit

Create a drizzle.config.ts in your project root:

import { defineConfig } from 'drizzle-kit';

export default defineConfig({
  schema: './src/schema.ts',
  out: './src/drizzle',
  dialect: 'sqlite',
  driver: 'expo',
});

Note: driver: 'expo' is required to generate the bundled migrations.js file that works in non-Node environments like Capacitor.

2. Generate migrations

npx drizzle-kit generate

This creates SQL files and a migrations.js bundle in ./src/drizzle/.

Note: .sql files are imported as strings by migrations.js. You may need babel-plugin-inline-import or a Vite plugin like vite-plugin-plain-text to handle .sql imports in your bundler.

3. Apply migrations

import { Sqlite } from '@capawesome-team/capacitor-sqlite';
import { drizzle, migrate } from '@capawesome/capacitor-sqlite-drizzle';
import migrations from './drizzle/migrations';

const { databaseId } = await Sqlite.open({ path: 'my.db' });
const db = drizzle(Sqlite, { databaseId });

await migrate(Sqlite, databaseId, migrations);

Each migration runs inside a transaction. The __drizzle_migrations table is created automatically to track applied migrations.

API

drizzle(client, config)

Creates a Drizzle ORM database instance.

| Param | Type | Description | | -------- | ------------------------- | -------------------------------------------------------------------------------------------------------- | | client | SqlitePlugin | The Capacitor SQLite plugin instance (e.g. Sqlite). | | config | CapawesomeDrizzleConfig | Configuration object. Must include databaseId. Supports all Drizzle options (e.g. schema, logger). |

Returns: SqliteRemoteDatabase<TSchema>

migrate(client, databaseId, migrations)

Applies pending migrations.

| Param | Type | Description | | ------------ | -------------- | ------------------------------------------------------------------------------------ | | client | SqlitePlugin | The Capacitor SQLite plugin instance. | | databaseId | string | The database identifier returned by Sqlite.open(). | | migrations | Migrations | Bundled migrations object generated by drizzle-kit generate with driver: 'expo'. |

Interfaces

CapawesomeDrizzleConfig

Extends Drizzle's DrizzleConfig with:

| Property | Type | Description | | ------------ | -------- | ---------------------------------------------------- | | databaseId | string | The database identifier returned by Sqlite.open(). |

Migrations

The bundled migrations format generated by drizzle-kit generate with driver: 'expo'.

| Property | Type | Description | | ------------ | ------------------------ | ------------------------------------------------------------- | | journal | { entries: Entry[] } | Migration journal with ordered entries. | | migrations | Record<string, string> | Map of migration keys (m0000, m0001, ...) to SQL strings. |