Overview

Some Fragno Fragments include a built-in database layer for persistent storage. When integrating these Fragments, you need to provide a database adapter that connects the Fragment to your existing database.

Fragment Handles Schema

The Fragment defines its own schema and handles migrations. You just provide the database connection - no need to manually create tables or write SQL.

Identifying Database Fragments

A Fragment uses the database layer if its documentation mentions FragnoPublicConfigWithDatabase or requires a databaseAdapter option.

Check the Fragment's creation function:

// Fragment without database
createExampleFragment(config, options);

// Fragment with database - requires databaseAdapter
createCommentFragment(config, { databaseAdapter });

Quick Start

Installation

npm install @fragno-dev/db

And install the CLI to perform migrations / schema generation:

npm install --save-dev @fragno-dev/cli

Choose Your Adapter

Fragno supports two popular TypeScript ORMs:

Kysely - Type-safe SQL query builder
Drizzle - Modern TypeScript ORM

Choose the adapter that matches your existing database setup. If you're starting fresh, either works great.

Prisma Support

We might support Prisma in the future. Follow this issue to get updates, and let us know if you'd like to see it supported.

Create Database Adapter

See the adapter-specific pages for detailed setup:

It will look something like this:

lib/database-adapter.ts

import { DrizzleAdapter } from "@fragno-dev/db/adapters/drizzle";
import { db } from "./database"; // Your existing Drizzle instance

export const fragmentDbAdapter = new DrizzleAdapter({
  db,
  provider: "postgresql", // or "mysql", "sqlite"
});

Pass Adapter to Fragment

lib/comment-fragment-server.ts

import { createCommentFragment } from "@fragno-dev/comment-fragment";
import { fragmentDbAdapter } from "./database-adapter";

export function createCommentFragmentInstance() {
  return createCommentFragment(
    {
      // Fragment-specific config
    },
    {
      databaseAdapter: fragmentDbAdapter,
    },
  );
}

// IMPORTANT: Export the Fragment so it's accessible by the Fragno CLI.
export const fragment = createCommentFragmentInstance();

Migrate your Database

Generate and apply database migrations:

# Generate migration (or schema) file
npx fragno-cli db generate lib/comment-fragment-server.ts

# Or apply migrations directly
npx fragno-cli db migrate lib/comment-fragment-server.ts

For details on the CLI commands, see the CLI Reference.

Supported Databases

Both Kysely and Drizzle adapters support:

PostgreSQL
MySQL
SQLite

The adapter automatically handles database-specific SQL generation.

FAQ

Q: Do I need to learn a new ORM?

A: No. You continue using your existing Kysely or Drizzle setup. The Fragment just adds its tables to your database.

Q: Can I query Fragment tables directly?

A: Yes, but there are some caveats. In general we recommend using the Fragment's service methods instead. You can query the Fragment's tables directly, but you have to be aware of the fact that the Fragment author may change the schema in the future.

Q: What if I don't use Kysely or Drizzle?

A: Currently, only Kysely and Drizzle adapters are available. Support for other ORMs may be added in the future. Please let us know on GitHub if you'd like to see support for other ORMs.

Q: Can I use multiple database Fragments?

A: Yes! Each Fragment manages its own namespaced tables. You can use the same adapter for all Fragments:

const comments = createCommentFragment({}, { databaseAdapter });
const ratings = createRatingFragment({}, { databaseAdapter });

Next Steps

Choose your database adapter to continue:

On this page