---
description: Aidbox provides access to PostgreSQL sequences through REST API.
---

# Sequence API

In some cases you want to enumerate your resources with an increasing counter or use global sequences for your app needs. Aidbox provides handy access to [PostgreSQL sequences](https://www.postgresql.org/docs/current/sql-createsequence.html) through REST API. Values generated by this API are transactional and safe to use in concurrent environment. 

## Create Sequence

You can create named sequence by posting PGSequence resource. We use explicit naming for sequences, so the **id** element is required!

{% code title="create-sequence.yaml" %}
```yaml
POST /PGSequence
Accept: text/yaml
Content-Type: text/yaml

id: pt_seq
```
{% endcode %}

You can specify other PGSequence attributes:

| attr          | type    | desc                                                              |
| ------------- | ------- | ----------------------------------------------------------------- |
| **id**        | ident   | sequence name; only lower case, digits and \_ are allowed in name |
| **start**     | integer | initial sequence value (default 1)                                |
| **cycle**     | boolean | cycle after reaching sequence max/min value                       |
| **increment** | integer | sequence step (default 1)                                         |
| **maxval**    | integer | max value to cycle                                                |
| **minval**    | integer | min value to cycle                                                |

## Get next value

Now you can move sequence forward transactionally and reserve the next value:

```yaml
POST /PGSequence/pt_seq
Accept: text/yaml

# response
id: pt_seq
value: 1
```

Each call will increment the sequence.

You can get a range of values by providing the **count** parameter in the body.

```yaml
POST /PGSequence/pt_seq
Accept: text/yaml
Content-Type: text/yaml

count: 5

# response 200
id: pt_seq
values: [2,3,4,5,6]
```

## Read current value

You can read the current state of sequence without incrementing it with `GET /PGSequence/[id]`

```yaml
GET /PGSequence/pt_seq
Accept: text/yaml

# response 200
id: pt_seq
value: 1
```

## Reset value

You can set the sequence to a specific value by `PUT /PGSequence/[id]`

```yaml
PUT /PGSequence/pt_seq
Accept: text/yaml
Content-Type: text/yaml

value: 30

# response 200
value: 30
```

This will reset the current sequence value to 30, so next get value operation will return 31:

```yaml
POST /PGSequence/pt_seq
Accept: text/yaml

## response 200
value: 31
```

You can use this endpoint if you want to update or create sequence:

```yaml
PUT /PGSequence/pt_seq
Accept: text/yaml
Content-Type: text/yaml

start: 300

# response 201 - created

--- 
PUT /PGSequence/pt_seq
Accept: text/yaml
Content-Type: text/yaml

start: 300

# response 200 - untouched
```

## Destroy Sequence

You can drop the sequence with `DELETE /PGSequence/[id]`

```yaml
DELETE /PGSequence/pt_seq
Accept: text/yaml

# response 200
id: pt_seq
value: 1
```