How viaduct-dev/pg-persistence works
PG Persistence spans build-time schema modeling and SQL generation, plus a runtime library that delegates Viaduct resolver reads and writes to PostgreSQL’s pg_graphql API. The primary path is schema and persistence policy → validated persistence model → Hibernate effective model → migration and pg_graphql metadata artifacts; at runtime, resolver selections flow through DbClient to pg_graphql and results are hydrated into Viaduct types. The runtime entry point and key model transformations are evidenced by the README and sampled source references; finer Gradle-task and renderer wiring is not fully shown.
Main entry points: DbClient.kt DbClient · EffectiveHibernateModelBuilder.kt Effective model · DbFetcher.kt Fetch and batch · model Schema and policy
Components 23
Build-time modeling
- Schema and policy
plugin/src/main/kotlin/dev/viaduct/persistence/model - Persistence model
plugin/src/main/kotlin/dev/viaduct/persistence/model/PersistenceModel.kt - Hibernate metadata
plugin/src/main/kotlin/dev/viaduct/persistence/hibernate/HibernateMetadataBootstrap.kt - Effective model
plugin/src/main/kotlin/dev/viaduct/persistence/hibernate/EffectiveHibernateModelBuilder.kt - Gradle integration
plugin/src/main/kotlin/dev/viaduct/persistence/gradle/ViaductPgPersistencePlugin.kt
Schema and migrations
- Migration plan
plugin/src/main/kotlin/dev/viaduct/persistence/postgresql/EffectiveModelToMigrationPlanMapper.kt - PostgreSQL SQL
plugin/src/main/kotlin/dev/viaduct/persistence/postgresql/PostgresqlMigrationRenderer.kt - pg_graphql overlay
plugin/src/main/kotlin/dev/viaduct/persistence/pggraphql/overlay/PgGraphqlOverlay.kt - Constraint comments
plugin/src/main/kotlin/dev/viaduct/persistence/pggraphql/overlay/PgGraphqlConstraintRenderer.kt - Schema diff
plugin/src/main/kotlin/dev/viaduct/persistence/liquibase/ViaductHibernateDatabase.kt
Runtime data access
- DbClient
runtime/src/main/kotlin/dev/viaduct/persistence/runtime/db/DbClient.kt - Query planner
runtime/src/main/kotlin/dev/viaduct/persistence/runtime/db/DbQueryPlanner.kt - Fetch and batch
runtime/src/main/kotlin/dev/viaduct/persistence/runtime/db/DbFetcher.kt - Mutation client
runtime/src/main/kotlin/dev/viaduct/persistence/runtime/db/PgGraphqlMutationClient.kt - GraphQL transport
runtime/src/main/kotlin/dev/viaduct/persistence/runtime/graphql/GraphqlTransport.kt
Runtime mapping
- Connection pagination
runtime/src/main/kotlin/dev/viaduct/persistence/runtime/connection/ConnectionQueryPlanner.kt - Node references
runtime/src/main/kotlin/dev/viaduct/persistence/runtime/node/NodeReferenceHydrator.kt - Generated-type reflection
runtime/src/main/kotlin/dev/viaduct/persistence/runtime/reflection/GeneratedTypeReflection.kt - Result mapping
runtime/src/main/kotlin/dev/viaduct/persistence/runtime/db/DbResponseReader.kt
Other components
- Application developer
- Viaduct resolvers
- pg_graphql API
- PostgreSQL tables
Connections 26
- Application developer → Schema and policy: defines
README.md - Gradle integration → Schema and policy: loads
- Schema and policy → Persistence model: builds
- Persistence model → Hibernate metadata: configures
- Hibernate metadata → Effective model: projects
plugin/src/main/kotlin/dev/viaduct/persistence/liquibase/ViaductHibernateDatabase.kt - Gradle integration → Effective model: generates
- Effective model → Migration plan: maps
plugin/src/main/kotlin/dev/viaduct/persistence/postgresql/EffectiveModelToMigrationPlanMapper.kt - Migration plan → PostgreSQL SQL: renders
- Effective model → pg_graphql overlay: renders metadata
- Effective model → Constraint comments: names constraints
plugin/src/main/kotlin/dev/viaduct/persistence/pggraphql/overlay/PgGraphqlConstraintRenderer.kt - Effective model → Schema diff: diffs against
plugin/src/main/kotlin/dev/viaduct/persistence/liquibase/ViaductHibernateDatabase.kt - Viaduct resolvers → DbClient: delegates
README.md - DbClient → Query planner: plans reads
runtime/src/main/kotlin/dev/viaduct/persistence/runtime/db/DbClient.kt - DbClient → Fetch and batch: fetches
runtime/src/main/kotlin/dev/viaduct/persistence/runtime/db/DbClient.kt - DbClient → Mutation client: delegates writes
runtime/src/main/kotlin/dev/viaduct/persistence/runtime/db/DbClient.kt - Query planner → Generated-type reflection: uses
runtime/src/main/kotlin/dev/viaduct/persistence/runtime/db/DbQueryPlanner.kt - Fetch and batch → GraphQL transport: sends queries
- Mutation client → GraphQL transport: executes
runtime/src/main/kotlin/dev/viaduct/persistence/runtime/db/PgGraphqlMutationClient.kt - GraphQL transport → pg_graphql API: sends GraphQL
README.md - pg_graphql API → PostgreSQL tables: queries tables
README.md - DbClient → Connection pagination: fetches pages
runtime/src/main/kotlin/dev/viaduct/persistence/runtime/db/DbClient.kt - DbClient → Node references: hydrates references
runtime/src/main/kotlin/dev/viaduct/persistence/runtime/db/DbClient.kt - Node references → Generated-type reflection: uses
runtime/src/main/kotlin/dev/viaduct/persistence/runtime/node/NodeReferenceHydrator.kt - Connection pagination → Generated-type reflection: classifies shapes
runtime/src/main/kotlin/dev/viaduct/persistence/runtime/reflection/GeneratedTypeReflection.kt - Fetch and batch → Result mapping: decodes results
- Result mapping → Viaduct resolvers: returns Viaduct types
README.md