Overview

Some Fragno Fragments include a built-in database layer for persistent storage. When integrating these Fragments, you typically provide a database adapter that connects the Fragment to your existing database. If better-sqlite3 is installed, Fragno can default to a local SQLite file per fragment under FRAGNO_DATA_DIR (default: ~/.fragno).

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 - may require databaseAdapter
createCommentFragment(config, { databaseAdapter });

Quick Start

npm install @fragno-dev/db

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

import { SqlAdapter } from "@fragno-dev/db/adapters/sql";
import { PostgresDialect } from "@fragno-dev/db/dialects";
import { NodePostgresDriverConfig } from "@fragno-dev/db/drivers";
import { Pool } from "pg";

const dialect = new PostgresDialect({
  pool: new Pool({ connectionString: process.env.DATABASE_URL }),
});

export const fragmentDbAdapter = new SqlAdapter({
  dialect,
  driverConfig: new NodePostgresDriverConfig(),
});

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();

# Generate SQL migrations
npx fragno-cli db generate lib/comment-fragment-server.ts

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

# Drizzle schema output
npx fragno-cli db generate lib/comment-fragment-server.ts --format drizzle -o schema/fragno-schema.ts

# Prisma schema output
npx fragno-cli db generate lib/comment-fragment-server.ts --format prisma -o prisma/schema/fragno.prisma

Supported Databases

The SqlAdapter supports:

• 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, Drizzle, or Prisma 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, Drizzle, or Prisma?

A: Fragno uses Kysely dialects under the hood and currently supports SQL migrations plus Drizzle or Prisma schema outputs. Support for other workflows may be added in the future. Please let us know on GitHub if you'd like to see additional formats.

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 workflow to continue:

• Database Adapter
• CLI Reference for migration commands