Learn how to generate instant GraphQL APIs using a data source connector (GraphQL and non-GraphQL sources), extend and join them both with custom resolvers and deploy to the edge without leaving the code editor.
Build and Deploy Instant GraphQL APIs to the Edge
AI Generated Video Summary
In this Workshop, we explore GraphBase and GraphQL, focusing on using Neon as a connector and Postgres as a database. We learn how to set up Neon and the Postgres connector, automatically generate a GraphQL schema, and create a GraphQL API with Neon. We also delve into edge caching, extending GraphQL APIs, and integrating with MongoDB, Contentful, and other data services. Additionally, we cover adding API rules and security with Click as the auth provider.
1. Introduction to Graphbase and GraphQL
In this part, we will explore Graphbase and GraphQL. We'll discuss the challenges of using multiple tools and services in the ecosystem and how GraphQL can provide a unified API. We'll also address the issue of data latency and introduce GraphQL edge caching. Additionally, we'll focus on using a Postgres database with NEON as a connector and demonstrate how to deploy globally using CloudFlare workers.
Hey, everyone. Thanks very much for taking the time today to join me, and we're going to be spending some time today looking at Graphbase and GraphQL. This isn't a workshop people to GraphQL, but I'm more than happy to answer any questions that anyone has there. So, hey, Natasha and everyone else that's in the chat, great to have you all. And please, feel free to interrupt me at any point.
The style that I'm going to go for today actually is going to be me just showing you a few things. And if you have access to GetNation portal, there is other workshops and videos on there from myself about this very topic. But I think today we can go through and show various parts. And I want to talk specifically about one way that you can build GraphQL APIs on top of a Postgres database with a new connector that we have. So that could be interesting. And we'll kind of take a tour of the product and what it enables developers to do. And hopefully, that's enough to, you know, inspire some questions and, you know, invite you to try it out.
I'm just going to flip through some slides to begin with, just to set the scene. And like I said, please ask any questions, should you have them. But I want to talk to you about GraphQL and how you can make your data fast. I'm Jamie. I've been doing GraphQL for about five close years now. I do have a website, GraphQLWTF, where I release weekly videos. That's currently on pause, but I will be resuming weekly videos on that at the moment. There's a huge back catalog if you're interested. You can follow me on Twitter, whatever it's called today. My handle is just Barton Backwards, which is no trab.
The biggest problem that I think we see today, or certainly the problem that I've experienced personally, is we have so many different tools in the ecosystem, and all of these tools allow us to do so many great things. Even my own website has tools for sending notifications via email, via Slack, pulling in content from a CMS, pulling in content from a digital asset management platform to get my images and videos, and certainly from my GraphQL website, content comes from a lot of different places. Which is great. I use these kind of best of breed services, as the industry calls them. But we often spend so much time figuring out how each of these APIs work. We spend so long reading each documentation or SDK reference to really figure out how everything works together, and by the end of it we've got a package json file that's got a dozen or if not multiple gigabytes worth of Node modules just to install SDKs and whatever, and that's okay. But I don't think it's the best experience, and I think GraphQL actually shines here because it allows us to interface with all of these different services as one API. And the other issue that I think we have is, all of these different services belong somewhere, the data is stored somewhere, and it's accessible. If I'm here in the UK and I'm wanting to access data that's on US East one or whatever, I have to make a request, get that data and the latency there can add up, right? And that latency is replicated for each individual service that I use, which isn't great either. Now, a lot of the different service providers that we use do allow you to replicate data or whatever, but you often have to pay a per provider a cost to replicate. So that's not great, you have all of these different costs associated with just one output because you've had to replicate content around the world. So that's not an amazing experience, at Graphbase, we are trying to resolve that by something that we call GraphQL edge caching. So we're able to put a layer in front of your data sources so when someone requests that, we cache that and response times go from looking something like this to the green line. Anything you request comes through a lot quicker. So how do we go about connecting stuff? Well, this is three ways that I want to show you and I'm not going to be focusing on these too much today, the postgres one is the one that about. We have three connectors here. MongoDB and an open API connector. The open API connector is pretty cool because that can take an open API specification and you can use that spec and the great thing about specs is they follow a specification so we're able to determine what fields are and end points are and what arguments they take because these specifications follow a spec and the schema follows a spec. So, we're able to automatically create a GraphQL API based off the open API spec, which is pretty cool. And because it's GraphQL, we can introspect that in the same way. We can introspect GraphQL APIs and we can generate something that you can use. MongoDB, on the other hand, here we have a way to define models and specify fields on those models and kind of add some strictness to our MongoDB, which is traditionally a document database. We can add some kind of rules and behaviors around how documents are stored and we generate all the APIs for that. But the one that I want to focus on today is using a Postgres database and we'll be using NEON, so please go to NEON dot tech and sign up and create your own database there if you want to follow along. But here we're able to kind of plug in NEON as a connector, add it to our schema as a data source, then we're able to add caching to that so when we make a request it fetches data from the cache and not from NEON. Then once we've got all of our connections and data sources lined up all we then need to do to deploy this to the edge globally around the world, over 200 points of presence, is run an npx craftbase deploy and that will deploy around the world which is pretty cool. Everything's built with Rust and it is then packaged up using WebAssembly and deployed into different, not lambdas, but CloudFlare workers that's deployed, like I say, around the world on the CloudFlare Edge network. Everything I'm going to show you and talk about today is open source, please check that out if you're interested.
2. GraphBase, Neon, and Postgres Adapter
Once we've deployed everything globally, we need to understand how to query it. Neon provides a dashboard and database that allows us to form GraphQL queries. We can create things with mutations and fetch things with queries, including pagination arguments. pathfinder.dev is a tool to run GraphQL queries. GraphBase aims to solve the problem of consuming data from different services by providing a unified GraphQL API. It also offers automatic deployment of API versions when changes are made to the database. Today, we will focus on Neon and the Postgres adapter. We'll explore the hosted version briefly, but most of our work will be done locally. GraphBase deploys GraphQL endpoints around the world, utilizing edge-caching and features like KVStorage to reduce latency. Each change to the schema is logged, and specific deployments can be accessed for different branches or features.
But once we've got everything kind of deployed around the world we then need to figure out how do we query this, what does that look like? Well, here we can see in the background is a screenshot of Neon. I'm going to dive into this in about two or three minutes time. And we're going to look at that dashboard and database and more tables and data we've got. But that database we're able to form GraphQL queries from. We can see on the screen here we've got a mutation to create things. Then we've got a query to fetch things. And we can see we've got some pagination arguments in here to fetch the first or last or whatever nodes we want from the database. And all of that is generated automatically, which is pretty cool. And yeah, lastly, pathfinder.dev is a way to run these GraphQL queries. This doesn't just work with Graphbase, but it works with any GraphQL API. It's a way to view and perform GraphQL requests similar to GraphiQL, if you've used that before. And that's what we have on the local experience and the deployed versions of Graphbase.
So I think that probably is a good transition to talk about Graphbase very, very quickly. Kind of give me the reasons why we created Graphbase and what we're looking to solve. But just as a high-level overview, GraphQL here, we've got a query to fetch a product by a slug. And the idea, the things that we can make really nice and intuitive for you as a developer is, you could have all of your different data sources, like I mentioned before, spread across different services. And if you want to create one query to fulfill this card requirement here, we can get the image, the title, the price, the variance, whatever, from all the different services that are managing that. So we've been told over the last few years it's important that we have different services to do their own individual things. But actually consuming all of that is actually a problem that we created because of that. And GraphQL is a really cool way to solve that. So, yeah, what GraphBase will do is, we will give you an API to call this GraphQL query. We will deploy that. Whenever you create a pull request on your work and you make any changes to your database, we'll deploy a different version of that as well, which is cool. Cool. So, yeah. Hello, and welcome to anyone that is just joining. It's great to have you all here. And like I said, please let me know if you've got any questions.
So, now we've set the scene. We've talked about the issues and problems that we have and why we create a GraphBase. For anyone just joining, we're looking to solve these two things here. Lots of different data sources with a different learning curve for every single tool that we use and the issue where all of this stuff is deployed around the world and it costs so much because we have to replicate that for each individual service. We think we can bring all of that under one GraphQL API. And today, I want to spend some time talking about Neon and the Postgres adapter that we've just created. So, Graphis, when you sign in, if you go there now and you get started in creating accounts, I'll sign into mine and show you around very briefly what the hosted version looks like. But everything we're going to do today is pretty much going to be something that we work on locally. So here, we've got a few different projects. If I just go to this project here, we can see here, this is our dashboard, we've got our GraphQL endpoints. And these are the endpoints we tell Netlify, Versaille, Fly, wherever you deploy this, this is my GraphQL endpoint. And that endpoint is distributed around the world, deployed to the edge, and has all of that kind of edge-caching stuff built alongside it. We've got things like KVStorage, which you can access all at the edge as well. The idea is to reduce that latency as much as much as we can. So this is a project that gets hammered quite a bit from some kind of tool that compares different edge deployments, but it's kind of good enough to show you around. So here we've got all the deployments that every single time you make a change to the schema, the schema is something I'll show you shortly, but every single change you make, you can go in and see, I added this, I removed this, I added this field, I added this connector. You can see exactly what went on and they build logs for that as well. And you can see exactly who did that. You've got access to the individual endpoints for that specific deployment as well. So if you create a branch to add a new feature or whatever, you get a specific deployment for that GraphQL API. And that's a pain that like setting that stuff up manually. If you're not using something like GraphBase, it's a bit of a pain.
3. Graph-Based Hosting Platform
In this part, we explore the graph-based hosting platform. We cover features like finders, analytics, and logs, which provide insights into the database or connected services. We also discuss the ease of viewing logs for requests and errors in production. This platform allows you to specify environment variables, manage API keys, and connect to repositories. It offers the option to redeploy and roll back changes if needed.
So we look to kind of build that to make it a much better experience. And as I mentioned before, in the slides are finders where you can kind of explore everything in the database or a service that you're using that's connected. And then analytics, we can see here what things are looking like for your service. We're just getting started on the analytics section, but there's kind of a pretty cool overview on how things are stacked up for you and what the data looks like. Logs as well, we've made it really easy to see exactly what's going on when you make requests and errors in production. We've just rolled this out recently where you can view all the logs and stuff that's going on. So that's about it. That's really all I wanted to show you about the graph-based kind of hosting platform. Honestly, this isn't something that you'll spend a huge amount of time in, but it's here that you'll specify your environment variables and API keys and you'll get repository that this is connected to as well. But yeah, for the most part, you will probably spend time in this screen here and you get your API keys and stuff from here, but yeah, if there's anything goes wrong and you kind of want to roll anything back, you know, there's the option to redeploy things as well. So we've got all of that amazing stuff built in.
4. Introduction to GraphBase and GraphBase SDK
Let's dive into GraphBase. Run the command 'npx GraphBase' to initialize a new project. Choose TypeScript for configuration. We'll be spending time in Neon and graph base. Is GraphBase a node module? Yes, it is. Use 'npx graphbase init' to invoke it. Create something from scratch using the graph-based SDK. Install the necessary dependencies.
But yeah, let's dive into the fun stuff. Like I mentioned before, I'm only using one screen today. I don't have my usual setup. So please bear with me as I jump around things. We'll get through it. But yeah, ask any questions if you've got them. Ask me anything about GraphQL. If you're new to GraphQL. I'd love to just get a feel from the audience on whether you're new or if you've used GraphQL before. Even if you've heard of GraphBase, I'd love to know that as well. So just let me know in the chat as well.
But if you can, if you want to follow along with this, you can go to neon.tech and you can sign up and create a database and then you can create some tables in your database. And then you can add some data if you want. I only have one table here called user and then I have some columns in here for name and email. And I've just added some dummy data in here for the purposes of this workshop.
Alrighty. So now let's dive into GraphBase. So let's imagine you have a front end application. Let's say it's Next.js. Let's say it's Vuel. Whatever you're using as a front end that you want to add a GraphQL back into, well, once you're inside of that, all you really need to do is run a command which is npx GraphBase. I'll use the latest version and we'll call this GraphBase react summit. This react summit is just going to create a folder for me where I can do some work. So I'll agree to install the latest version and this is going to initialize a new project. It's going to ask me once it's installed that how I want to configure my projects. I'm going to use TypeScript. You can opt to use GraphQL. So you can actually use GraphQL SDL to define your back end, but I'm going to use TypeScript because that is a little bit nicer to work with if you aren't familiar with SDL too much. So if I can type this, I'll open it on my code editor and we'll get going.
Yeah. I will share the resource links in the description. That's fine. No problem. Let's just start the first one, which is graphbase.com and then neon.tech. Those are the two things we're going to be spending a bunch of time with today and the documentation as well. So yeah, we'll be spending a bunch of time in Neon and sometime in graph base and we'll deploy all of that. I imagine you're using GitHub already, but we'll be using that as well. All right. So here is my new project. Is Graphbase a node module? It is a node module, but you can invoke it by using npx graphbase init and then you can do, I'll show you the commands as well. So if you've got node installed in your machine, that's probably the easiest way. I think it's available as a binary through homebrew and stuff as well, but honestly, the easiest way is just using that npx. Once you have run npx, you will get something that looks like this. And this is a configuration file. And what we're going to do today is, dilly diddle, we are going to create something from scratch. So I'm going to call import config from graph-based SDK. And when I ran initialize before, this just created a package.json that looks something like this. It's added this dependency, which is the graph-based SDK. You'll also need to install the dependencies, but we'll do that next. So now we've got this, let's run export default config.
5. Setting Up Neon and Postgres Connector
Pass the schema as a G using the builder pattern. Use a connector to add a new connection to a database. Sign up to Neon, create a database, and get a connection string. Choose the Postgres connector, give it a name of Neon, and set the neon url as an environment variable. Run mpx graph base dev to generate a GraphQL API.
And then I'm going to pass the schema as a G here. I'm using the builder pattern. So this builder generator G is something we can use to do various things.
Now, I mentioned before, I want to use a connector. So I've disconnected a config here. And then what we then want to do is invoke and add a new connection to a database. I'm not using Neon locally, but I am. I signed up to Neon, I created a database, and then you get a connection string. We'll look at that in about a minute or so. But yeah, go to neon.tech and create a database. If you want to follow along, if you just want to watch, that's also cool. And you could replay this and pause this later. Sometime too, but yeah, the best way is just to go to Neon. It's a hosted Postgres serverless platform. Just create a database there and you get a connection string. I just created a database with them and then created a table and added some content.
So back inside of here, I'm going to call this connected Neon and then I'm going to call connector, connector, if I can spell connector.postgres. Whoops, I might need to install. Let's just try this. I might be using an old version here. There we go. So yeah, if you run an NPS graph based in it and you don't see Postgres here, then you'll need to run NPM install just to get that latest version. But then I'm going to choose the postgres connector and I'm going to give this a name of Neon. You don't need to give us any... It's good to give it a name. The name doesn't really mean too much. If you don't want it to mean anything, you can disable that name being used from the namespace. But by default, Graphbase will namespace the output API, which is pretty cool. And then lastly, all we need to do here is tell it to use an env variable, so I'm just going to call this neon url. And then we're going to place that inside of this file here. So there's neon url I'm going to paste inside of here. And I will grab this from an example that I had previously, which is here. We'll paste that there. Doesn't really matter. I wouldn't you could use this one if you wanted to during this workshop. But you know, you probably want to use your own thing. I'll delete this after the workshop. Now we've got that connection string set. The last thing we need to do is run a G.dataSource, and then we can pass in Neon. And then that's the last piece of the puzzle there. I would try the latest. This is a very new connector that we've created. So I would imagine it's running the latest version of Postgres on that Neon support. So, yeah, I would just try the default version. I'm not sure how much we support other versions, because all we really do is introspect the database and create you an API for it. So now we've got that. The next thing to do, get my screen, is run mpx graph base. I'm gonna tag that latest, because I think I have an older version installed. And then I'm gonna run dev. That's then gonna look at this configuration file, and it's gonna generate me a GraphQL API.
6. Automatic Generation of GraphQL Schema
The types are automatically generated, and a schema is created for the service. The GraphQL schema is generated from the NEON database. No need to install Express or any plugins. Just have Node.js and npm installed. The quickstart documentation provides a step-by-step guide. The GraphQL schema includes types for the database tables and supports batch mutations. The query 'neon' is the namespace of the database adapter. The query fetches the first user from the user collection using cursor-based pagination. The query is executed on the database in SQL terms.
And if you pay some attention over here, we can see it's generated some types here. I haven't done anything. I haven't created any custom types. There's no schema there yet. But this shows that things are started, and there's a hidden folder in here, schema. And it's kind of created a schema that we need for um the service to actually work. So that's all we need.
We then need to go to Pathfinder on localhost port 4000. And then this is the cool thing. We have a GraphQL schema here that has been generated from the NEON database that I have. If I go to type query, and we see here we have a NEON query. Let's now fetch that NEON query. We can then see we've got a query to fetch a single NEON user by a field. That field could be an ID or it could be another unique constrained field row uh column sorry. And then we have a collection query as well. And we can see here we've got pagination and ordering in here. That is something which we automatically generate and handle for you. So if you've used any services that create GraphQL APIs from a database, schema, this is all we're doing at this point which is pretty cool.
So another question is do we need to install Node.js like Express? Nope. Download any plugins? Nope. Any library access to workshop? Nope. No you don't need to install Express or anything. You will need Node.js and npm install in your machine. Like I said, if you haven't done that already then you could just follow along and do this at your leisure later. There is documentation to a quickstart and I'll leave that in the chat as well, which is right here. There's a link to the quickstart in there as well. So if you do want to follow along and you don't have any of this installed, you can do this at your leisure later.
So we're going to be following some of this quickstart and dive off down different paths as the chat goes on. So we have this GraphQL schema that was automatically generated for us, and then here we've got things like onNeonUser, and user is the name of the table in Neon, in our Postgres database. If we go here, we've then got this table user. We've introspected the database, we've seen that there's a table called user, and then we've generated a type in GraphQL called user. We've then looked at the type called the name, and we can see that those are strings as well, and that those are non-nullable, so we've created a type for that as well. And then if you can see here, we've got things like a batch mutation, so if you wanted to create many, update many, or delete many, we have all of those different GraphQL mutations as well for you. And then we can see here, there's various other things for collections and input types. This isn't too important right now, you can explore all this as you're writing your GraphQL queries, so I think we should probably do that. So with a GraphQL query, we have a query here called neon, that's the namespace of the database adapter that we created. So that neon namespace is based off this value here. We could, if we wanted to, pass namespace false, then if we call false here, GraphBase detects that change locally and it restarts the server, so now this neon doesn't exist. There's no such namespace. Instead, what we have is everything's flattened and we have user and user collection as the root here. So let's use that just to play around, and here we can say let's fetch the first one user, and we follow a specific convention within GraphQL. If anyone's familiar with the relay pagination specification, we loosely follow that by giving you some edges here. Edges are pretty cool because we can then look at the node, which is the specific record. Here we can fetch the name and the email as well as the ID, and also from that we could fetch the cursor because we do cursor-based pagination. You're able to kind of fetch before and after a cursor, and that cursor is where it is in the list, so if things are added or removed, you're not having to kind of... You know, there's a lot of downsides to using the offset-based pagination, so cursor, you've got access to that cursor as well. Then there's some of the things like the current page that you're on, we can see it doesn't have a next page, doesn't have a previous page within this GraphQL request. So this query here is going to, if we run this, it's going to go to the database and it's going fetch the first user from the user collection here. So we can see there is another page, so if there's another page, cool, I can then say, okay, pass me the first item after this cursor here. So copy that, and then we'll run that, and then we get the next user in the database from neon, and this GraphQL request goes to GraphBase, GraphBase looks at the query, we then project that same query onto the database, but in SQL terms, not in GraphQL.
7. GraphQL API with Neon Database
We have a GraphQL API based on our neon database with pagination, ordering, and filtering capabilities. Neon is a Postgres offering and competes with PlanetScale, Hasura, and possibly Apollo. GraphBase focuses on a local experience for creating GraphQL APIs without extra installations. We can fetch users by ID or email, and mutations are automatically generated. However, there may be some issues with the mutation in this brand new connector.
So all of this now we have a GraphQL API that is based on our neon database, and here we can see we've got things like pagination. So if I remove the pagination after cursor and I just say fetch the first 100, I run that, I get the two users that are in my database, let's clear some of this stuff off, that's not too important, and let's have a look at something else.
So here we can see we've got order by, so we can order some of the things by name, for example, so we could, let's just do the ID action, so it's probably the easiest one. So we'll order the users by descending order, and then we'll see here, we get the data return to us, so you've got the different ordering things in there as well, and then filter, we can do the same with filter, we can apply one or many filters in here, so I could just say, okay, fetch me, you know, fetch me this user from this collection, and that would fetch that as well. Whoops, this will be equal to, so yeah, here, you could do email is equal to this value, and it will filter those results out and give me the result that I want, or I could do it in an array, so if you had a list of emails that you wanted to query, you could use that as well.
8. Creating Connectors and Configuring Caching Rules
We'll explore how to create a connector for an API and use the TrevorBlades API to fetch countries. We'll also learn how to fetch data from different APIs and configure caching rules to reduce latency. GraphBase aims to solve latency issues by providing edge caching and caching rules. By configuring caching rules, we can improve the performance of our GraphQL API and reduce data latency.
We'll just say test email is test.test.test.com. I worked that time. It could be that it's a namespace issue. I will make a note of that mentally and we'll figure that out. Probably just for that.
The GraphQL API for queries and mutations are automatically generated based off what you have inside of here. All we have inside of here is a single connection to our database. The next thing I want to show you is how we can create a connector for an API. Maybe I can use the TrevorBlades API. This is an API to fetch countries and we can make GraphQL queries here. This is a separate endpoint. We've got all of these different services. We've got a neon database and we're going to have a country API to fetch countries. We could have a cart API as well to fetch carts as well. Let's do that. Let's have a connector.graphql. I'm going to give it the name cartQL and then give it a URL. I'm not going to add this as an environment variable because it's not like code for best practices but it's not something that I really need to add as an environment variable because that URL couldn't change. But if we add this here, now, when I save, graph base detects the change, it restarts the local server. I go back to Pathfinder locally and then we can see here we've got a mutation cartQL. This is another namespace and then we've got all of these things here and these are all of the mutations that are inside of that GraphQL API. And then here again we've got query namespace where we can fetch things from a different API. Here we'll just fetch in NEON or do React or whatever we want. And then we can fetch in the subtotal amount, formatted amount. That goes to the GraphQL API and it resolves that data. I could do the same for NEON and here I could fetch the first 100 users from NEON. Let's just fetch their name and then one GraphQL request we've now talked to two different services. We've talked to the Carts API and then we've talked to the NEON database. But if I open up the history pane here and I run a few more of these queries, let's just clear this out. If I run this query, got to go to one API and then go to another API and then return the results. This has taken still for a second to get that data back. And it doesn't matter how many times you run that there is still latency. Now imagine your users are all around the world that's open to these databases and it's going through GraphBase. Yes, GraphBase is at the edge but if your database or your API for commerce is an edge as well, and it's not in the same pot, then there's going to be some out of latency. Now, that's something that we've from the outset wanted to solve with GraphBase. So the best way to do this is inside of here, we can then go on to configure some caching rules. I'm just going to cover some very basic caching rules here. The easiest one to demonstrate is just to cache absolutely everything. So let's just put in query is the type name that we want to cache, and then we can add in max age on here. Let's say 60. And another cool thing is we support the stale while we validate option as well. So you can specify a length of time where it gets 60 seconds. But if a user makes a request and the data is older than 60 seconds, then give them that stale response and go revalidate in the background. So the next time you or another user fetches the data, it's going to be getting that fresh data from the database. So with that now saved, if we go back to Pathfinder and we run that query once, we'll see it takes about 1200 milliseconds, nearly 1300 milliseconds there. You run it again, that's now jumped to four milliseconds. So clear this out so it's a bit clearer. You run this again, again, 77 milliseconds, four, four, four, four, four. This is really fast because it's locally, but in production, you get those same kind of numbers in production as well. Yeah, it's pretty cool.
9. Edge Caching and Extending GraphQL APIs
Edge caching improves user experience by caching data at the deployment point, reducing database queries and resolving time. Changes made in the database are automatically invalidated in the GraphQL cache. Caching rules can be configured on a per-type basis, allowing for longer cache times for less frequently changing data. Caching reduces traffic to the origin database and helps stay within API limits. Caching is especially powerful for LLMs and OpenAI. Postgres databases can be used with GraphBase, and work is being done to support non-edge databases. GraphBase allows extending GraphQL APIs and joining them. A Gravatar URL can be obtained for users by extending the neon user type and creating a resolver file.
It's very easy just to kind of add the edge caching on here. And wherever this is deployed, that data is then cached at that point. So your users, wherever they are in the world, gets that data. It's all cached in. It's replicated. And hopefully your users, it's a much better experience because they're not having to go to the database and wait every single time. And as you add more and more services, it takes longer and longer and longer to resolve that stuff as well.
Now, if you make any changes on the database, if you run any mutations and you've changed, let's say, the name here, we will automatically, as long as you use the GraphQL endpoint that Graphbase provides, we will automatically invalidate that cached result in the GraphQL or the Graphbase, GraphQL cache. So if you change this user's name and remove two from there, next time you make a request, it's going to take a little bit longer than four milliseconds, but then it's cached again and then you get those fast responses. You can also configure all of those caching rules on a type per type basis as well. So you can add multiple rules in here, and you could say, for the types, let's say product and category. Those are typically things in e-commerce that don't change too much, things like the product description and images, those aren't frequently changed. Those may change once a month or a quarter whenever you have different marketing pushes, so you might want to cache those for much longer. So if anyone makes a request to fetch that data, it's coming straight from the cache and it's not going to your database. And the best thing about that is by reducing the traffic to the origin database or other service, you can stay well below any of their API limits. If you have to pay for API limits to increase API limits or more API calls, when you add caching in front of it, you don't have to. So one area that this is quite powerful for is actually with the lots of the different LLMs and things like OpenAI, you're able to kind of cache. Yeah, so you're able to make a request, pass your instructions and if the instructions are similar and have the same variable, then you can get the cache response and you don't have to execute that code every time and burn through all of your different tokens. You could cache all that data at the edge for your apps. Right now, you can put in a Postgres URL and we will handle it. It has to be HTTP-based, I think, at the moment. But give it a try and let us know what happens there. As far as I know, you should be able to use any Postgres database, but if it doesn't, it should just work with HTTP-based databases. I'm not sure if it's in production just yet, but we're working on the ability to kind of add any and use any and bring non-edge to the edge. And then, yeah, I think one other thing, which is pretty cool to show, is something in this project here. So I did this a bit earlier, kind of experimenting, but let's take this code. It isn't too important, but I'm going to paste some code in here. Now, neon, connect to here, neon generates types that we've seen earlier called neon user from my user table. Now, my user, every user has an email. But let's imagine we want to allow you in the query to get the Gravatar URL for users. Well, GraphBase allows you to do that. You can extend any GraphQL API and join them. So here, we extend the neon user, give it a new field of avatar and specify some arguments with different types that are optional. Then we specify that this Gravatar field returns URL and uses the file that's called Gravatar. So let's create a file inside of the GraphBase folder. We'll call this resolvers, is the folder name and then gravatar.ts. This here, by adding in slash, it's just going to quickly create that folder for us. And then inside of here, I'm just going to get the code that I did earlier. This code is not important. This is just a way to generate, believe it or not, the Gravatar URL in an edge function. Because we're based at the edge and we use Cloudflare Workers, you can install node modules, but they have to be edge compatible. So things that use the file system and stuff like that will not work or the crypto libraries. So with this, we have to use the native crypto library that's built into Cloudflare Workers because that's where we deploy. Like I say, it's not too important, but we do all of that. We get the email from the query. We then encode it. It will be one. We then pass in any different options or custom options that we've passed through, and then we encode that URI and return it to the GraphQL resolver. So if we give that a go down here, let's fetch the email. So we'll close that.
10. Adding Gravatar to GraphQL API
We can add Gravatar to the GraphQL API and customize the options. The response is cached, resulting in faster subsequent requests. Custom resolvers can be created for queries, mutations, and fields. GraphBase can automatically detect changes and deploy them when the project is committed to GitHub. GraphBase supports various databases, including Postgres, MongoDB, and OpenAPI.
Actually, we'll keep it open because it's important. So here we've got two or three users, and we have the email. Now if I add Gravatar, this field is now part of the GraphQL API, and then we've got some custom options here. We could pass in the size. Let's say it's 400 pixels. We run this query. Then this is going to go to the database, get the users. Then it's going to compute the code for the email to create the URL. If we scroll down, it took about four seconds, which is an insane amount of time, but it had to do all of this stuff. But the next time we request it, we do it again, it's going to come back in three milliseconds because it already cached the response. It didn't need to compute all of this stuff.
So now we can see that we have Gravatar returned to us for all of our different users. So if I click on this, follow the link, we then get that Gravatar URL. And the URL here was automatically generated using the email field and hashtag, did what it needed to do. And it ran this code when you requested that field. If it didn't request the field, it doesn't run the code. And all of this, when you deploy all of this, is right at the edge and bundled inside of your API as well.
So if you've created a GraphQL server before, you can create custom resolvers for queries, mutations and fields, just like you can in any other GraphQL framework. But the beauty of this is once you commit this to GitHub, GraphBase can automatically detect that and deploy it automatically, which is pretty cool. Yeah, database, wherever it's hosted, as long as it's Postgres. You could use MongoDB. And you could use OpenAPI as well. Yeah, that is that one. Let me just fetch the project. That has Mongo in it.
11. Using MongoDB and Contentful with GraphBase
Here, we explore examples of using MongoDB and Contentful with GraphBase. MongoDB Atlas is used for HTTP-based MongoDB connections. Constraints can be added to documents, and JSON fields can be attached as data sources. Contentful can be integrated with GraphBase to extend its API and fetch additional data. The GraphBase OpenAPI connector allows introspection and transformation of OpenAPI specs. GraphQL's concise and restrictive spec makes it a powerful tool for federating services. GraphBase enables extending fields in Contentful queries and fetching external data. Changes made to branches in GitHub automatically trigger redeployment in GraphBase.
Yeah, so this is a Mongo example. Here we call it MongoDB. We give it a name, pass in all the credentials. Again, this is HTTP-based, so this is using MongoDB Atlas for this. We then can create those constraints around our documents. So we can say here, we're going to say this is an address, as these fields, and then we have a user, which has an address, which has a reference. And we can do things like JSON fields, give it the collection name, and then attach it as a data source, which is pretty cool.
And yeah, another example here is Contentful. There's an example guide on the Graphbase website. I'll share this in the chat because it's pretty cool. But one thing that we see a lot of users doing is adding their existing GraphQL APIs, adding edge caching, and then extending those APIs with their custom code. So it doesn't matter what GraphQL API that you're using, you can just add it to Graphbase, remove the namespace, and everything should just work as normal. All you'd need to do is change the endpoint. So this guide here, I'll leave a link in the chat, OpenAPI would work similar to generating types from an OpenAPI specs run. Yep, very similar idea. I think the biggest thing with OpenAPI is the spec, it can be so easily, quickly abused. And we've seen this generate in the connector, is people try to follow it, but then, I don't know why but people either, I've done this myself, is you create a spec, and it's very easy to just not mention things in the spec or not use certain fields or keys, which is totally valid by OpenAPI spec because it's quite a lot of ambiguity and optional stuff that it makes it really hard to rely on that stuff to create the best experience. So we have an OpenAPI connector which can introspect the OpenAPI spec, and there's a way you can transform that as well. So you could say, use a different name, name a convention based on whatever you've got in the spec, because honestly there's so much stuff that just gets forgotten in those specs. And what I really like about GraphQL is, it's a very concise spec, and it's very hard to abuse it. I love the spec for that reason. GraphQL itself is pretty cool. I think it's a really good implementation, and it finds itself in a cool space when it comes to federating all of your different services into a single GraphQL API. That is super powerful, but I think the specification itself is so good. It's so, so good because it's, like I say, very, very restrictive in what you can do. But yeah, this is what I was talking about before. We're using Contentful. We create some stuff in Contentful for properties, and then we publish that, then we create a GraphQL backend. And then this is a ... The concept of this guide is actually properties that belong in Contentful. You want to make a query to fetch those, but then you want to get the current weather about the properties inside of Contentful. Now, Contentful has no idea about the weather and you can't extend that API, but with GraphBase, we're able to add a proxy in front of Contentful that's able to extend a field in a query from Contentful, which is super cool and it works locally as well. We then just kind of use the values from the query, pass our API keys to our weather API and then we'll return the data. Honestly, this is the best thing. I love this kind of stuff with GraphBase. So, yeah, there's many other use cases.
My resolutions are a bit, but I mentioned branching and instant preview branching earlier. So any change you make and commit that you make to your branch with GitHub will automatically deploy a preview for you. So, I go to my dashboard now and we just go to this project here. If I open the Git repository, if I make any changes to this repo, it's going to redeploy this project, which is pretty cool. And any analytics, there'll be nothing that goes on in this project because it's not used. It's just a demo. So, yeah, any change you make, you can see all the different kind of changes that were made in here, which is pretty cool.
So, yeah, please do let me know if there's any comments. We'll probably wrap up in about eight minutes or so. But I just wanted to use the time today really just to kind of show a few of those things within GraphBase that you're able to do. Kind of coming back to what we were talking about at the very beginning, what we've been able to accomplish in a very short space of time actually is adding different data sources. And, you know, like I said, this could be a CMS, could be an API, send an SMS, eCommerce, or payments or whatever. When you need to retrieve that data or update that data or whatever, and you want to either extend or cache that and make it faster, you no longer have to go and pay to replicate data. We'll replicate that for you.
12. GraphBase Integrations and Examples
GraphBase offers integrations with different data services and allows you to deploy the runtime yourself. The platform is open source, including the CLI and templates. GraphBase supports various databases, such as KV storage, MongoDB, and PlanetScale. Examples of using GraphBase in projects are provided, including fetching data with resolvers and creating GraphQL APIs manually. The platform also offers examples for React, Vue, Nuxt, Next, NextAuth, and Click.
Yes, it's on a cache basis, but we're working on some pretty cool integrations with different data services. So we're able to kind of think your data to the edge automatically. So if that sounds interesting, please let us know. We do have Discord and things as well. So if you want to join that and ask any questions, you can go to graphcase.com and there is a link to Discord here as well.
And everything I've spoken about today is available on GraphBase. And the last thing is that everything you've seen is open source and you can even deploy this yourself to Cloudflare or Deno deploy, which is pretty cool. The GraphBase engine is all open source. It's built in Rust, like I mentioned before, and we take that, we build that web assembly and push that to the edge. With Cloudflare, that's our hosted service. But if you don't want to pay for our hosted service, which gives you seams and the branching support, stuff like that, if you just want to deploy the runtime yourself, you can. It's all open source. You don't need to pay us a thing, which I really love.
So, yeah, we're committed to open source. We love working in open source. Our CLI is open source. All of our templates are. If you just open the template, see, I've added a bunch in here for different services. So, Stripe. But this Stripe one actually uses the open API spec. So, it uses this to then generate a GraphQL API. And we're able to kind of use header forwarding with our GraphQL requests. So, your end user, your service, GraphBase doesn't even know your API keys. You can forward that from different requests, which is pretty cool. All right. So many other things in here. And there are a few other examples as well for actually using GraphBase in actual projects. So, we've got things like the KV storage, which I haven't spoken about today. But this GraphBase has its own KV storage. Planet scales in there. Planet scale. So, you can use any database with GraphBase as long as it's kind of HDB compatible.
And if we go into here and look at our products resolver. Let's just get the query here. We'll see we import the dependency for the database. And then we're able to do what we need to return the data that we like. There's other things in here, as well. Like MongoDB. So, as well in here. So, we make a resolver fetch all of our users. Here we install LibSQL. So, that's a fork of SQL Lite. We import the client, connect to it. And then we can run whatever we need. And we can create a GraphQL API from that. This is more manual and hands on. It's not automated like the connectors, but the more connectors we make, that will automate. You have to do all this stuff manually. But there's some other examples in here for React and Vue and quick, and Nuxt and Next. If you want to use things like Next, NextAuth or Click.
13. Adding API Rules and Security with Click
In this part, we explore how to add API rules and security to your GraphQL API using Click as the auth provider. By passing an authorization header and token, Click acts as the open ID connect provider and verifies the JWT. If everything checks out, the request is allowed to proceed to GraphBase. You can also use JWT and custom code/resolvers for added security. This example demonstrates how to configure and implement these features.
We haven't again spoken about it because there's so much in the GraphQL product that we haven't. It's too much to go over. But if we look at the configuration here, I've specified, this is a different configuration format by the way, but I specified here that we use Click as our auth provider. And what this does is it adds an API, it adds kind of a layer in front of GraphBase. So if you pass an authorization header and you pass it a token, it will use Click as the open ID connect provider. It looks at that provider's spec to get the URL for where it should compare the JWT. So it gets what they call the JWKS, and it gets that and then it looks and checks if everything's okay. If everything's okay and Click says, yep, you're good, we then allow the request to the GraphBase. So if you want to add API rules and security on top of your GraphQL API, you could use Click, you could use JWT, you could use some custom code and a custom resolver. You can do all of that there in this example in here. Does that show you how to do that?