<!--[meta]
section: api
subSection: field-types
title: AutoIncrement
[meta]-->

# AutoIncrement

> This is the last active development release of this package as **Keystone 5** is now in a 6 to 12 month active maintenance phase. For more information please read our [Keystone 5 and beyond](https://github.com/keystonejs/keystone-5/issues/21) post.

An automatically incrementing integer with support for the Knex adapter. It's important to note that this type:

- Has [important limitations](#limitations) due to varying support from the underlying DB platform
- Has [non-standard defaults](#non-standard-defaults) for much of its configuration

**Currently, outside its use as a primary key, this field type will only work on PostgreSQL.**

## Limitations

The majority of DB platforms allow only a single automatically incrementing column per table.
At time of writing (2019-07-11) this is true of
[SQLite](https://www.sqlite.org/autoinc.html),
[MySQL](https://dev.mysql.com/doc/refman/8.0/en/example-auto-increment.html),
[SQL Server](https://docs.microsoft.com/en-us/sql/t-sql/statements/create-table-transact-sql-identity-property),
[Oracle](https://docs.oracle.com/database/121/SQLRF/statements_7002.htm#SQLRF55661), and
[MariaDB](https://mariadb.com/kb/en/library/auto_increment/).
Further, it is often assumed these columns are the tables primary key.
On several platforms (eg. SQLite) auto increment functionality is _only_ available for primary keys.

Of the DB platforms supported by Knex, only
[PostgreSQL](https://www.postgresql.org/docs/9.1/datatype-numeric.html#DATATYPE-SERIAL) and
[Amazon Redshift](https://docs.aws.amazon.com/redshift/latest/dg/r_CREATE_TABLE_NEW.html#identity-clause)
supports _multiple_ auto incrementing columns.

## Non-standard defaults

The configuration for `AutoIncrement` fields has different default values than most field types.
Specifically:

- `isUnique` defaults to `true` --
  As unique values are generated by the DB it's assumed this uniqueness should be enforced with a unique constraint.
- `isNotNullable` defaults to `true` --
  Likewise, it's assumed values will never be updated or explicitly set to null.
  The column is set to be not nullable to enforce this.
- Read only --
  It's assumed `AutoIncrement` are not intended to be writable.
  Some DB platform will error if you attempt to update columns created by this type.
  Further, if the column has a unique constraint (as is the default; see `isUnique` in config above)
  inserting arbitrary values may cause errors when later records are created.
  As such, fields using this type default to being read-only.
  This is implemented by defaulting the `create`, `update` and `delete` field-level access control config to `false`.

## Usage

```js
const { Keystone } = require('@keystonejs/keystone');
const { AutoIncrement } = require('@keystonejs/fields-auto-increment');
const { Text } = require('@keystonejs/fields');

const keystone = new Keystone({...});

keystone.createList('Order', {
  fields: {
    name: { type: Text },
    orderNumber: { type: AutoIncrement, gqlType: 'Int' },
  },
});
```

### Config

| Option       | Type      | Default       | Description                                                                                 |
| :----------- | :-------- | :------------ | :------------------------------------------------------------------------------------------ |
| `isRequired` | `Boolean` | `false`       | Does this field require a value?                                                            |
| `isUnique`   | `Boolean` | `true`        | Adds a unique index that allows only unique values to be stored                             |
| `gqlType`    | `String`  | `Int` or `ID` | The GraphQL to be used by this field. Defaults to `ID` for primary keys or `Int` otherwise. |

## Admin UI

`AutoIncrement` fields reuse the interface implementation from the native `Integer` field.

## GraphQL

`AutoIncrement` fields can use the `Int` or `ID` GraphQL types.
This can be specified using the `gqlType` config option if needed.
The default is `ID` for primary key fields and `Int` otherwise.

### Input fields

`AutoIncrement` fields are read-only by default.
As such, input fields and types may not be added to the GraphQL schema.
See the [non-standard defaults section](#non-standard-defaults) for details.

| Field name | Type          | Description               |
| :--------- | :------------ | :------------------------ |
| `${path}`  | `Int` or `ID` | The integer value to save |

### Output fields

| Field name | Type          | Description              |
| :--------- | :------------ | :----------------------- |
| `${path}`  | `Int` or `ID` | The integer value stored |

### Filters

| Field name       | Type              | Description                                 |
| :--------------- | :---------------- | :------------------------------------------ |
| `${path}`        | `Int` or `ID`     | Exact match to the value provided           |
| `${path}_not`    | `Int` or `ID`     | Not an exact match to the value provided    |
| `${path}_lt`     | `Int` or `ID`     | Less than the value provided                |
| `${path}_lte`    | `Int` or `ID`     | Less than or equal to the value provided    |
| `${path}_gt`     | `Int` or `ID`     | Greater than the value provided             |
| `${path}_gte`    | `Int` or `ID`     | Greater or equal to than the value provided |
| `${path}_in`     | `[Int]` or `[ID]` | In the array of integers provided           |
| `${path}_not_in` | `[Int]` or `[ID]` | Not in the array of integers provided       |

## Storage

### Mongoose adapter

Not supported.

### Knex adapter

The `AutoIncrement` field type uses [`increments()`](https://knexjs.org/#Schema-increments) by default.
The underlying implementation varies in significant ways depending on the DB platform used (see [limitations](#limitations)).

One implication of `increments()` is that Knex will
[always make it the primary key](https://github.com/tgriesser/knex/issues/385) of the table.
To work around this, if this type is not being used as the lists primary key,
we replace the generic `increments()` call with an explicitly build `serial` column.
This work around only supports PostgreSQL; on other DB platforms, this type can only be used for the `id` field.
See the [Limitations section](#limitations) more about auto inc and their usage as primary keys.