django-sequences
################
By default, Django gives each model an auto-incrementing integer primary key.
These primary keys look like they generate a continuous sequence of integers.
However, this behavior isn't guaranteed.
If a transaction inserts a row and then is rolled back, the sequence counter
isn't rolled back for performance reasons, creating a gap in primary keys.
Such gaps may happen on all databases natively supported by Django:
* `PostgreSQL <https://www.postgresql.org/docs/current/datatype-numeric.html#DATATYPE-SERIAL>`_
* `MariaDB <https://mariadb.com/kb/en/auto_increment/#missing-values>`_ / MySQL
* `Oracle <https://docs.oracle.com/en/database/oracle/oracle-database/21/sqlrf/CREATE-SEQUENCE.html>`_
* `SQLite <https://sqlite.org/autoinc.html#the_autoincrement_keyword>`_
They may also happen on most databases supported via third-party backends.
This can cause compliance issues for some use cases such as accounting.
This risk isn't well known. Since most transactions succeed, values look
sequential. Gaps will only be revealed by audits.
django-sequences solves this problem with a ``get_next_value`` function
designed to be used as follows:
.. code:: python
from django.db import transaction
from sequences import get_next_value
from invoices.models import Invoice
with transaction.atomic():
Invoice.objects.create(number=get_next_value("invoice_numbers"))
Or, if you'd rather use an object-oriented API:
.. code:: python
from django.db import transaction
from sequences import Sequence
from invoices.models import Invoice
invoice_numbers = Sequence("invoice_numbers")
with transaction.atomic():
Invoice.objects.create(number=next(invoice_numbers))
``get_next_value`` relies on the database's transactional integrity to ensure
that each value is returned exactly once. As a consequence, **the guarantees
of django-sequences apply only if you call** ``get_next_value`` **and save its
return value to the database within the same transaction!**
Table of contents
=================
* `Getting started`_
* `API`_
* `Database support`_
* `Multiple databases`_
* `Isolation levels`_
* `Contributing`_
* `Releasing`_
* `Changelog`_
Getting started
===============
django-sequences is tested with Django Django 3.2 (LTS), 4.0, 4.1, 4.2 (LTS),
and 5.0.
It is also tested with all database backends built-in to Django: MySQL/MariaDB,
Oracle, PostgreSQL and SQLite.
It is released under the BSD license, like Django itself.
Install django-sequences:
.. code:: shell-session
$ pip install django-sequences
Add it to the list of applications in your project's settings:
.. code:: python
INSTALLED_APPS = [
...,
"sequences.apps.SequencesConfig",
...
]
Run migrations:
.. code:: shell-session
$ django-admin migrate
API
===
``get_next_value``
------------------
.. code:: pycon
>>> from sequences import get_next_value
This function generates a gapless sequence of integer values:
.. code:: pycon
>>> get_next_value()
1
>>> get_next_value()
2
>>> get_next_value()
3
It supports multiple independent sequences:
.. code:: pycon
>>> get_next_value("cases")
1
>>> get_next_value("cases")
2
>>> get_next_value("invoices")
1
>>> get_next_value("invoices")
2
The first value defaults to 1. It can be customized:
.. code:: pycon
>>> get_next_value("customers", initial_value=1000) # pro growth hacking
The ``initial_value`` parameter only matters when ``get_next_value`` is called
for the first time for a given sequence — assuming the corresponding database
transaction gets committed; as discussed above, if the transaction is rolled
back, the generated value isn't consumed. It's also possible to initialize a
sequence in a data migration and not use ``initial_value`` in actual code.
Sequences can loop:
.. code:: pycon
>>> get_next_value("seconds", initial_value=0, reset_value=60)
When the sequence reaches ``reset_value``, it restarts at ``initial_value``.
In other words, it generates ``reset_value - 2``, ``reset_value - 1``,
``initial_value``, ``initial_value + 1``, etc. In that case, each call to
``get_next_value`` must provide ``initial_value`` when it isn't the default
and ``reset_value``.
**Database transactions that call** ``get_next_value`` **for a given sequence
are serialized.** As a consequence, when you call ``get_next_value`` in a
database transaction, other callers trying to get a value from the same
sequence block until the transaction completes, either with a commit or a
rollback. You should keep such transactions short to minimize the impact on
performance.
This is why databases default to a faster behavior that may create gaps.
Passing ``nowait=True`` makes ``get_next_value`` raise an exception instead of
blocking in this scenario. This is rarely useful. Also it doesn't work for the
first call. (This is a bug but it's harmless and hard to fix.)
Calls to ``get_next_value`` for distinct sequences don't interact with one
another.
Finally, passing ``using="..."`` allows selecting the database on which the
current sequence value is stored. When this parameter isn't provided, it
defaults to the default database for writing models of the ``sequences``
application. See `Multiple databases`_ for details.
To sum up, the complete signature of ``get_next_value`` is:
.. code:: python
get_next_value(
sequence_name="default",
initial_value=1,
reset_value=None,
*,
nowait=False,
using=None,
)
``get_next_values``
-------------------
.. code:: pycon
>>> from sequences import get_next_values
This function generates values in batch:
.. code:: pycon
>>> get_next_values(10)
range(1, 11)
>>> get_next_values(10)
range(11, 21)
As a reminder, you must save all these values to the database within the same
transaction to benefit from the guarantees of django-sequences.
``get_next_values`` supports the same arguments as ``get_next_value`` except
``reset_value``.
The complete signature of ``get_next_values`` is:
.. code:: python
get_next_values(
batch_size,
sequence_name="default",
initial_value=1,
*,
nowait=False,
using=None,
)
``get_last_value``
------------------
.. code:: pycon
>>> from sequences import get_last_value
This function returns the last value generated by a sequence:
.. code:: pycon
>>> get_last_value()
None
>>> get_next_value()
1
>>> get_last_value()
1
>>> get_next_value()
2
>>> get_last_value()
2
If the sequence hasn't generated a value yet, ``get_last_value`` returns
``None``.
It supports independent sequences like ``get_next_value``:
.. code:: pycon
>>> get_next_value("cases")
1
>>> get_last_value("cases")
1
>>> get_next_value("invoices")
1
>>> get_last_value("invoices")
1
It accepts ``using="..."`` for selecting the database on which the current
sequence value is stored, defaulting to the default database for reading
models of the ``sequences`` application.
The complete signature of ``get_last_value`` is:
.. code:: python
get_last_value(
sequence_name="default",
*,
using=None,
)
``get_last_value`` **is a convenient and fast way to tell how many values a
sequence generated but it makes no guarantees.** Concurrent calls to
``get_next_value`` may produce unexpected results of ``get_last_value``.
``delete``
----------
.. code:: pycon
>>> from sequences import delete
This function deletes a sequence. It returns ``True`` if the sequence existed
and was deleted and ``False`` otherwise.
.. code:: pycon
>>> company_id = "b1f6cdef-367f-49e4-9cf5-bb0d34707af8"
>>> get_next_value(f"invoices—{company_id}")
1
>>> delete(f"invoices—{company_id}")
True
>>> delete(f"invoices—{company_id}")
False
It accepts ``using="..."`` for selecting the database, like ``get_next_value``.
The complete signature of ``delete`` is:
.. code:: python
delete(
sequence_name="default",
*,
using=None,
)
``delete`` is useful when you create many sequences and want to dispose of some.
``Sequence``
------------
.. code:: pycon
>>> from sequences import Sequence
(not to be confused with ``sequences.models.Sequence``, a private API)
This class stores parameters for a sequence and provides ``get_next_value``,
``get_next_values``, ``get_last_value``, and ``delete`` methods:
.. code:: pycon
>>> claim_ids = Sequence("claims")
>>> claim_ids.get_next_value()
1
>>> claim_ids.get_next_value()
2
>>> claim_ids.get_last_value()
2
>>> claim_ids.delete()
True
This reduces the risk of errors when the same sequence is used in multiple
places.
Instances of ``Sequence`` are also infinite iterators:
.. code:: pycon
>>> next(claim_ids)
3
>>> next(claim_ids)
4
The complete API is:
.. code:: python
Sequence(
sequence_name="default",
initial_value=1,
reset_value=None,
*,
using=None,
)
Sequence.get_next_value(
self,
*,
nowait=False,
)
Sequence.get_next_values(
self,
batch_size,
*,
nowait=False,
)
Sequence.get_last_value(
self,
)
Sequence.delete(
self,
)
All parameters have the same meaning as in the ``get_next_value``,
``get_last_values``, ``get_last_value``, and ``delete`` functions.
Examples
========
Per-date sequences
------------------
If you want independent sequences per day, month, or year, use the appropriate
date fragment in the sequence name. For example:
.. code:: python
from django.utils import timezone
from sequences import get_next_value
# Per-day sequence
get_next_value(f"books-{timezone.now().date().isoformat()}")
# Per-year sequence
get_next_value(f"prototocol-{timezone.now().year}")
The above calls will result in separate sequences like ``books-2023-03-15``
or ``protocol-2024``, respectively.
Database support
================
django-sequences is tested on PostgreSQL, MariaDB / MySQL, Oracle, and SQLite.
MySQL only supports the ``nowait`` parameter from version 8.0.1.
MariaDB only supports ``nowait`` from version 10.3.
Multiple databases
==================
Since django-sequences relies on the database to guarantee transactional
integrity, the current value for a given sequence must be stored in the same
database as models containing generated values.
In a project that uses multiple databases, you must write a suitable database
router to create tables for the ``sequences`` application on all databases
storing models containing sequential numbers.
Each database has its own namespace: a sequence with the same name stored in
two databases will have independent counters in each database.
Isolation levels
================
Since django-sequences relies on the database's transactional integrity, using
a non-default transaction isolation level requires special care.
* **read uncommitted:** django-sequences cannot work at this isolation level.
Indeed, concurrent transactions can create gaps, as in this scenario:
* Transaction A reads N and writes N + 1;
* Transaction B reads N + 1 (dirty read) and writes N + 2;
* Transaction A is rolled back;
* Transaction B is committed;
* N + 1 is a gap.
The read uncommitted isolation level doesn't provide sufficient guarantees.
It will never be supported.
* **read committed:** django-sequences works best at this isolation level,
like Django itself.
* **repeatable read:** django-sequences also works at this isolation level,
provided your code handles serialization failures and retries transactions.
This requirement isn't specific to django-sequences. It's generally needed
when running at the repeatable read isolation level.
Here's a scenario where only one of two concurrent transactions can
complete on PostgreSQL:
* Transaction A reads N and writes N + 1;
* Transaction B attemps to read; it must wait until transaction A completes;
* Transaction A is committed;
* Transaction B is aborted.
On PostgreSQL, serialization failures are reported as: ``OperationalError:
could not serialize access due to concurrent update``.
On MySQL, they result in: ``OperationalError: (1213, 'Deadlock found when
trying to get lock; try restarting transaction')``.
Concurrent transactions initializing the same sequence are also vulnerable,
although that's hardly ever a problem in practice.
On PostgreSQL, this manifests as ``IntegrityError: duplicate key value
violates unique constraint "sequences_sequence_pkey"``.
* **serializable:** the situation is identical to the repeatable read level.
SQLite always runs at the serializable isolation level. Serialization
failures result in: ``OperationalError: database is locked``.
Contributing
============
Prepare a development environment:
* Install Poetry_.
* Run ``poetry install``.
* Run ``poetry shell`` to load the development environment.
Prepare testing databases:
* Install PostgreSQL, MariaDB, and Oracle.
* Create a database called ``sequences``, owned by a user called ``sequences``
with password ``sequences``, with permissions to create a ``test_sequences``
test database. You may override these values with environment variables; see
``tests/*_settings.py`` for details.
Make changes:
* Make changes to the code, tests, or docs.
* Run ``make style`` and fix errors.
* Run ``make test`` to run the set suite on all databases.
Iterate until you're happy.
Check quality and submit your changes:
* Install tox_.
* Run ``tox`` to test on all Python and Django versions and all databases.
* Submit a pull request.
.. _Poetry: https://python-poetry.org/
.. _tox: https://tox.readthedocs.io/
Releasing
=========
Increment version number X.Y in ``pyproject.toml``.
Commit, tag, and push the change:
.. code:: shell-session
$ git commit -m "Bump version number".
$ git tag X.Y
$ git push
$ git push --tags
Build and publish the new version:
.. code:: shell-session
$ poetry build
$ poetry publish
Changelog
=========
3.0
---
* Add the ``get_next_values`` function for generating values in batch.
2.9
---
* Add the ``delete`` function.
2.8
---
* No significant changes.
2.7
---
* Sequence values can go up to ``2 ** 63 - 1`` instead of ``2 ** 31 - 1``
previously. The exact limit depends on the database backend.
Migration ``0002_alter_sequence_last.py`` changes the field storing sequence
values from ``PositiveIntegerField`` to ``PositiveBigIntegerField``. Running
it requires an exclusive lock on the table, which prevents other operations,
including reads.
If you have many distinct sequences, e.g. if you create one sequence per user
and you have millions of users, review how the migration will affect your app
before running it or skip it with ``migrate --fake``.
2.6
---
* Improve documentation.
2.5
---
* Fix Japanese and Turkish translations.
* Restore compatibility with Python 3.5.
* Support relabeling the ``sequences`` app with a custom ``AppConfig``.
2.4
---
* Add the ``get_last_value`` function.
* Add the ``Sequence`` class.
2.3
---
* Optimize performance on MySQL.
* Test on MySQL, SQLite and Oracle.
2.2
---
* Optimize performance on PostgreSQL ≥ 9.5.
2.1
---
* Provide looping sequences with ``reset_value``.
2.0
---
* Add support for multiple databases.
* Add translations.
* ``nowait`` becomes keyword-only argument.
* Drop support for Python 2.
1.0
---
* Initial stable release.
Raw data
{
"_id": null,
"home_page": "https://github.com/aaugustin/django-sequences",
"name": "django-sequences",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "",
"author": "Aymeric Augustin",
"author_email": "aymeric.augustin@m4x.org",
"download_url": "https://files.pythonhosted.org/packages/b4/57/18664e9506198262ac854e677118653c7b69dabeaa77fef11eb6bad15781/django_sequences-3.0.tar.gz",
"platform": null,
"description": "django-sequences\n################\n\nBy default, Django gives each model an auto-incrementing integer primary key.\nThese primary keys look like they generate a continuous sequence of integers.\n\nHowever, this behavior isn't guaranteed.\n\nIf a transaction inserts a row and then is rolled back, the sequence counter\nisn't rolled back for performance reasons, creating a gap in primary keys.\n\nSuch gaps may happen on all databases natively supported by Django:\n\n* `PostgreSQL <https://www.postgresql.org/docs/current/datatype-numeric.html#DATATYPE-SERIAL>`_\n* `MariaDB <https://mariadb.com/kb/en/auto_increment/#missing-values>`_ / MySQL\n* `Oracle <https://docs.oracle.com/en/database/oracle/oracle-database/21/sqlrf/CREATE-SEQUENCE.html>`_\n* `SQLite <https://sqlite.org/autoinc.html#the_autoincrement_keyword>`_\n\nThey may also happen on most databases supported via third-party backends.\n\nThis can cause compliance issues for some use cases such as accounting.\n\nThis risk isn't well known. Since most transactions succeed, values look\nsequential. Gaps will only be revealed by audits.\n\ndjango-sequences solves this problem with a ``get_next_value`` function\ndesigned to be used as follows:\n\n.. code:: python\n\n from django.db import transaction\n from sequences import get_next_value\n from invoices.models import Invoice\n\n with transaction.atomic():\n Invoice.objects.create(number=get_next_value(\"invoice_numbers\"))\n\nOr, if you'd rather use an object-oriented API:\n\n.. code:: python\n\n from django.db import transaction\n from sequences import Sequence\n from invoices.models import Invoice\n\n invoice_numbers = Sequence(\"invoice_numbers\")\n\n with transaction.atomic():\n Invoice.objects.create(number=next(invoice_numbers))\n\n``get_next_value`` relies on the database's transactional integrity to ensure\nthat each value is returned exactly once. As a consequence, **the guarantees\nof django-sequences apply only if you call** ``get_next_value`` **and save its\nreturn value to the database within the same transaction!**\n\nTable of contents\n=================\n\n* `Getting started`_\n* `API`_\n* `Database support`_\n* `Multiple databases`_\n* `Isolation levels`_\n* `Contributing`_\n* `Releasing`_\n* `Changelog`_\n\nGetting started\n===============\n\ndjango-sequences is tested with Django Django 3.2 (LTS), 4.0, 4.1, 4.2 (LTS),\nand 5.0.\n\nIt is also tested with all database backends built-in to Django: MySQL/MariaDB,\nOracle, PostgreSQL and SQLite.\n\nIt is released under the BSD license, like Django itself.\n\nInstall django-sequences:\n\n.. code:: shell-session\n\n $ pip install django-sequences\n\nAdd it to the list of applications in your project's settings:\n\n.. code:: python\n\n INSTALLED_APPS = [\n ...,\n \"sequences.apps.SequencesConfig\",\n ...\n ]\n\nRun migrations:\n\n.. code:: shell-session\n\n $ django-admin migrate\n\nAPI\n===\n\n``get_next_value``\n------------------\n\n.. code:: pycon\n\n >>> from sequences import get_next_value\n\nThis function generates a gapless sequence of integer values:\n\n.. code:: pycon\n\n >>> get_next_value()\n 1\n >>> get_next_value()\n 2\n >>> get_next_value()\n 3\n\nIt supports multiple independent sequences:\n\n.. code:: pycon\n\n >>> get_next_value(\"cases\")\n 1\n >>> get_next_value(\"cases\")\n 2\n >>> get_next_value(\"invoices\")\n 1\n >>> get_next_value(\"invoices\")\n 2\n\nThe first value defaults to 1. It can be customized:\n\n.. code:: pycon\n\n >>> get_next_value(\"customers\", initial_value=1000) # pro growth hacking\n\nThe ``initial_value`` parameter only matters when ``get_next_value`` is called\nfor the first time for a given sequence \u2014 assuming the corresponding database\ntransaction gets committed; as discussed above, if the transaction is rolled\nback, the generated value isn't consumed. It's also possible to initialize a\nsequence in a data migration and not use ``initial_value`` in actual code.\n\nSequences can loop:\n\n.. code:: pycon\n\n >>> get_next_value(\"seconds\", initial_value=0, reset_value=60)\n\nWhen the sequence reaches ``reset_value``, it restarts at ``initial_value``.\nIn other words, it generates ``reset_value - 2``, ``reset_value - 1``,\n``initial_value``, ``initial_value + 1``, etc. In that case, each call to\n``get_next_value`` must provide ``initial_value`` when it isn't the default\nand ``reset_value``.\n\n**Database transactions that call** ``get_next_value`` **for a given sequence\nare serialized.** As a consequence, when you call ``get_next_value`` in a\ndatabase transaction, other callers trying to get a value from the same\nsequence block until the transaction completes, either with a commit or a\nrollback. You should keep such transactions short to minimize the impact on\nperformance.\n\nThis is why databases default to a faster behavior that may create gaps.\n\nPassing ``nowait=True`` makes ``get_next_value`` raise an exception instead of\nblocking in this scenario. This is rarely useful. Also it doesn't work for the\nfirst call. (This is a bug but it's harmless and hard to fix.)\n\nCalls to ``get_next_value`` for distinct sequences don't interact with one\nanother.\n\nFinally, passing ``using=\"...\"`` allows selecting the database on which the\ncurrent sequence value is stored. When this parameter isn't provided, it\ndefaults to the default database for writing models of the ``sequences``\napplication. See `Multiple databases`_ for details.\n\nTo sum up, the complete signature of ``get_next_value`` is:\n\n.. code:: python\n\n get_next_value(\n sequence_name=\"default\",\n initial_value=1,\n reset_value=None,\n *,\n nowait=False,\n using=None,\n )\n\n``get_next_values``\n-------------------\n\n.. code:: pycon\n\n >>> from sequences import get_next_values\n\nThis function generates values in batch:\n\n.. code:: pycon\n\n >>> get_next_values(10)\n range(1, 11)\n >>> get_next_values(10)\n range(11, 21)\n\nAs a reminder, you must save all these values to the database within the same\ntransaction to benefit from the guarantees of django-sequences.\n\n``get_next_values`` supports the same arguments as ``get_next_value`` except\n``reset_value``.\n\nThe complete signature of ``get_next_values`` is:\n\n.. code:: python\n\n get_next_values(\n batch_size,\n sequence_name=\"default\",\n initial_value=1,\n *,\n nowait=False,\n using=None,\n )\n\n\n``get_last_value``\n------------------\n\n.. code:: pycon\n\n >>> from sequences import get_last_value\n\nThis function returns the last value generated by a sequence:\n\n.. code:: pycon\n\n >>> get_last_value()\n None\n >>> get_next_value()\n 1\n >>> get_last_value()\n 1\n >>> get_next_value()\n 2\n >>> get_last_value()\n 2\n\nIf the sequence hasn't generated a value yet, ``get_last_value`` returns\n``None``.\n\nIt supports independent sequences like ``get_next_value``:\n\n.. code:: pycon\n\n >>> get_next_value(\"cases\")\n 1\n >>> get_last_value(\"cases\")\n 1\n >>> get_next_value(\"invoices\")\n 1\n >>> get_last_value(\"invoices\")\n 1\n\nIt accepts ``using=\"...\"`` for selecting the database on which the current\nsequence value is stored, defaulting to the default database for reading\nmodels of the ``sequences`` application.\n\nThe complete signature of ``get_last_value`` is:\n\n.. code:: python\n\n get_last_value(\n sequence_name=\"default\",\n *,\n using=None,\n )\n\n``get_last_value`` **is a convenient and fast way to tell how many values a\nsequence generated but it makes no guarantees.** Concurrent calls to\n``get_next_value`` may produce unexpected results of ``get_last_value``.\n\n``delete``\n----------\n\n.. code:: pycon\n\n >>> from sequences import delete\n\nThis function deletes a sequence. It returns ``True`` if the sequence existed\nand was deleted and ``False`` otherwise.\n\n.. code:: pycon\n\n >>> company_id = \"b1f6cdef-367f-49e4-9cf5-bb0d34707af8\"\n >>> get_next_value(f\"invoices\u2014{company_id}\")\n 1\n >>> delete(f\"invoices\u2014{company_id}\")\n True\n >>> delete(f\"invoices\u2014{company_id}\")\n False\n\nIt accepts ``using=\"...\"`` for selecting the database, like ``get_next_value``.\n\nThe complete signature of ``delete`` is:\n\n.. code:: python\n\n delete(\n sequence_name=\"default\",\n *,\n using=None,\n )\n\n``delete`` is useful when you create many sequences and want to dispose of some.\n\n``Sequence``\n------------\n\n.. code:: pycon\n\n >>> from sequences import Sequence\n\n(not to be confused with ``sequences.models.Sequence``, a private API)\n\nThis class stores parameters for a sequence and provides ``get_next_value``,\n``get_next_values``, ``get_last_value``, and ``delete`` methods:\n\n.. code:: pycon\n\n >>> claim_ids = Sequence(\"claims\")\n >>> claim_ids.get_next_value()\n 1\n >>> claim_ids.get_next_value()\n 2\n >>> claim_ids.get_last_value()\n 2\n >>> claim_ids.delete()\n True\n\nThis reduces the risk of errors when the same sequence is used in multiple\nplaces.\n\nInstances of ``Sequence`` are also infinite iterators:\n\n.. code:: pycon\n\n >>> next(claim_ids)\n 3\n >>> next(claim_ids)\n 4\n\nThe complete API is:\n\n.. code:: python\n\n Sequence(\n sequence_name=\"default\",\n initial_value=1,\n reset_value=None,\n *,\n using=None,\n )\n\n Sequence.get_next_value(\n self,\n *,\n nowait=False,\n )\n\n Sequence.get_next_values(\n self,\n batch_size,\n *,\n nowait=False,\n )\n\n Sequence.get_last_value(\n self,\n )\n\n Sequence.delete(\n self,\n )\n\nAll parameters have the same meaning as in the ``get_next_value``,\n``get_last_values``, ``get_last_value``, and ``delete`` functions.\n\nExamples\n========\n\nPer-date sequences\n------------------\n\nIf you want independent sequences per day, month, or year, use the appropriate\ndate fragment in the sequence name. For example:\n\n.. code:: python\n\n from django.utils import timezone\n from sequences import get_next_value\n\n # Per-day sequence\n get_next_value(f\"books-{timezone.now().date().isoformat()}\")\n # Per-year sequence\n get_next_value(f\"prototocol-{timezone.now().year}\")\n\nThe above calls will result in separate sequences like ``books-2023-03-15``\nor ``protocol-2024``, respectively.\n\nDatabase support\n================\n\ndjango-sequences is tested on PostgreSQL, MariaDB / MySQL, Oracle, and SQLite.\n\nMySQL only supports the ``nowait`` parameter from version 8.0.1.\nMariaDB only supports ``nowait`` from version 10.3.\n\nMultiple databases\n==================\n\nSince django-sequences relies on the database to guarantee transactional\nintegrity, the current value for a given sequence must be stored in the same\ndatabase as models containing generated values.\n\nIn a project that uses multiple databases, you must write a suitable database\nrouter to create tables for the ``sequences`` application on all databases\nstoring models containing sequential numbers.\n\nEach database has its own namespace: a sequence with the same name stored in\ntwo databases will have independent counters in each database.\n\nIsolation levels\n================\n\nSince django-sequences relies on the database's transactional integrity, using\na non-default transaction isolation level requires special care.\n\n* **read uncommitted:** django-sequences cannot work at this isolation level.\n\n Indeed, concurrent transactions can create gaps, as in this scenario:\n\n * Transaction A reads N and writes N + 1;\n * Transaction B reads N + 1 (dirty read) and writes N + 2;\n * Transaction A is rolled back;\n * Transaction B is committed;\n * N + 1 is a gap.\n\n The read uncommitted isolation level doesn't provide sufficient guarantees.\n It will never be supported.\n\n* **read committed:** django-sequences works best at this isolation level,\n like Django itself.\n\n* **repeatable read:** django-sequences also works at this isolation level,\n provided your code handles serialization failures and retries transactions.\n\n This requirement isn't specific to django-sequences. It's generally needed\n when running at the repeatable read isolation level.\n\n Here's a scenario where only one of two concurrent transactions can\n complete on PostgreSQL:\n\n * Transaction A reads N and writes N + 1;\n * Transaction B attemps to read; it must wait until transaction A completes;\n * Transaction A is committed;\n * Transaction B is aborted.\n\n On PostgreSQL, serialization failures are reported as: ``OperationalError:\n could not serialize access due to concurrent update``.\n\n On MySQL, they result in: ``OperationalError: (1213, 'Deadlock found when\n trying to get lock; try restarting transaction')``.\n\n Concurrent transactions initializing the same sequence are also vulnerable,\n although that's hardly ever a problem in practice.\n\n On PostgreSQL, this manifests as ``IntegrityError: duplicate key value\n violates unique constraint \"sequences_sequence_pkey\"``.\n\n* **serializable:** the situation is identical to the repeatable read level.\n\n SQLite always runs at the serializable isolation level. Serialization\n failures result in: ``OperationalError: database is locked``.\n\nContributing\n============\n\nPrepare a development environment:\n\n* Install Poetry_.\n* Run ``poetry install``.\n* Run ``poetry shell`` to load the development environment.\n\nPrepare testing databases:\n\n* Install PostgreSQL, MariaDB, and Oracle.\n* Create a database called ``sequences``, owned by a user called ``sequences``\n with password ``sequences``, with permissions to create a ``test_sequences``\n test database. You may override these values with environment variables; see\n ``tests/*_settings.py`` for details.\n\nMake changes:\n\n* Make changes to the code, tests, or docs.\n* Run ``make style`` and fix errors.\n* Run ``make test`` to run the set suite on all databases.\n\nIterate until you're happy.\n\nCheck quality and submit your changes:\n\n* Install tox_.\n* Run ``tox`` to test on all Python and Django versions and all databases.\n* Submit a pull request.\n\n.. _Poetry: https://python-poetry.org/\n.. _tox: https://tox.readthedocs.io/\n\nReleasing\n=========\n\nIncrement version number X.Y in ``pyproject.toml``.\n\nCommit, tag, and push the change:\n\n.. code:: shell-session\n\n $ git commit -m \"Bump version number\".\n $ git tag X.Y\n $ git push\n $ git push --tags\n\nBuild and publish the new version:\n\n.. code:: shell-session\n\n $ poetry build\n $ poetry publish\n\nChangelog\n=========\n\n3.0\n---\n\n* Add the ``get_next_values`` function for generating values in batch.\n\n2.9\n---\n\n* Add the ``delete`` function.\n\n2.8\n---\n\n* No significant changes.\n\n2.7\n---\n\n* Sequence values can go up to ``2 ** 63 - 1`` instead of ``2 ** 31 - 1``\n previously. The exact limit depends on the database backend.\n\n Migration ``0002_alter_sequence_last.py`` changes the field storing sequence\n values from ``PositiveIntegerField`` to ``PositiveBigIntegerField``. Running\n it requires an exclusive lock on the table, which prevents other operations,\n including reads.\n\n If you have many distinct sequences, e.g. if you create one sequence per user\n and you have millions of users, review how the migration will affect your app\n before running it or skip it with ``migrate --fake``.\n\n2.6\n---\n\n* Improve documentation.\n\n2.5\n---\n\n* Fix Japanese and Turkish translations.\n* Restore compatibility with Python 3.5.\n* Support relabeling the ``sequences`` app with a custom ``AppConfig``.\n\n2.4\n---\n\n* Add the ``get_last_value`` function.\n* Add the ``Sequence`` class.\n\n2.3\n---\n\n* Optimize performance on MySQL.\n* Test on MySQL, SQLite and Oracle.\n\n2.2\n---\n\n* Optimize performance on PostgreSQL \u2265 9.5.\n\n2.1\n---\n\n* Provide looping sequences with ``reset_value``.\n\n2.0\n---\n\n* Add support for multiple databases.\n* Add translations.\n* ``nowait`` becomes keyword-only argument.\n* Drop support for Python 2.\n\n1.0\n---\n\n* Initial stable release.\n",
"bugtrack_url": null,
"license": "BSD-3-Clause",
"summary": "Generate gapless sequences of integer values.",
"version": "3.0",
"project_urls": {
"Homepage": "https://github.com/aaugustin/django-sequences",
"Repository": "https://github.com/aaugustin/django-sequences"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "33cfd18a396dec56959a1e6e2f67ea3a0437a134bc4adb7e8a08faae17c50bea",
"md5": "a4b177633b57ccf0fb7edeb0c10cd8ab",
"sha256": "e2dc2c3615f01e15d51c155ad38df8f56cbe61ec20b82f250b4ea35a277af614"
},
"downloads": -1,
"filename": "django_sequences-3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a4b177633b57ccf0fb7edeb0c10cd8ab",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 29790,
"upload_time": "2024-01-31T21:07:22",
"upload_time_iso_8601": "2024-01-31T21:07:22.255077Z",
"url": "https://files.pythonhosted.org/packages/33/cf/d18a396dec56959a1e6e2f67ea3a0437a134bc4adb7e8a08faae17c50bea/django_sequences-3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b45718664e9506198262ac854e677118653c7b69dabeaa77fef11eb6bad15781",
"md5": "f08b65de7e013a51f0c82e23875c26e9",
"sha256": "e82bfee28d9eaee5b7d3be618eed989c7c5a117601b56142ee2435edb5a45456"
},
"downloads": -1,
"filename": "django_sequences-3.0.tar.gz",
"has_sig": false,
"md5_digest": "f08b65de7e013a51f0c82e23875c26e9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 18404,
"upload_time": "2024-01-31T21:07:24",
"upload_time_iso_8601": "2024-01-31T21:07:24.528608Z",
"url": "https://files.pythonhosted.org/packages/b4/57/18664e9506198262ac854e677118653c7b69dabeaa77fef11eb6bad15781/django_sequences-3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-31 21:07:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "aaugustin",
"github_project": "django-sequences",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"tox": true,
"lcname": "django-sequences"
}
JSON
