harper-schema-graphql

name

harper-schema-graphql

description

This skill should be used when editing a Harper (HarperDB/Fabric) schema.graphql — defining or changing database tables, types, fields, relationships, or indexes that the graphqlSchema extension turns into Harper tables and API surface. Use it when adding a table, changing the data model, or when a resource/verify path depends on schema shape. Pairs with harper-resources, harper-config-yaml, and harper-component-model.

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
}

Directive	Scope	Syntax	Use
@table	Type	type Product @table { ... }	Creates a persisted table named after the type. Optional arguments: table: "products" to override the table name, database: "commerce" to choose a database, expiration: 3600 for TTL-style records, and audit: true to force audit logging.
@export	Type	type Product @table @export(name: "products") { ... }	Exposes the table as a resource endpoint for REST/MQTT and related surfaces. name is optional; without it the type name is the path segment.
@sealed	Type	type Product @table @sealed { ... }	Rejects undeclared properties. Omit it when the table intentionally accepts extra record fields.
@primaryKey	Field	id: Long @primaryKey	Marks the unique table key. If omitted on insert, Harper v4 can auto-generate a UUID for String/ID keys or an auto-incrementing integer for Int/Long/Any keys. Prefer Long or Any for generated numeric keys.
@indexed	Field	sku: String @indexed	Adds a secondary index used by REST filters, SQL, and NoSQL/search paths. Array fields index each element. For vectors in Harper v4.6+, use embedding: [Float] @indexed(type: "HNSW").
@createdTime	Field	createdAt: Long @createdTime	Writes Unix epoch milliseconds when the record is created.
@updatedTime	Field	updatedAt: Long @updatedTime	Writes Unix epoch milliseconds whenever the record is updated.
@relationship(from: field)	Field	owner: Owner @relationship(from: ownerId)

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:

Change	Compatibility	What Harper does	Required agent work
Add optional field	Usually safe	Adds the declared attribute shape; existing rows read as missing/null until written.	Update resources, seeds, and verification that should include the field.
Add required/non-null field	Breaking for existing rows and writers	The schema can declare the field, but existing records do not magically gain valid values.	Backfill first or deploy as optional, populate, then tighten in a later deploy.
Add @indexed	Usually safe, operationally sensitive	Creates/uses a secondary index for the attribute. Large tables may pay rebuild cost.	Verify filtered REST/search paths and note index build risk in the deploy runbook.
Add @sealed	Breaking when rows or writers use extra properties	Future writes with undeclared properties are rejected.	Audit current data/writers, declare needed fields, or migrate callers before sealing.
Rename field	Breaking	Treated as a new field; the old field and its values are not transformed.	Add the new field, copy values with a migration, update code, verify, then remove old usage.
Rename type/table	Breaking	Harper v4 does not rename tables; changing the type name creates a new empty table and leaves the old table/data untouched.	Create the new table, copy data, update resources/routes, verify both read/write paths, then retire the old table intentionally.
Change field type	Breaking	Existing stored values are not coerced into the new type in a controlled migration.	Add a replacement field/table, transform data with code, verify, then remove old usage.
Remove field/type	Breaking	Schema no longer declares it, but dependent resources, routes, queries, seeds, and clients can still reference it.	Delete references first, run a migration/cleanup if needed, and verify old API paths fail or redirect intentionally.

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