export const meta = {
  title: `Overview`,
  description: `Add a GraphQL API + database to your Amplify app using the Amplify CLI`,
};

<MigrationAlert url={"/cli-legacy/graphql-transformer/overview"}/>

Amplify CLI's GraphQL API category makes it easy for you to create a new GraphQL API backed by a database. Just define a GraphQL schema and Amplify CLI will automatically transform the schema into a fully functioning GraphQL API powered by AWS AppSync, Amazon DynamoDB, and more. 

## Creating your first table

First, set up your GraphQL API by running:
```bash
amplify add api
```
```console
? Select from one of the below mentioned services:
> GraphQL
? Here is the GraphQL API that we will create. Select a setting to edit or continue
> Continue
? Choose a schema template:
> Single object with fields (e.g., “Todo” with ID, name, description)
...
Edit your schema at <...>/schema.graphql or place .graphql files in a directory at <...>/schema
✔ Do you want to edit the schema now? (Y/n)
> yes
Edit the file in your editor: <...>/schema.graphql
✅ Successfully added resource new locally
```

Accept the default values and your code editor should show a GraphQL schema for a Todo app.

```graphql
# This "input" configures a global authorization rule to enable public access to
# all models in this schema. Learn more about authorization rules here: https://docs.amplify.aws/cli/graphql/auth
input AMPLIFY { globalAuthRule: AuthRule = { allow: public } } # FOR TESTING ONLY!

type Todo @model {
  id: ID!
  name: String!
  description: String
}
```

Every GraphQL `type` with the `@model` directive is automatically backed by a new DynamoDB database table.

<Callout warning>

`input AMPLIFY { globalAuthRule: AuthRule = { allow: public } }` allows you to get started quickly without worrying about authorization rules. Review the [Authorization rules](/cli/graphql/authorization-rules) section to setup the appropriate access control for your GraphQL API.
</Callout>

Now let's deploy your changes to the cloud:

```bash
amplify push
```

That's it! Your API and database tables are set up. 

## Setup your app code

Use Amplify libraries to connect your app with your GraphQL endpoint. 

Add the Amplify library to your app with `yarn` or `npm`:

```bash
npm install aws-amplify
```
In your app's entry point i.e. App.js, import and load the configuration file:

```js
import { Amplify, API, graphqlOperation } from 'aws-amplify';
import awsconfig from './aws-exports';
Amplify.configure(awsconfig);
```

## Add your first record

Next, let's try to query from the GraphQL API. Follow along the steps below to make a query from a React app:

```js
import { API } from 'aws-amplify'
import { createTodo, updateTodo, deleteTodo } from './graphql/mutations'
import { listTodos } from './graphql/queries'
```

Then, create your first todo item with the a GraphQL API call:

```js
const result = await API.graphql(graphqlOperation(createTodo, {
  input: {
    name: 'My first todo!'
  }
}))
```

## Query records from the table

Use the GraphQL query statement to list all todos in your app:

```js
const result = await API.graphql(graphqlOperation(listTodos))
console.log(result)
```

You should see the record created above: `My first todo!`.

## Update the record

To update the record use the GraphQL update mutation:

```js
const result = await API.graphql(graphqlOperation(updateTodo, {
  input: {
    id: "<...>",
    name: "My first updated todo!"
  }
}))
console.log(result)
```

The result should contain the updated value: `My first updated todo!`.

## Delete a record

Let's clean up your database! Delete the todo by using the delete mutation:

```js
const result = await API.graphql(graphqlOperation(deleteTodo, {
  input: {
    id: "<...>",
  }
}))
console.log(result)
```
The result output should indicate to you that the record was successfully deleted!

## Update schema

If you want to update your API, open your project's `amplify/backend/api/<api-name>/schema.graphql` file (NOT the one in the `amplify/backend/api/<api-name>/build` folder) and edit it in your favorite code editor. You can compile the `amplify/backend/api/<api-name>/schema.graphql` file by running:

```bash
amplify api gql-compile
```

and view the compiled schema output in `backend/api/~apiname~/build/schema.graphql`.

You can then push updated changes with:

```bash
amplify push
```

The following schema updates require replacement of the underlying DynamoDB table:
1. Removing or renaming a model
2. Modifying the [primary key](/cli/graphql/data-modeling/#configure-a-primary-key) of a model
3. Modifying a Local Secondary Index of a model (only applies to projects with [secondaryKeyAsGSI](/cli/reference/feature-flags/#secondaryKeyAsGSI) turned off)

When trying to push a schema change with one or more of these updates you will see an error message explaining that you will lose ALL DATA in any table that requires replacement. To confirm you want to continue with the deployment, run:
```bash
amplify push --allow-destructive-graphql-schema-updates
```
<Callout>
In general, this command should only be used during development.

If you are making a breaking change to a production API but you want to retain the data in the affected table(s), you can [create a backup](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/CreateBackupAWS.html) before running `amplify push --allow-destructive-graphql-schema-updates`
</Callout>

## Rebuild GraphQL API

<Callout>
Rebuild should NEVER be used in a production environment!
</Callout>

When in development, sometimes test data gets in a bad state or you want to make many changes to your schema all at once. In these cases, you may wish to "rebuild" all of the tables backing your schema. To do this, run:
```bash
amplify rebuild api
```
This will recreate ALL of the tables backing models in your schema. ALL DATA in ALL TABLES will be deleted.



## Next steps

Success! You've learned how to create a GraphQL API backed by a database table and also how to run queries and mutations from your app. 

There's so much more to discover with Amplify's GraphQL API capabilities. Learn more about: 
- [How to model your database table and their access patterns](/cli/graphql/data-modeling)
- [Secure your API with fine-grained authorization rules](/cli/graphql/authorization-rules)
- [Create relationships between different database model](/cli/graphql/data-modeling/#setup-relationships-between-models)
- [Add custom business logic to the GraphQL API](/cli/graphql/custom-business-logic)
- [Run search and result aggregation queries](/cli/graphql/search-and-result-aggregations/)
- [Connect to machine learning services](/cli/graphql/connect-to-machine-learning-services/)
- [Examples and solutions](/cli/graphql/examples-and-solutions/)