Making Postgres and GraphQL a breeze 🌬️
Step 1: Specify the views that will be used by your models using plain SQL
-- views/Person.sql
SELECT
id,
full_name
FROM personHere we're using a single table, but views can be queries of arbitrary complexity, including joins, subqueries, etc.
Step 2: Generate the views from the SQL files using the CLI
graphql-zephyr views/*.sql generated/views.tsThis creates a TypeScript file for you like this:
export const views = {
Person: {
name: "Person",
query: `
SELECT
id,
full_name
FROM person;
`,
columns: {
id: {
kind: "integer",
} as const,
full_name: {
kind: "text",
} as const,
},
type: {} as { id: number; full_name: string },
},
// and more...
};Step 3: Create your models
// Person.ts
import { createModel } from "graphql-zephyr";
import { views } from "../views";
export const Person = createModel({
name: "Person",
view: views.Person,
fields: ({ field }) => {
return {
// Fields can map directly to a view column
id: field({
column: "id",
}),
// Or multiple columns
fullName: field({
// Note: this is an arbitrary example. In practice, you'd just return "fullName" as a column on your view.
columns: ["first_name", "last_name"],
// The resolver here is correctly typed based on the generated view
resolve: ({ first_name, last_name }) => `${first_name} ${last_name}`,
// For regular columns, the types are implied from the view columns, but here we have to specify our own
type: "String!",
}),
];
},
});Relationships are defined separately from models to avoid issues with circular dependencies.
// PersonRelationships.ts
import { createRelationships } from "graphql-zephyr";
import { Person } from "./Person";
import { Post } from "./Post";
export const PersonRelationships = createRelationships(({ oneToMany }) => [
oneToMany({
name: "posts",
models: [Person, Post],
// How the two models will be joined by the query builder. Each parameter here is typed based on the model's associated view columns
join: (person, post) => sql`${person.id} = ${post.person_id}`,
}),
]);Step 4: Use your models to generate components for a base GraphQL schema
import { createSchemaComponents } from "graphql-zephyr";
import { Person } from "./Person";
import { PersonRelationships } from "./PersonRelationships";
import { Post } from "./Post";
const {
typeDefs,
resolvers,
schema,
createQueryBuilder,
} = await createSchemaComponents({
models: { Person, Post },
relationships: [...PersonRelationships],
});This generates base type definitions and resolvers that you can build on top of when creating your schema.
type PageInfo {
endCursor: String!
hasNextPage: Boolean!
hasPreviousPage: Boolean!
startCursor: String!
}
type PersonPostsConnection {
edges: [PersonPostsEdge!]!
pageInfo: PageInfo!
}
type PersonPostsEdge {
cursor: String!
node: Post!
}
type Person {
id: Int!
fullName: String!
posts(
after: String
before: String
first: Int
last: Int
): PersonPostsConnection!
}
type PostLikedByConnection {
edges: [PostLikedByEdge!]!
pageInfo: PageInfo!
}
type PostLikedByEdge {
cursor: String!
node: Person!
}
type Post {
id: Int!
body: String!
likedBy(
after: String
before: String
first: Int
last: Int
): PostLikedByConnection!
}Note: In addition to typeDefs and resolvers,
createSchemaComponentsalso returns a schema object. While this schema cannot be used on its own (it has no root types), it can be used with tools like GraphQL Code Generator and the GraphQL VS Code extension as shown here.
Step 5: Use the query builder inside your schema to generate complete SQL queries right from the root of your schema.
import { createPool } from "slonik";
const pool = createPool("postgres://");
const queryBuilder = createQueryBuilder(pool);Then in your resolver:
function resolve(parent, args, ctx, info) {
return ctx.queryBuilder.models.Person.getRelayConnection({
info,
where: (person) => sql`${person.full_name} ilike 'c%'`,
orderBy: (person) => [[person.id, "DESC"]],
});
}The query builder will inspect your request using the info parameter and build a single database query based on it.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent