
You can now restrict access to specific operations using rules when configuring your project's schema.

You can set the following rules when using signed-in or group based authorization:

- `get` &mdash; Allow [Fetch by ID](/docs/reference/queries#fetch-by-id) queries
- `list` &mdash; Allow [Fetch by collection](/docs/reference/queries#fetch-by-collection) queries
- `read` &mdash; Combines both `get` and `list`
- `create` &mdash; Allow [create](/docs/reference/mutations#create) mutations
- `update` &mdash; Allow [update](/docs/reference/mutations#update) mutations
- `delete` &mdash; Allow [delete](/docs/reference/mutations#delete) mutations

You can now provide an array of allowed operations when [configuring rules](/docs/reference/directives#rules).

```graphql
schema
  @auth(
    providers: [{ type: oidc, issuer: "{{ env.ISSUER_URL }}" }]
    rules: [
      { allow: private, operations: ["read"] }
      { allow: groups, groups: ["moderator"], operations: ["update"] }
      { allow: groups, groups: ["admin"] }
    ]
  ) {
  query: Query
}
```

The schema above will control data access for:

- Signed-in users to perform `read` operations
- Users of the `moderator` group to perform `update` operations
- Users of the `admin` group to perform all operations

<YoutubeWidget url="https://www.youtube.com/watch?v=vwUGlwbdfvI" />

<a href="/docs/reference/schema#operations" class="card">
  Learn more about restricting allowed operations
</a>

We'd love to hear your feedback and ideas, so join us on [Discord](https://discord.gg/grafbase).



We're happy to announce the release of paginated relations.

You can now paginate relations using arguments `first`, `last`, `before`, and `after` with [`connection`](/docs/reference/pagination#connections) types &mdash; [learn more about Pagination](/docs/reference/pagination).

<Tabs>

<TabItem label="Schema">

```graphql
type Category @model {
  id: ID!
  name: String
  posts: [Post]
}

type Post @model {
  id: ID!
  title: String
  category: Category
}
```

</TabItem>

<TabItem label="Fetch first 10 posts by category">

```graphql
query {
  category(id: "...") {
    name
    posts(first: 10, after: "...") {
      edges {
        node {
          title
        }
      }
    }
  }
}
```

</TabItem>

<TabItem label="Fetch all categories and posts">

```graphql
query {
  categoryCollection(first: 10) {
    edges {
      node {
        name
        posts(last: 10) {
          edges {
            node {
              title
            }
          }
        }
      }
    }
  }
}
```

</TabItem>

</Tabs>

The schema above represents a **_Category_** that has many **_Post_**s, and a **_Post_** belongs to one **_Category_**.

<YoutubeWidget url="https://www.youtube.com/watch?v=Vyy9WcHqKrw" />

## Other changes

- Grafbase CLI [0.8.0](https://www.npmjs.com/package/grafbase/v/0.8.0) has been released to include all of the above.
- [OpenID Connect](/docs/reference/directives#providers) is now supported locally with version 0.8.0
- Special thanks to [@ajcwebdev](https://twitter.com/ajcwebdev) for [fixing a typo](https://github.com/grafbase/grafbase/pull/84) with the `init` output.

We'd love to hear your feedback and ideas, so join us on [Discord](https://discord.gg/grafbase).



You can now login to Grafbase via email. Head to the [sign in](/sign-in) where you can enter your email to request a magic link.

<YoutubeWidget url="https://www.youtube.com/watch?v=UDarBXNG_cQ" />

If you're not already signed up, [join the waitlist](/join-the-waitlist). We're actively inviting new users to the platform.

We'd love to hear your feedback and ideas, so join us on [Discord](https://discord.gg/grafbase).



We're happy to announce that the playground you use to perform queries and mutations against your project’s backend has now been updated to use the new and improved GraphiQL 2.0.

This new version of GraphiQL comes with support for tabs, variables, merging fragments, prettifying operation payloads, history, and more.

<YoutubeWidget url="https://youtu.be/VPti8vGvjAg" />

You can use the new playground by visiting any branch in your project dashboard. Here you will find all of the above as well as built-in documentation to explore the supported queries and mutations for your backend.

We'd love to hear your feedback and ideas, so join us on [Discord](https://discord.gg/grafbase).



We're extremely happy to announce the release of our newest feature &mdash; [Environment Variables](/docs/concepts/environment-variables).

Here's an example using an environment variable for your auth provider issuer URL right inside your project schema:

```graphql
schema
  @auth(
    providers: [{ type: oidc, issuer: "{{ env.CLERK_ISSUER_URL }}" }]
    rules: [{ allow: private }]
  ) {
  query: Query
}
```

We've made it easy to set environment variables per environment too. This means you can set different variables for production and preview environments.

You can add, edit, or delete environment variables from inside your project settings at anytime.

<YoutubeWidget url="https://www.youtube.com/watch?v=qd0k7woy9Wk" />

You can also set environment variables inside of the file `grafbase/.env` that will be used by schema when running `grafbase dev`.

## Other changes

- Grafbase CLI 0.7.0 has been released to include all of the above.
- The GraphQL Scalar `PhoneNumber` has been added.

We'd love to hear your feedback and ideas, so join us on [Discord](https://discord.gg/grafbase).



We're super excited to share that the official [Grafbase + Clerk integration](https://clerk.dev/integrations/grafbase) is now live!

Grafbase users can benefit from the amazing auth experience Clerk brings, as well as Clerk users are now able to leverage a powerful serverless GraphQL backend.

This integration is made possible by configuring Clerk as your identity provider when configuring schema. Clerk has made it super easy to get started using their [JWT templates](https://clerk.dev/docs/request-authentication/jwt-templates).

Here's how simple it is to configure with Grafbase:

```graphql
# Signed in user authentication
schema
  @auth(
    providers: [{ type: oidc, issuer: "YOUR_FRONTEND_API" }]
    rules: [{ allow: private }]
  ) {
  query: Query
}

# Group-based authentication
schema
  @auth(
    providers: [{ type: oidc, issuer: "YOUR_FRONTEND_API" }]
    rules: [{ allow: groups, groups: ["backend", "admin"] }]
  ) {
  query: Query
}
```

Follow the [Grafbase integration guide](https://clerk.dev/docs/integration/grafbase) to get started. Here you will learn how to setup Clerk, JWT templates, and how to authenticate requests with a valid token.

We'd love to hear your feedback and ideas, so join us on [Discord](https://discord.gg/grafbase).



We're extremely happy to announce that Grafbase supports [OpenID Connect](https://openid.net/connect/) (OIDC).

Grafbase authorization with OIDC currently supports both signed-in user and group-based data access &mdash; [learn more](/docs/guide/auth).

OIDC is an open authentication protocol that sits on top of the OAuth 2.0 framework. With our OIDC integration, users of your applications can take advantage of single sign-on without the need to write all of the code necessary to authenticate and authorize users manually.

Tokens provided by your identity provider (Clerk, Auth0, etc.) can include the desired properties which Grafbase will check to allow or deny access to data.

Enabling OIDC authorization is easy with the `@auth` directive inside of your schema. All you need is the issuer URL supplied by your identity provider.

To restrict access to your project for signed-in users only, you can configure this using the `allow: private` rule:

```graphql
# grafbase/schema.graphql

schema
  @auth(
    providers: [{ type: oidc, issuer: "YOUR_ISSUER_ENDPOINT" }]
    rules: [{ allow: private }]
  ) {
  query: Query
}
```

With group-based authorization you can allow access based on the `groups` contained in a user token:

```graphql
# grafbase/schema.graphql

schema
  @auth(
    providers: [{ type: oidc, issuer: "YOUR_ISSUER_ENDPOINT" }]
    rules: [{ allow: groups, groups: ["backend", "admin"] }]
  ) {
  query: Query
}
```

Access is granted based on JWTs sent in the header of requests made to your Grafbase backend.

These tokens contain all the data Grafbase needs in order to check if you are who you say you are and can do what you're requesting. These tokens when decoded look something like this:

```json
{
  "exp": 1659646197,
  "groups": ["admin"],
  "iat": 1659559797,
  "iss": "YOUR_ISSUER_ENDPOINT",
  "nbf": 1659559792,
  "sub": "user_12345"
}
```

We'd love to hear your feedback and ideas, so join us on [Discord](https://discord.gg/grafbase).



We're extremely happy to announce the release of **5 new scalars**:

- [`JSON`](#json)
- [`URL`](#url)
- [`Email`](#email)
- [`Timestamp`](#timestamp)
- [`IPAddress`](#ipaddress)

These can be used inside of your schema to attribute certain fields to the type they are, as well as benefiting from the validations those bring. If any data doesn't meet the requirements of each scalar, an error with be thrown.

Let's take a look at how these can be used in our schema, mutating data, as well as the different specifications these scalars relate to.

### JSON

With the [ECMA-404](https://www.ecma-international.org/publications-and-standards/standards/ecma-404/) specification you can now set which field is a `JSON` object:

```graphql
type Order @model {
  id: ID!
  metadata: JSON
}
```

Simply pass valid JSON when mutating data:

```graphql
mutation {
  orderCreate(input: { metadata: { stripeCheckoutId: "abc" } }) {
    order {
      metadata
    }
  }
}
```

### URL

The `URL` scalar conforms to the [URL standard](http://url.spec.whatwg.org/) which can be used to set fields as a `URL`:

```graphql
type User @model {
  id: ID!
  avatarUrl: URL
}
```

Simply pass a valid URL when mutating data:

```graphql
mutation {
  userCreate(input: { avatarUrl: "https://github.com/notrab.png" }) {
    user {
      avatarUrl
    }
  }
}
```

### Email

The new `Email` scalar conforms to the [HTML Spec](https://html.spec.whatwg.org/multipage/input.html#valid-e-mail-address) which can be used to set fields as a `Email`:

```graphql
type User @model {
  id: ID!
  email: Email
}
```

Simply pass a valid email when mutating data:

```graphql
mutation {
  userCreate(input: { email: "jamie@grafbase.com" }) {
    user {
      email
    }
  }
}
```

### Timestamp

The new `Timestamp` scalar conforms to the Unix [epoch](https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap04.html#tag_04_16) format.

You can use this inside your schema by providing `Timestamp` for the desired field:

```graphql
type Activity @model {
  id: ID!
  when: Timestamp
}
```

Simply pass a valid timestamp when mutating data:

```graphql
mutation {
  activityCreate(input: { when: 1662032540 }) {
    activity {
      when
    }
  }
}
```

### IPAddress

A valid IPv4 or IPv6 address. IPv4 addresses are expected in quad-dotted notation `123.123.123.123`. IPv6 addresses are expected in non-bracketed, colon-separated format `1a2b:3c4b::1234:4567`.

To opt-into this behaviour, use the `IPAddress` scalar for the desired field:

```graphql
type Activity @model {
  id: ID!
  ip: IPAddress
}
```

Simply pass a valid IP Address when mutating data:

```graphql
mutation NewIPV4Activity {
  activityCreate(input: { ip: "123.123.123.123" }) {
    activity {
      ip
    }
  }
}

mutation NewIPV6Activity {
  activityCreate(input: { ip: "1a2b:3c4b::1234:4567" }) {
    activity {
      ip
    }
  }
}
```

## Other changes

- Grafbase CLI 0.6.0 has been released to include all of the above. If upgrading from versions before `0.4.0` you'll want to delete the `.grafbase` folder.
- Grafbase CLI 0.6.0 also fixes cursor support in paginated queries, and the order of results using `last`.

We'd love to hear your feedback and ideas, so join us on [Discord](https://discord.gg/grafbase).



We're extremely happy to announce the release of the `DateTime` scalar.

You can now mark fields in your models as `DateTime`. This new scalar uses the ISO 8601 standard. ISO 8601 represents date and time by starting with the year, followed by the month, day, hour, minutes, seconds and milliseconds.

You can read more about this within the document [rfc3339](https://datatracker.ietf.org/doc/html/rfc3339).

Here's how you can use it:

```graphql
type Event @model {
  id: ID!
  title: String!
  starts: DateTime!
  ends: DateTime
}
```

When mutating data, in the case of the above schema, you'll want to pass the ISO 8601 format to the input type:

```graphql
mutation {
  eventCreate(
    input: {
      title: "Grafbase DateTime Scalar Party"
      starts: "2022-08-17T13:43:30Z"
    }
  ) {
    event {
      id
      title
      starts
    }
  }
}
```

You'll then get a response that looks something like the following, including the `DateTime` response:

```json
{
  "data": {
    "eventCreate": {
      "event": {
        "id": "event_01GANRQA0NBMPKA0W3QCYJXXFC",
        "title": "Grafbase DateTime Scalar Party",
        "starts": "2022-08-17T13:43:30Z"
      }
    }
  }
}
```

## Other changes

- Grafbase CLI 0.5.0 has been released to include all of the above. If upgrading from versions before `0.4.0` you'll want to delete the `.grafbase` folder.
- Grafbase CLI now has a `reset` command to remove all local project data.

We'd love to hear your feedback and ideas, so join us on [Discord](https://discord.gg/grafbase).



We're extremely happy to announce the release of the `@unique` directive.

You can now mark fields in your models as unique, preventing duplicate entries in your collections.

All that's needed to make this work is to provide the `@unique` directive inside of your `@model` definition:

```graphql
type Post @model {
  id: ID!
  slug: String! @unique
  body: String!
}
```

If you try to use a value for a field that has been marked as unique, you'll get the following error:

```json
{
  "data": null,
  "errors": [
    {
      "locations": [{ "column": 3, "line": 2 }],
      "message": "The value \"foo\" is already taken on field \"slug\"",
      "path": ["postCreate"]
    }
  ]
}
```

Please note that unique fields are currently case sensitive.

## Other changes

- We changed the format of IDs of data returned from your project. This means `TodoList#123` will now be returned as `todolist_123`.
- The Playground inside of your project dashboard has had some minor styling improvements.
- Grafbase CLI 0.4.0 has been released to include all of the above. You'll want to delete the `.grafbase` folder if you have an existing database.

We'd love to hear your feedback and ideas, so join us on [Discord](https://discord.gg/grafbase).



Grafbase CLI 0.3.0 now supports live reloading.

Changes to your schema will automatically be detected when you're running `grafbase dev`, and the local development server will be reloaded accordingly.

You can opt out of live reloading by providing the flag `--disable-watch` when using the `dev` command.

We've also improved the default schema that is created when you initialize a new project with `grafbase init`, as well as some technical changes to how we test, and package the CLI. You can read more about these over on [GitHub](https://github.com/grafbase/grafbase/releases/tag/0.3.0).

If you've installed the Grafbase CLI globally, you can now use the alias `gb`.



We're extremely happy to announce the release of the Grafbase CLI.

The CLI allows you to create and develop your projects locally, in the comfort of your own `~`. No configuration, or Docker needed.

In a new directory, run the following to get started:

```
npm i -g grafbase
grafbase init
```

Then populate `grafbase/schema.graphql` with the following:

```graphql
type TodoList @model {
  id: ID!
  title: String!
  todos: [Todo]
}

type Todo @model {
  id: ID!
  title: String!
  complete: Boolean
}
```

Run the following to start your local development environment:

```
grafbase dev
```

Now with Grafbase running locally you will be able to execute the GraphQL operations generated from the schema defined above.

You can now visit the GraphQL Playground at [http://localhost:4000](http://localhost:4000) to create a new Todo List entry, with related Todos:

```graphql
mutation {
  todoListCreate(
    input: {
      title: "My todo list"
      todos: [
        { create: { title: "My first todo!" } }
        { create: { title: "My second todo!" } }
      ]
    }
  ) {
    todoList {
      title
      todos {
        title
      }
    }
  }
}
```

You can also update, delete, query all or individual entries for the models you defined above. Here's an example querying for the first 100 todoList items, and their linked todos:

```graphql
{
  todoListCollection(first: 100) {
    edges {
      node {
        title
        todos {
          title
        }
      }
    }
  }
}
```

You can learn more about the CLI [here](https://grafbase.com/cli). The CLI is [open source](https://github.com/grafbase/grafbase), and built with Rust.

We'd love to hear your feedback and ideas, so join us on [Discord](https://discord.gg/grafbase).


Changelog

Restrict allowed operations

Paginated Relations

Passwordless login

Improved Playground with GraphiQL 2

Environment Variables now available

Clerk integration now available

Authorization with OpenID Connect

JSON, URL, Email, Timestamp, and IPAddress scalars added

DateTime scalar now available

Unique directive now available

Grafbase CLI now supports live reloading

Grafbase CLI now available