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:

• Has important limitations due to varying support from the underlying DB platform
• Has 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, 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

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 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() 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.