Harper Schema GRAPHQL

Harper schema.graphql

Overview

Harper defines its database tables and types from GraphQL schema files, loaded by the graphqlSchema extension (default *.graphql; this project uses harper-app/schema.graphql). The schema is the source of truth for the data model: the tables it declares are what resources extend ([[harper-resources]]) and what the REST/GraphQL surface exposes.

Defining tables

A table is a GraphQL type. Harper-specific directives mark a type as a persisted table and control exposure, primary keys, indexes, audit timestamps, sealed records, and relationships. Lisa's Harper Fabric template pins harperdb to the Harper 4 line (^4.7.29), so use this v4 directive reference for template projects:

type Dog @table @export(name: "dogs") {
  id: Long @primaryKey
  name: String @indexed
  breed: String
  ownerId: Long @indexed
  owner: Owner @relationship(from: ownerId)
  createdAt: Long @createdTime
  updatedAt: Long @updatedTime
}

Use v5 docs only when the downstream project has intentionally moved off the Lisa template's Harper 4 dependency; do not mix v5-only syntax into a harperdb ^4.7.29 project.

How the schema drives the app

• The graphqlSchema extension creates/migrates tables from the schema on load.
• rest: true exposes exported tables/resources as REST endpoints; the GraphQL surface is generated from the same schema.
• Resources that extends tables.X depend on X existing in the schema. A rename or removal in the schema is a breaking change for every resource and verify path that references it.

Schema evolution

Schema changes are deploy-time data-model changes, not just type edits. Harper's graphqlSchema extension ensures declared tables and attributes exist when the component loads, but it does not perform semantic data migrations such as renaming tables, copying field values, or rewriting existing rows for you.

Classify each change before editing:

Migration recipe for production data:

1. Add the new schema shape in a backward-compatible way: new table or nullable replacement field, keeping the old field/table available.
2. Write a one-shot migration using a Harper resource method or Operations API/script that reads old rows, transforms values, and writes the new shape. Make it idempotent; reruns should skip rows already migrated or compare a migration marker.
3. Deploy to one Fabric environment and run the migration before switching readers/writers. For replicated Fabric deployments, assume every node may see the new code/schema at slightly different times; keep old and new reads compatible until replication and smoke checks are green.
4. Update resources, REST/GraphQL queries, data-loader seeds, and verify scripts in the same PR. A schema PR is incomplete if bun run verify or the project smoke path cannot prove the migrated read/write behavior.
5. Roll back by reverting code/schema only when the old field/table remains intact. Once cleanup drops old data or callers, rollback needs a reverse migration and a restored compatibility path.

Project conventions

• schema.graphql is source and lives at the component root that Fabric packages (harper-app/schema.graphql). Keep it there.
• A schema change is a data-model change. In the same change:
  • Update the conceptual schema docs.
  • Update any verify/smoke paths that assert joins, relationships, or row counts — those assertions encode the data model and must track it.
  • Update resources and seed/data-loader paths that reference changed tables.
• Document deploy-affecting consequences (new tables, migrations) in the Fabric runbook. See [[harper-build-and-deploy]].

Verification

After a schema change, boot the app (harper dev harper-app or the project run command) and confirm tables migrate cleanly and the dependent endpoints respond. Run any verify path that asserts row counts or joins against the changed model.

Sources

• Harper v4 Schema
• Components overview
• Operations API