feat(gb-9097): derive/is introspection support

Author: pimeys

.github/workflows/pull-request.yml

@@ -55,8 +55,8 @@ jobs:
     strategy:
       matrix:
         version:
-          - gateway: "0.37.2"
-            cli: "0.94.1"
+          - gateway: "0.38.0"
+            cli: "0.95.1"
     env:
       RUSTFLAGS: -D warnings
     steps:

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "grafbase-postgres"
-version = "0.3.5"
+version = "0.3.6"
 edition = "2024"
 license = "Apache-2.0"
 

cli/postgres/Cargo.toml

@@ -171,6 +171,9 @@ enable_queries = true
 # you can define them manually from this map. Key/value from relation name
 # to config.
 relations = {}
+
+# Configure derives for cross-database joins.
+derives = {}
 ```
 
 ### View Configuration
@@ -201,6 +204,9 @@ columns = {}
 # can define relations manualy from this map.
 # Key/value from relation name to config.
 relations = {}
+
+# Configure derives for cross-database joins.
+derives = {}
 ```
 
 #### Unique Key Definitions
@@ -258,6 +264,173 @@ referenced_columns = ["id", "name"]
 
 Define these relations in your config file to enable joins to and from your views.
 
+### Derive Definitions
+
+Our derives setup offers a powerful way to join data efficiently between multiple Postgres databases. You can use several approaches to enable joins across two or more Postgres databases.
+
+The Grafbase Gateway prevents GraphQL N+1 problems in all cross-database joins by minimizing the number of queries needed to load data.
+
+Let's explore some examples using these SQL schemas:
+
+Database A:
+
+```sql
+CREATE TABLE "posts" (
+  id INT PRIMARY KEY,
+  title VARCHAR(255) NOT NULL,
+  author_id INT NOT NULL
+);
+```
+
+Database B:
+
+```sql
+CREATE TABLE "users" (
+  id INT PRIMARY KEY,
+  name VARCHAR(255) NOT NULL
+)
+```
+
+We want to create a federated GraphQL schema that joins posts and users:
+
+```graphql
+type Post @key(fields: "id") {
+  id: Int!
+  title: String!
+  authorId: Int!
+  author: User
+}
+
+type User @key(fields: "id") {
+  id: Int!
+  name: String!
+}
+```
+
+#### Entity Joins
+
+The first approach uses GraphQL federation spec entity joins. This method requires both subgraph schemas to define the same type. Database A needs a view that represents unique users, which we create with:
+
+```sql
+CREATE VIEW "users" AS SELECT DISTINCT(author_id) AS id FROM posts ORDER BY author_id;
+```
+
+Add this configuration for the grafbase-postgres CLI extension before introspection:
+
+```toml
+[schemas.public.views.users.columns.id]
+nullable = false
+unique = true
+```
+
+This gives subgraph A the following types:
+
+```graphql
+type Post @key(fields: "id") {
+  id: Int!
+  title: String!
+  authorId: Int!
+  author: User!
+}
+
+type User @key(fields: "id") {
+  id: Int!
+}
+```
+
+When you compose this with subgraph B, you can efficiently join posts and users.
+
+#### Deriving
+
+Creating an extra view to join data between databases often adds maintenance overhead and can slow down performance. Instead, use the composite spec `@is` and `@derive` directives. Define derives for subgraph A:
+
+```toml
+[schemas.public.tables.posts.derives.author]
+referenced_type = "User"
+fields = { id = "authorId" }
+```
+
+This tells the system: for the `posts` table, create a derived field `author` that loads a single `User` entity. The `id` field of the User type maps to the `authorId` field of the `Post` type.
+
+Introspection then produces these types:
+
+```graphql
+type Post @key(fields: "id") {
+  id: Int!
+  title: String!
+  authorId: Int!
+  author: User! @derive @is(field: "{ id: authorId }")
+}
+
+type User @key(fields: "id") {
+  id: Int!
+}
+```
+
+The introspection creates a User type with fields needed for joining and a derived relation field with the corresponding directives. Compose this with the other subgraph to create a federated graph that joins posts to users across databases.
+
+#### One to Many
+
+We're currently working on support for one-to-many joins with deriving. For now, use the entity join approach if you need to fetch many entities from another graph.
+
+Add a view to the database with the posts table:
+
+```sql
+CREATE VIEW "users" AS SELECT DISTINCT(author_id) AS id FROM posts ORDER BY author_id;
+```
+
+Then add this configuration to create a relation between the users view and posts table:
+
+```toml
+[schemas.public.views.users.relations.users_to_posts]
+referenced_schema = "public"
+referenced_table = "posts"
+referencing_columns = ["id"]
+referenced_columns = ["author_id"]
+```
+
+Introspection produces this SDL:
+
+```graphql
+type Post @key(fields: "id") {
+  id: Int!
+  title: String!
+  authorId: Int!
+  author: User!
+}
+
+type User @key(fields: "id") {
+  id: Int!
+  posts: [Post!]!
+}
+```
+
+When you compose this with the other subgraph:
+
+```graphql
+type User @key(fields: "id") {
+  id: Int!
+  name: String!
+}
+```
+
+You get this federated graph:
+
+```graphql
+type Post @key(fields: "id") {
+  id: Int!
+  title: String!
+  authorId: Int!
+  author: User!
+}
+
+type User @key(fields: "id") {
+  id: Int!
+  name: String!
+  posts: [Post!]!
+}
+```
+
 ## License
 
 Apache-2.0

cli/postgres/README.md

@@ -6,7 +6,7 @@ if [[ ${OS:-} = Windows_NT ]]; then
     exit 1
 fi
 
-LATEST_VERSION="0.3.5"
+LATEST_VERSION="0.3.6"
 
 # Reset
 Color_Off=''

cli/postgres/grafbase-postgres.toml

@@ -421,6 +421,13 @@ impl DatabaseDefinition {
             .map(|id| self.walk(id))
     }
 
+    /// Retrieves a table walker for the given schema and table name.
+    pub fn get_table(&self, schema: &str, table_name: &str) -> Option<TableWalker<'_>> {
+        self.get_schema_id(schema)
+            .and_then(|schema_id| self.get_table_id(schema_id, table_name))
+            .map(|table_id| self.walk(table_id))
+    }
+
     /// Finds the id of a schema with the given name, if existing.
     pub fn get_schema_id(&self, schema: &str) -> Option<SchemaId> {
         self.schemas

cli/postgres/install.sh

@@ -23,6 +23,7 @@ itertools.workspace = true
 Inflector.workspace = true
 indenter = { version = "0.3.3", features = ["std"] }
 serde = { workspace = true, features = ["derive"] }
+indexmap.workspace = true
 
 [lints]
 workspace = true

crates/database-definition/src/lib.rs

@@ -1,4 +1,5 @@
 use grafbase_database_definition::TableWalker;
+use indexmap::IndexMap;
 use serde::Deserialize;
 use std::collections::BTreeMap;
 
@@ -121,6 +122,9 @@ pub struct TableConfig {
     /// Configuration details for relationships originating from this view, keyed by relationship name.
     #[serde(default)]
     pub relations: BTreeMap<String, RelationConfig>,
+    /// Configuration for derived fields in this table, keyed by derive name.
+    #[serde(default)]
+    pub derives: BTreeMap<String, DeriveConfig>,
 }
 
 /// Represents the configuration settings for a specific database relation (e.g., a view).
@@ -139,6 +143,78 @@ pub struct ViewConfig {
     /// Configuration details for relationships originating from this view, keyed by relationship name.
     #[serde(default)]
     pub relations: BTreeMap<String, RelationConfig>,
+    /// Configuration for derived fields in this table, keyed by derive name.
+    #[serde(default)]
+    pub derives: BTreeMap<String, DeriveConfig>,
+}
+
+/// Represents the configuration for a derived field within a table or view.
+///
+/// A derived field allows you to enable joins between subgraphs. By defining a derived field in
+/// this database, the introspection generates a virtual type, which then composes with the full
+/// federated schema.
+///
+/// For example:
+///
+/// ```toml
+/// # In your config.toml file:
+///
+/// [schemas.public.tables.Post.derives.author]
+/// referenced_type = "User"
+/// field = { author_id = "id" }
+/// ```
+///
+/// This then is reflected in the generated schema as follows:
+///
+/// ```graphql
+/// type Post @key(fields: "id") {
+///   id: ID!
+///   title: String!
+///   email: String!
+///   # introspection will create this field
+///   author: User! @derive @is(field: "{ author_id: id }")
+/// }
+///
+/// """
+/// Introspection will create this type.
+/// """
+/// type User @key(fields: "id") {
+///   id: ID!
+/// }
+/// ```
+///
+/// Keep in mind that you do not need to define derives for types that are already defined in the
+/// schema. The introspection process will detect the relationship between the types through
+/// foreign keys. Also, if you have the same type in two different databases, automatically utilize the
+/// Apollo federation keys to implement an entity join:
+///
+/// Subgraph A:
+///
+/// ```
+/// type User @key(fields: "id") {
+///   id: ID!
+///   name: String!
+/// }
+/// ```
+///
+/// Subgraph B:
+///
+/// ```
+/// type User @key(fields: "id") {
+///   id: ID!
+///   socialSecurityNumber: String!
+/// }
+/// ```
+///
+/// The composition will combine these User types into a single User type without extra
+/// configuration.
+#[derive(Deserialize, Debug)]
+#[serde(deny_unknown_fields)]
+pub struct DeriveConfig {
+    /// The type the derived field points to.
+    pub referenced_type: String,
+    /// A map of referencing field to referenced field.
+    pub fields: IndexMap<String, String>,
 }
 
 /// Represents the configuration for a specific column within a view.

crates/postgres-introspection/Cargo.toml

@@ -32,7 +32,7 @@ pub async fn introspect(conn: &mut sqlx::PgConnection, config: Config) -> anyhow
 
     database_definition.finalize();
 
-    Ok(render::to_sdl(database_definition, &config))
+    render::to_sdl(database_definition, &config)
 }
 
 /// A list of schemas to filter out automatically on every introspection.