Skip to content
KeystoneJS LogoKeystoneJS
👋🏻 Keystone 5 has officially moved to maintenance only. For the latest release of Keystone please visit the Keystone website.

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 post.

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

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, MySQL, SQL Server, Oracle, and MariaDB. 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 and Amazon Redshift 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

OptionTypeDefaultDescription
isRequiredBooleanfalseDoes this field require a value?
isUniqueBooleantrueAdds a unique index that allows only unique values to be stored
gqlTypeStringInt or IDThe 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 for details.

Field nameTypeDescription
${path}Int or IDThe integer value to save

Output fields

Field nameTypeDescription
${path}Int or IDThe integer value stored

Filters

Field nameTypeDescription
${path}Int or IDExact match to the value provided
${path}_notInt or IDNot an exact match to the value provided
${path}_ltInt or IDLess than the value provided
${path}_lteInt or IDLess than or equal to the value provided
${path}_gtInt or IDGreater than the value provided
${path}_gteInt or IDGreater 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() by default. The underlying implementation varies in significant ways depending on the DB platform used (see limitations).

One implication of increments() is that Knex will always make it the primary key 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 more about auto inc and their usage as primary keys.

On this page

Edit on GitHub