peewee Documentation

# Sqlite database using WAL-mode and 64MB page-cache.
  db = SqliteDatabase('app.db', pragmas={
      'journal_mode': 'wal',
      'cache_size': -64000})

  # Postgresql database on remote host.
  db = PostgresqlDatabase(
      'my_app',
      user='postgres',
      host='10.8.0.3',
      password='secret')

db = PostgresqlDatabase(None)

  class BaseModel(Model):
      class Meta:
          database = db

  # Read database connection info from env, for example:
  db_name = os.environ['DATABASE']
  db_host = os.environ['PGHOST']

  # Initialize database.
  db.init(db_name, host=db_host, user='postgres')

String used as parameter placeholder in SQL queries. Default is ``'?'``.

Type of quotation-mark(s) to use to denote entities such as tables or
  columns, specified as ``'<open quote><close quote>'``. Default is ``'""'``.

Whether the database supports sequences. ``False`` by default,
  ``True`` for Postgres.

Property which returns a base :class:`Model` class bound to this
  database, created on first access. Subclassing ``db.Model`` removes
  the need to declare ``Meta.database`` on each model:

  .. code-block:: python

     db = SqliteDatabase('app.db')

     class User(db.Model):
         username = TextField()

:param str database: Database name or filename for SQLite.
  :param kwargs: Arbitrary keyword arguments that will be passed to the
      database driver when a connection is created, for example
      ``password``, ``host``, etc.

  Initialize a *deferred* database. See :ref:`initializing-database`
  for more info.

:param bool reuse_if_open: Do not raise an exception if a connection is
      already opened.
  :return: whether a new connection was opened.
  :rtype: bool
  :raises: ``OperationalError`` if connection already open and
      ``reuse_if_open`` is not set to ``True``.

  Open a connection to the database.

  .. code-block:: python

     db.connect()

     # Or:
     db.connect(reuse_if_open=True)

:return: Whether the connection was closed. If the database was already
      closed, this returns ``False``.
  :rtype: bool

  Close the connection to the database.

  .. code-block:: python

     if not db.is_closed():
         db.close()

:return: return ``True`` if database is closed, ``False`` if open.
  :rtype: bool

Return the DB-API driver connection. If a connection is not open, one
  will be opened.

  .. code-block:: python

     db = SqliteDatabase(':memory:')

     # Get the sqlite3.Connection() instance.
     conn = db.connection()

The database object can be used as a context manager or decorator.

  1. Connection opens when context manager / decorated function is entered.
  2. Peewee begins a transaction.
  3. Control is passed to user for duration of block.
  4. Peewee commits transaction if block exits cleanly, otherwise issues a
     rollback.
  5. Peewee closes the connection.
  6. Any unhandled exception is raised.

  .. code-block:: python

     with db:
         User.create(username='charlie')
         # Transaction is committed when the block exits normally,
         # rolled back if an exception is raised.

  Decorator:

  .. code-block:: python

     @db
     def demo():
         print('closed?', db.is_closed())

     demo()  # "closed? False"
     db.is_closed()  # True

Create a context-manager or decorator that will hold open a connection
  for the duration of the wrapped block.

  Example:

  .. code-block:: python

     with db.connection_context():
         # Connection is open, no implicit transaction.
         results = User.select()

  Decorator:

  .. code-block:: python

     @db.connection_context()
     def load_fixtures():
         db.create_tables([User, Tweet])
         import_data()

:param named_cursor: Reserved for internal use by Postgres extension.

  Return a DB-API ``cursor`` object on the current connection. If a
  connection is not open, one will be opened.

:param str sql: SQL string to execute.
  :param tuple params: Parameters for query.
  :return: cursor object.

  Execute a SQL query and return a cursor over the results.

  .. code-block:: python

     db = SqliteDatabase('my_app.db')
     db.connect()

     # Example of executing a simple query and ignoring the results.
     db.execute_sql("ATTACH DATABASE ':memory:' AS cache;")

     # Example of iterating over the results of a query using the cursor.
     cursor = db.execute_sql('SELECT * FROM users WHERE status = ?', (ACTIVE,))
     for row in cursor.fetchall():
         # Do something with row, which is a tuple containing column data.
         pass

:param query: A :class:`Query` instance.
  :param context_options: Arbitrary options to pass to the SQL generator.
  :return: cursor object.

  Execute a SQL query by compiling a ``Query`` instance and executing the
  resulting SQL.

  .. code-block:: python

     query = User.insert({'username': 'Alice'})
     db.execute(query)  # Equivalent to query.execute()

:param cursor: cursor object.
  :return: primary key of last-inserted row.

:param cursor: cursor object.
  :return: number of rows modified by query.

Create a context-manager or decorator which wraps a block of code in a
  transaction (or savepoint).

  Calls to :meth:`~Database.atomic` can be nested.

  Database-specific parameters:

  :class:`PostgresqlDatabase` and :class:`MySQLDatabase` accept an
  ``isolation_level`` parameter. :class:`SqliteDatabase` accepts a
  ``lock_type`` parameter. Refer to :ref:`sqlite-locking` and :ref:`postgres-isolation`
  for discussion.

  :param str isolation_level: Isolation strategy: READ UNCOMMITTED, READ COMMITTED, REPEATABLE READ, SERIALIZABLE
  :param str lock_type: Locking strategy: DEFERRED, IMMEDIATE, EXCLUSIVE.

  Example code::

     with db.atomic() as txn:
         user = User.create(username='charlie')
         with db.atomic():
             tweet = Tweet.create(user=user, content='Hello')

     # Both rows are committed when block exits normally.

  As a decorator:

  .. code-block:: python

     @db.atomic()
     def create_user_with_tweet(username, content):
         user = User.create(username=username)
         Tweet.create(user=user, content=content)
         return user

  Transactions (and save-points) can be committed or rolled-back within the
  wrapped block. If this occurs, a new transaction or savepoint is begun:

  Example:

  .. code-block:: python

      with db.atomic() as txn:
          User.create(username='bob')
          txn.commit()  # Changes are saved and a new transaction begins.

          User.create(username='alice')
          txn.rollback()  # "alice" will not be saved.

          User.create(username='carol')

      # Print the usernames of all users.
      print([u.username for u in User.select()])

      # Prints ["bob", "carol"]

  If an unhandled exception occurs in the block, the block is rolled-back
  and the exception propagates.

Create a context-manager or decorator that runs all queries in the
  wrapped block in a transaction.

  Database-specific parameters:

  :class:`PostgresqlDatabase` and :class:`MySQLDatabase` accept an
  ``isolation_level`` parameter. :class:`SqliteDatabase` accepts a
  ``lock_type`` parameter. Refer to :ref:`sqlite-locking` and :ref:`postgres-isolation`
  for discussion.

  :param str isolation_level: Isolation strategy: READ UNCOMMITTED, READ COMMITTED, REPEATABLE READ, SERIALIZABLE
  :param str lock_type: Locking strategy: DEFERRED, IMMEDIATE, EXCLUSIVE.

  .. code-block:: python

     with db.transaction() as txn:
         User.create(username='bob')
         txn.commit()         # Commit now, a new transaction begins.
         User.create(username='alice')
         txn.rollback()       # Roll back alice, a new transaction begins.
         User.create(username='carol')
     # carol is committed when the block exits.

  Transactions can be committed or rolled-back within the wrapped block.
  If this occurs, a new transaction is begun.

  .. warning::
     If you attempt to nest transactions with peewee using the
     :meth:`~Database.transaction` context manager, only the outer-most
     transaction will be used.

     As this may lead to unpredictable behavior, it is recommended that
     you use :meth:`~Database.atomic`.

Create a context-manager or decorator that runs all queries in the
  wrapped block in a savepoint. Savepoints can be nested arbitrarily, but
  must occur within a transaction.

  .. code-block:: python

     with db.transaction() as txn:
         with db.savepoint() as sp:
             User.create(username='bob')

         with db.savepoint() as sp2:
             User.create(username='carol')
             sp2.rollback()  # "carol" is not saved.
             User.create(username='alice')

     # bob and alice were created.

  Savepoints can be committed or rolled-back within the wrapped block.
  If this occurs, a new savepoint is begun.

Create a context-manager or decorator which disables Peewee's transaction
  management for the wrapped block.

  Example:

  .. code-block:: python

     with db.manual_commit():
         db.begin()  # Begin transaction explicitly.
         try:
             user.delete_instance(recursive=True)
         except:
             db.rollback()  # Rollback -- an error occurred.
             raise
         else:
             try:
                 db.commit()  # Attempt to commit changes.
             except:
                 db.rollback()  # Error committing, rollback.
                 raise

  The above code is equivalent to the following:

  .. code-block:: python

     with db.atomic():
         user.delete_instance(recursive=True)

Begin a new transaction (without using a context-manager or decorator).
  This method is useful if you intend to execute a sequence of operations
  inside a transaction, but using a decorator or context-manager would
  not be appropriate.

  It is strongly advised that you use the :meth:`Database.atomic`
  method whenever possible for managing transactions/savepoints. The
  ``atomic`` method correctly manages nesting, uses the appropriate
  construction (e.g., transaction-vs-savepoint), and always cleans up
  after itself.

  The :meth:`~Database.session_start` method should only be used
  if the sequence of operations does not easily lend itself to
  wrapping using either a context-manager or decorator.

  You must *always* call either :meth:`~Database.session_commit`
  or :meth:`~Database.session_rollback` after calling the
  ``session_start`` method.

Commit any changes made during a transaction begun with
  :meth:`~Database.session_start`.

Roll back any changes made during a transaction begun with
  :meth:`~Database.session_start`.

Begin a transaction when using manual-commit mode.

  This method should only be used in conjunction with the
  :meth:`~Database.manual_commit` context manager.

Manually commit the currently-active transaction.

  This method should only be used in conjunction with the
  :meth:`~Database.manual_commit` context manager.

Manually roll-back the currently-active transaction.

  This method should only be used in conjunction with the
  :meth:`~Database.manual_commit` context manager.

:return: whether or not a transaction is currently open.
  :rtype: bool

  .. code-block:: python

     with db.atomic() as tx:
         assert db.in_transaction()

     assert not db.in_transaction()  # No longer in transaction.

:param iterable it: an iterable whose items will be yielded.
  :param int n: commit every *n* items.
  :return: an equivalent iterable to the one provided, with the addition
      that groups of *n* items will be yielded in a transaction.

  Simplify batching large operations, such as inserts, updates, etc. Pass
  in an iterable and the number of items-per-batch, and the items will be
  returned by an equivalent iterator that wraps each batch in a
  transaction.

  Example:

  .. code-block:: python

     # Some list or iterable containing data to insert.
     row_data = [{'username': 'u1'}, {'username': 'u2'}, ...]

     # Insert all data, committing every 100 rows. If, for example,
     # there are 789 items in the list, then there will be a total of
     # 8 transactions (7x100 and 1x89).
     for row in db.batch_commit(row_data, 100):
         user = User.create(**row)

         # Now let's suppose we need to do something w/the user.
         user.call_method()

  A more efficient option is to batch the data into a multi-value ``INSERT``
  statement (for example, using :meth:`Model.insert_many`). Use this
  approach instead wherever possible:

  .. code-block:: python

     with db.atomic():
         for idx in range(0, len(row_data), 100):
             # Insert 100 rows at a time.
             rows = row_data[idx:idx + 100]
             User.insert_many(rows).execute()

:param str table: Table name.
  :param str schema: Schema name (optional).
  :return: ``bool`` indicating whether table exists.

:param str schema: Schema name (optional).
  :return: a list of table names in the database.

:param str table: Table name.
  :param str schema: Schema name (optional).

  Return a list of :class:`IndexMetadata` tuples.

  Example:

  .. code-block:: python

     print(db.get_indexes('entry'))
     [IndexMetadata(
          name='entry_public_list',
          sql='CREATE INDEX "entry_public_list" ...',
          columns=['timestamp'],
          unique=False,
          table='entry'),
      IndexMetadata(
          name='entry_slug',
          sql='CREATE UNIQUE INDEX "entry_slug" ON "entry" ("slug")',
          columns=['slug'],
          unique=True,
          table='entry')]

:param str table: Table name.
  :param str schema: Schema name (optional).

  Return a list of :class:`ColumnMetadata` tuples.

  The ``full_type`` attribute carries the parameterized column type,
  e.g. ``character varying(50)``, where ``data_type`` retains the
  backend's bare type name. ``identity`` indicates auto-incrementing
  columns (serial / identity / auto_increment / sqlite rowid alias).

  Example:

  .. code-block:: python

     print(db.get_columns('entry'))
     [ColumnMetadata(
          name='id',
          data_type='INTEGER',
          null=False,
          primary_key=True,
          table='entry',
          default=None,
          full_type='INTEGER',
          identity=True),
      ColumnMetadata(
          name='title',
          data_type='TEXT',
          null=False,
          primary_key=False,
          table='entry',
          default=None,
          full_type='TEXT',
          identity=False),
      ...]

:param str table: Table name.
  :param str schema: Schema name (optional).

  Return a list of column names that comprise the primary key.

  Example:

  .. code-block:: python

     print(db.get_primary_keys('entry'))
     ['id']

:param str table: Table name.
  :param str schema: Schema name (optional).

  Return a list of :class:`ForeignKeyMetadata` tuples for keys present
  on the table.

  The ``name`` attribute is the constraint name (``None`` on SQLite). The
  ``on_delete`` and ``on_update`` are the referential actions, with
  undeclared actions reported as the backend's no-op default (``NO ACTION``
  or ``RESTRICT``).

  Example:

  .. code-block:: python

     print(db.get_foreign_keys('entrytag'))
     [ForeignKeyMetadata(
          column='entry_id',
          dest_table='entry',
          dest_column='id',
          table='entrytag',
          name='entrytag_entry_id_fkey',
          on_delete='NO ACTION',
          on_update='NO ACTION'),
      ...]

:param str schema: Schema name (optional).

  Return a list of :class:`ViewMetadata` tuples for VIEWs present in
  the database.

  Example:

  .. code-block:: python

     print(db.get_views())
     [ViewMetadata(
          name='entries_public',
          sql='CREATE VIEW entries_public AS SELECT ... '),
      ...]

:param str seq: Name of sequence.
  :return: Whether sequence exists.
  :rtype: bool

  .. code-block:: python

     if db.sequence_exists('user_id_seq'):
         print('Sequence found.')

:param list models: A list of :class:`Model` classes.
  :param options: Options to specify when calling
      :meth:`Model.create_table`.

  Create tables, indexes and associated constraints for the given list of
  models.

  Dependencies are resolved so that tables are created in the appropriate
  order.

:param list models: A list of :class:`Model` classes.
  :param kwargs: Options to specify when calling
      :meth:`Model.drop_table`.

  Drop tables, indexes and constraints for the given list of models.

  Dependencies are resolved so that tables are dropped in the appropriate
  order.

:param list models: One or more :class:`Model` classes to bind.
  :param bool bind_refs: Bind related models.
  :param bool bind_backrefs: Bind back-reference related models.

  Bind the given list of models, and specified relations, to the
  database.

  .. code-block:: python

     def setup_tests():
         # Bind models to an in-memory SQLite database.
         test_db = SqliteDatabase(':memory:')
         test_db.bind([User, Tweet])

:param list models: List of models to bind to the database.
   :param bool bind_refs: Bind models that are referenced using
       foreign-keys.
   :param bool bind_backrefs: Bind models that reference the given model
       with a foreign-key.

   Create a context-manager that binds (associates) the given models with
   the current database for the duration of the wrapped block.

   Example:

   .. code-block:: python

       MODELS = [User, Tweet, Favorite]

       # Bind the given models to the db for the duration of wrapped block.
       def use_test_database(fn):
           @wraps(fn)
           def inner(self):
               with test_db.bind_ctx(MODELS):
                   test_db.create_tables(MODELS)
                   try:
                       fn(self)
                   finally:
                       test_db.drop_tables(MODELS)
           return inner


       class TestSomething(TestCase):
           @use_test_database
           def test_something(self):
               # ... models are bound to test database ...
               pass

:param str date_part: date part to extract, e.g. 'year'.
  :param Node date_field: a SQL node containing a date/time, for example
      a :class:`DateTimeField`.
  :return: a SQL node representing a function call that will return the
      provided date part.

  Provides a compatible interface for extracting a portion of a datetime.

  Example:

  .. code-block:: python

     query = (Tweet.select()
              .where(db.extract_date('year', Tweet.timestamp) == 2026))

     # If Tweet.timestamp is a DateField or DateTimeField we could
     # also write:
     query = Tweet.select().where(Tweet.timestamp.year == 2026)

:param str date_part: date part to truncate to, e.g. 'day'.
  :param Node date_field: a SQL node containing a date/time, for example
      a :class:`DateTimeField`.
  :return: a SQL node representing a function call that will return the
      truncated date part.

  Provides a compatible interface for truncating a datetime to the given
  resolution.

  Example:

  .. code-block:: python

     # Report on how many tweets made in each month.
     query = (Tweet
              .select(
                  db.truncate_date('month', Tweet.timestamp).alias('month'),
                  fn.COUNT(Tweet.id).alias('count'))
              .group_by(db.truncate_date('month', Tweet.timestamp)))
     for row in query:
         print(row.month, '->', row.count)

:param date_field: a SQL node containing a date/time, for example
      a :class:`DateTimeField`.
  :return: a SQL node representing the value as an integer unix
      timestamp.

  Backend-appropriate conversion of a datetime value to an integer
  timestamp. See also :meth:`DateTimeField.to_timestamp`, which calls
  this.

:param date_field: a SQL node containing an integer unix timestamp.
  :return: a SQL node representing the value as a datetime.

  Inverse of :meth:`to_timestamp`.

:return: a SQL node representing a function call that returns a random
      value.

  A compatible interface for calling the appropriate random number
  generation function provided by the database. For Postgres and Sqlite,
  this is equivalent to ``fn.random()``, for MySQL ``fn.rand()``.

db = SqliteDatabase('my_app.db', pragmas=(
      ('cache_size', -16000),  # 16MB
      ('journal_mode', 'wal'),  # Use write-ahead-log journal mode.
  ))

  # Alternatively, pragmas can be specified using a dictionary.
  db = SqliteDatabase('my_app.db', pragmas={'journal_mode': 'wal'})

:param key: Setting name.
  :param value: New value for the setting (optional).
  :param permanent: Apply this pragma whenever a connection is opened.
  :param str schema: Database name to apply pragma to.

  Execute a PRAGMA query once on the active connection. If a value is not
  specified, then the current value will be returned.

  If ``permanent`` is specified, then the PRAGMA query will also be
  executed whenever a new connection is opened, ensuring it is always
  in-effect.

Get or set the application_id pragma for the current connection.

Get or set the cache_size pragma for the current connection.

Get the data_version pragma for the current connection. Changes when
  the database file is modified by another connection. Read-only.

Get or set the foreign_keys pragma for the current connection.

Get or set the journal_mode pragma.

Get or set the journal_size_limit pragma.

Get or set the mmap_size pragma for the current connection.

Get or set the page_size pragma.

Get or set the read_uncommitted pragma for the current connection.

Get or set the synchronous pragma for the current connection.

Get or set the user_version pragma for the current connection.

Get or set the wal_autocheckpoint pragma for the current connection.

Get or set the busy timeout (seconds).

:param str name: Name of the function (defaults to function name).
  :param int num_params: Number of parameters the function accepts,
      or -1 for any number.
  :param bool deterministic: Whether the function is deterministic for a
      given input (this is required to use the function in an index).
      Requires Sqlite 3.20 or newer, and ``sqlite3`` driver support
      (added to stdlib in Python 3.8).

  Decorator to register a user-defined scalar function.

  Example:

  .. code-block:: python

     @db.func('title_case')
     def title_case(s):
         return s.title() if s else ''

     Book.select(fn.title_case(Book.title))

:param fn: The user-defined scalar function.
  :param str name: Name of function (defaults to function name)
  :param int num_params: Number of arguments the function accepts, or
      -1 for any number.
  :param bool deterministic: Whether the function is deterministic for a
      given input (this is required to use the function in an index).
      Requires Sqlite 3.20 or newer, and ``sqlite3`` driver support
      (added to stdlib in Python 3.8).

  Register a user-defined scalar function. The function will be
  registered each time a new connection is opened.  Additionally, if a
  connection is already open, the function will be registered with the
  open connection.

:param str name: Name of the aggregate (defaults to class name).
  :param int num_params: Number of parameters the aggregate accepts,
      or -1 for any number.

  Class decorator to register a user-defined aggregate function.

  Example:

  .. code-block:: python

     @db.aggregate('md5')
     class MD5(object):
         def initialize(self):
             self.md5 = hashlib.md5()

         def step(self, value):
             self.md5.update(value)

         def finalize(self):
             return self.md5.hexdigest()


     @db.aggregate()
     class Product(object):
         '''Like SUM() except calculates cumulative product.'''
         def __init__(self):
             self.product = 1

         def step(self, value):
             self.product *= value

         def finalize(self):
             return self.product

:param klass: Class implementing aggregate API.
  :param str name: Aggregate function name (defaults to name of class).
  :param int num_params: Number of parameters the aggregate accepts, or
      -1 for any number.

  Register a user-defined aggregate function.

  The function will be registered each time a new connection is opened.
  Additionally, if a connection is already open, the aggregate will be
  registered with the open connection.

:param str name: Name of the window function (defaults to class name).
  :param int num_params: Number of parameters the function accepts, or -1
      for any number.

  Class decorator to register a user-defined window function. Window
  functions must define the following methods:

  * ``step()`` - receive values from a row and update state.
  * ``inverse()`` - inverse of ``step()`` for the given values.
  * ``value()`` - return the current value of the window function.
  * ``finalize()`` - return the final value of the window function.

  Example:

  .. code-block:: python

     @db.window_function('my_sum')
     class MySum(object):
         def __init__(self):
             self._value = 0

         def step(self, value):
             self._value += value

         def inverse(self, value):
             self._value -= value

         def value(self):
             return self._value

         def finalize(self):
             return self._value

:param klass: Class implementing window function API.
  :param str name: Window function name (defaults to name of class).
  :param int num_params: Number of parameters the function accepts, or
      -1 for any number.

  Register a user-defined window function, requires SQLite >= 3.25.0
  and Python 3.11+ (or a ``pysqlite3`` build with window-function
  support).

  The window function will be registered each time a new connection is
  opened. Additionally, if a connection is already open, the window
  function will be registered with the open connection.

:param str name: Name of collation (defaults to function name)

  Decorator to register a user-defined collation.

  Example:

  .. code-block:: python

     @db.collation('reverse')
     def collate_reverse(s1, s2):
         return -cmp(s1, s2)

     # Usage:
     Book.select().order_by(collate_reverse.collation(Book.title))

     # Equivalent:
     Book.select().order_by(Book.title.asc(collation='reverse'))

  The ``collate_reverse`` function has a ``collation`` attribute, a
  shorthand for generating the collation SQL.

:param fn: The collation function.
  :param str name: Name of collation (defaults to function name)

  Register a user-defined collation. The collation will be registered
  each time a new connection is opened.  Additionally, if a connection is
  already open, the collation will be registered with the open
  connection.

:param name: Name of the user-defined scalar function.

  Unregister the user-defined scalar function.

:param name: Name of the user-defined aggregate.

  Unregister the user-defined aggregate.

:param name: Name of the user-defined window function.

  Unregister the user-defined window function.

:param name: Name of the user-defined collation.

  Unregister the user-defined collation.

Load the given extension shared library. Extension will be loaded for the
  current connection as well as all subsequent connections.

  .. code-block:: python

     db = SqliteDatabase('my_app.db')

     # Load extension in closure.so shared library.
     db.load_extension('closure')

Unregister extension from being automatically loaded on new connections.

:param str filename: Database to attach (or ``:memory:`` for in-memory)
  :param str name: Schema name for attached database.
  :return: boolean indicating success

  Register another database file that will be attached to every database
  connection. If the main database is currently connected, the new
  database will be attached on the open connection.

  Databases that are attached using this method will be attached
  every time a database connection is opened.

:param str name: Schema name for attached database.
  :return: boolean indicating success

  Unregister another database file that was attached previously with a
  call to ``attach()``. If the main database is currently connected, the
  attached database will be detached from the open connection.

:param str lock_type: Locking strategy: DEFERRED, IMMEDIATE, EXCLUSIVE.

  Create an atomic context-manager / decorator, optionally using the
  specified locking strategy (default DEFERRED).

  Lock type only applies to the outermost ``atomic()`` block.

  .. seealso:: :ref:`sqlite-locking`

:param str lock_type: Locking strategy: DEFERRED, IMMEDIATE, EXCLUSIVE.

  Create a transaction context-manager / decorator, optionally using the
  specified locking strategy (default DEFERRED).

db = PostgresqlDatabase(
      'app',
      user='postgres',
      host='10.8.0.1',
      port=5432,
      password=os.environ['PGPASSWORD'],
      isolation_level='SERIALIZABLE')

:param str val: Time interval, e.g. ``'30 minutes'``
  :return: expression representing the interval.

:param str timezone: timezone name, e.g. "US/Central".
  :return: no return value.

  Set the timezone on the current connection. If no connection is open,
  then one will be opened.

:param isolation_level: Isolation level constant, defined in the
      ``psycopg2.extensions`` module or ``psycopg.IsolationLevel`` enum (psycopg3).
      Also accepts string which is converted to the matching constant.
      Set to ``None`` to use the server default.
  :type isolation_level: int, str

  Example of setting isolation level:

  .. code-block:: python

     # psycopg2 or psycopg3
     db.set_isolation_level('SERIALIZABLE')

     # psycopg2
     from psycopg2.extensions import ISOLATION_LEVEL_SERIALIZABLE
     db.set_isolation_level(ISOLATION_LEVEL_SERIALIZABLE)

     # psycopg3
     from psycopg import IsolationLevel
     db.set_isolation_level(IsolationLevel.SERIALIZABLE)

  Isolation level values in order of increasing strictness:

  * READ UNCOMMITTED
  * READ COMMITTED
  * REPEATABLE READ
  * SERIALIZABLE

  See the `Postgresql transaction isolation docs <https://www.postgresql.org/docs/current/transaction-iso.html>`__
  and Peewee's :ref:`postgres-isolation` for additional discussion.

:param isolation_level: Isolation strategy: SERIALIZABLE, READ COMMITTED, REPEATABLE READ, READ UNCOMMITTED
  :type isolation_level: int, str

  Create an atomic context-manager, optionally using the specified
  isolation level (if unspecified, the connection default will be used).

  Isolation level only applies to the outermost ``atomic()`` block.

  See the `Postgresql transaction isolation docs <https://www.postgresql.org/docs/current/transaction-iso.html>`__
  and Peewee's :ref:`postgres-isolation` for additional discussion.

:param isolation_level: Isolation strategy: SERIALIZABLE, READ COMMITTED, REPEATABLE READ, READ UNCOMMITTED
  :type isolation_level: int, str

  Create a transaction context-manager, optionally using the specified
  isolation level (if unspecified, the connection default will be used).

db = MySQLDatabase('app', host='10.8.0.1')

:param str isolation_level: Isolation strategy: SERIALIZABLE, READ COMMITTED, REPEATABLE READ, READ UNCOMMITTED

  Create an atomic context-manager, optionally using the specified
  isolation level (if unspecified, the server default will be used).

  Isolation level only applies to the outermost ``atomic()`` block.

:param str isolation_level: Isolation strategy: SERIALIZABLE, READ COMMITTED, REPEATABLE READ, READ UNCOMMITTED

  Create a transaction context-manager, optionally using the specified
  isolation level (if unspecified, the server default will be used).

Begin the transaction or savepoint.

  :return: Either a :class:`_transaction` or :class:`_savepoint` instance,
     depending on nesting.

Commit the transaction or savepoint if exiting cleanly. If an unhandled
  exception occurred, roll back.

Decorate the wrapped function with a transaction or savepoint. Equivalent
  to:

  .. code-block::

     @db.atomic()
     def modify_data():
         ...

     def modify_data():
         with db.atomic():
             ...

:param bool begin: If ``True`` (default), automatically start a new
      transaction after the commit completes.

  Commit the current transaction. Subsequent statements inside the
  wrapped block run in the new transaction unless ``begin=False``.

:param bool begin: If ``True`` (default), automatically start a new
      transaction after the rollback completes.

  Roll back the current transaction. Subsequent statements inside
  the wrapped block run in the new transaction unless
  ``begin=False``.

:param bool begin: If ``True`` (default), automatically begin a
      new savepoint after releasing.

  Release the current savepoint. Subsequent statements run inside
  the new savepoint unless ``begin=False``.

:param bool begin: If ``True`` (default), automatically begin a
      new savepoint after rollback.

  Roll back to the current savepoint. Subsequent statements run
  inside the new savepoint unless ``begin=False``.

db = SqliteDatabase(':memory:')

  class User(Model):
      username = TextField()
      join_date = DateTimeField(default=datetime.datetime.now)
      is_admin = BooleanField(default=False)

  admin = User(username='admin', is_admin=True)
  admin.save()

:param str alias: Optional name for alias.
  :return: :class:`ModelAlias` instance.

  Create an alias to the model-class. Model aliases allow you to
  reference the same :class:`Model` multiple times in a query, for
  example when doing a self-join or sub-query.

  Example:

  .. code-block:: python

     Parent = Category.alias()
     sq = (Category
           .select(Category, Parent)
           .join(Parent, on=(Category.parent == Parent.id))
           .where(Parent.name == 'parent category'))

:param fields: A list of model classes, field instances, functions or
      expressions. If no arguments are provided, all columns for the
      given model will be selected by default.
  :return: :class:`ModelSelect` query.

  Create a SELECT query. If no fields are explicitly provided, the query
  will by default SELECT all the fields defined on the model, unless you
  are using the query as a sub-query, in which case only the primary key
  will be selected by default.

  Example of selecting all columns:

  .. code-block:: python

     query = User.select().where(User.active == True).order_by(User.username)

  Example of selecting all columns on *Tweet* and the parent model,
  *User*. When the ``user`` foreign key is accessed on a *Tweet*
  instance no additional query will be needed (see :ref:`N+1 <nplusone>`
  for more details):

  .. code-block:: python

     query = (Tweet
              .select(Tweet, User)
              .join(User)
              .order_by(Tweet.created_date.desc()))

     for tweet in query:
         print(tweet.user.username, '->', tweet.content)

  Example of subquery only selecting the primary key:

  .. code-block:: python

     inactive_users = User.select().where(User.active == False)

     # Here, instead of defaulting to all columns, Peewee will default
     # to only selecting the primary key.
     Tweet.delete().where(Tweet.user.in_(inactive_users)).execute()

  See :ref:`querying` for in-depth discussion.

:param dict __data: ``dict`` of fields to values.
  :param update: Field-name to value mapping.

  Create an UPDATE query.

  Example showing users being marked inactive if their registration has
  expired:

  .. code-block:: python

     q = (User
          .update(active=False)
          .where(User.registration_expired == True))
     q.execute()  # Execute the query, returning number of rows updated.

  Example showing an atomic update:

  .. code-block:: python

     q = (PageView
          .update({PageView.count: PageView.count + 1})
          .where(PageView.url == url))
     q.execute()  # Execute the query.

  Update queries support :meth:`~_WriteQuery.returning` with Postgresql and SQLite
  to obtain the updated rows:

  .. code-block:: python

     query = (User
              .update(spam=True)
              .where(User.username.contains('billing'))
              .returning(User))
     for user in query:
         print(f'Marked {user.username} as spam')

  See :ref:`updating-records` for additional discussion.

  When an update query is executed, the number of rows modified will
  be returned.

:param dict __data: ``dict`` of fields to values to insert.
  :param insert: Field-name to value mapping.

  Create an INSERT query.

  Insert a new row into the database. If any fields on the model have
  default values, these values will be used if the fields are not
  explicitly set in the ``insert`` dictionary.

  Example showing creation of a new user:

  .. code-block:: python

     q = User.insert(username='admin', active=True, registration_expired=False)
     q.execute()  # perform the insert.

  You can also use :class:`Field` objects as the keys:

  .. code-block:: python

     new_id = User.insert({User.username: 'admin'}).execute()

  If you have a model with a default value on one of the fields, and
  that field is not specified in the ``insert`` parameter, the default
  will be used:

  .. code-block:: python

     class User(Model):
         username = CharField()
         active = BooleanField(default=True)

     # This INSERT query will automatically specify `active=True`:
     User.insert(username='charlie')

  Insert queries support :meth:`~_WriteQuery.returning` with Postgresql and
  SQLite to obtain the inserted rows:

  .. code-block:: python

     alice, = (User
               .insert(username='alice')
               .returning(User)
               .execute())
     print(f'Added {alice.username} with id = {alice.id}')

  When an insert query is executed on a table with an
  auto-incrementing primary key, the primary key of the new row will
  be returned.

:param rows: An iterable that yields rows to insert.
  :param list fields: List of fields being inserted.
  :return: number of rows modified (see note).

  INSERT multiple rows of data.

  The ``rows`` parameter must be an iterable that yields dictionaries or
  tuples, where the ordering of the tuple values corresponds to the
  fields specified in the ``fields`` argument. As with
  :meth:`~Model.insert`, fields that are not specified in the
  dictionary will use their default value, if one exists.

  Due to the nature of bulk inserts, each row must contain the same
  fields. The following will not work:

  .. code-block:: python

      Person.insert_many([
          {'first_name': 'Peewee', 'last_name': 'Herman'},
          {'first_name': 'Alice'},  # Missing "last_name"!
      ]).execute()

  Example of inserting multiple Users:

  .. code-block:: python

     data = [
         ('charlie', True),
         ('alice', False),
         ('carol', False)]
     query = User.insert_many(data, fields=[User.username, User.is_admin])
     query.execute()

  Equivalent example using dictionaries:

  .. code-block:: python

     data = [
         {'username': 'charlie', 'is_admin': True},
         {'username': 'alice', 'is_admin': False},
         {'username': 'carol', 'is_admin': False}]

     # Insert new rows.
     User.insert_many(data).execute()

  Because the ``rows`` parameter can be an arbitrary iterable, you can
  also use a generator:

  .. code-block:: python

     def get_usernames():
         for username in ['charlie', 'alice', 'peewee']:
             yield {'username': username}
     User.insert_many(get_usernames()).execute()

  Insert queries support :meth:`~_WriteQuery.returning` with Postgresql and
  SQLite to obtain the inserted rows:

  .. code-block:: python

     query = (User
              .insert_many([{'username': 'alice'}, {'username': 'bob'}])
              .returning(User))
     for user in query:
         print(f'Added {user.username} with id = {user.id}')

  See :ref:`bulk-inserts` for additional discussion.

  SQLite has a default limit of bound variables per statement.
  Additional discussion: :ref:`bulk-inserts`.

  SQLite documentation:

  * `Max variable number limit <https://www.sqlite.org/limits.html#max_variable_number>`_
  * `SQLite compile-time flags <https://www.sqlite.org/compile.html>`_

  The default return value is the number of rows modified. However,
  when using Postgresql, Peewee will return a cursor that yields the
  primary-keys of the inserted rows. To disable this functionality with
  Postgresql, append ``as_rowcount()`` to your insert.

:param Select query: SELECT query to use as source of data.
  :param fields: Fields to insert data into.
  :return: number of rows modified (see note).

  Generates an ``INSERT INTO ... SELECT`` query, copying rows from one
  table into another without round-tripping data through Python:

  .. code-block:: python

     (TweetArchive
      .insert_from(
          Tweet.select(Tweet.user, Tweet.message),
          fields=[TweetArchive.user, TweetArchive.message])
      .execute())

  See :ref:`bulk-inserts` for additional discussion.

  The default return value is the number of rows modified. However,
  when using Postgresql, Peewee will return a cursor that yields the
  primary-keys of the inserted rows. To disable this functionality with
  Postgresql, append ``as_rowcount()`` to your insert.

:param dict __data: ``dict`` of fields to values to insert.
  :param insert: Field-name to value mapping.

  SQLite and MySQL support a ``REPLACE`` query, which will replace the row
  in the event of a conflict:

  .. code-block:: python

     class User(BaseModel):
         username = TextField(unique=True)
         last_login = DateTimeField(null=True)

     # Insert, or replace the entire existing row.
     User.replace(username='alice', last_login=datetime.datetime.now()).execute()

     # Equivalent using insert():
     (User
      .insert(username='alice', last_login=datetime.datetime.now())
      .on_conflict_replace()
      .execute())

  See :ref:`upsert` for additional discussion.

  ``replace`` deletes and re-inserts, which changes the primary key.
  Use :meth:`Insert.on_conflict` when the primary key must be preserved,
  or when only some columns should be updated.

:param rows: An iterable that yields rows to insert.
  :param list fields: List of fields being inserted.

  INSERT multiple rows of data using REPLACE for conflict-resolution.

  .. seealso::
     * :meth:`Model.insert_many` for syntax and examples.
     * :ref:`upsert` for additional discussion.

  ``replace_many`` may delete and re-insert rows, which changes the
  primary key. Use :meth:`Insert.on_conflict` when the primary key must
  be preserved, or when only some columns should be updated.

:param str sql: SQL query to execute.
  :param params: Parameters for query.

  Execute a SQL query directly.

  Example selecting rows from the User table:

  .. code-block:: python

     q = User.raw('select id, username from users')
     for user in q:
         print(user.id, user.username)

  Generally the use of ``raw`` is reserved for those cases where you
  can significantly optimize a select query.

Create a DELETE query.

  Example showing the deletion of all inactive users:

  .. code-block:: python

     q = User.delete().where(User.active == False)
     q.execute()  # Remove the rows, return number of rows removed.

  Delete queries support :meth:`~_WriteQuery.returning` with Postgresql and
  SQLite to obtain the deleted rows:

  .. code-block:: python

     query = (User
              .delete()
              .where(User.username.contains('billing'))
              .returning(User))
     for user in query:
         print(f'Deleted: {user.username}')

  .. seealso::
     * :ref:`deleting-records` for discussion and example usage.
     * :meth:`Model.delete_instance` for deleting individual rows.

:param query: Mapping of field-name to value.

  INSERT new row into table and return corresponding model instance.

  Example showing the creation of a user (a row will be added to the
  database):

  .. code-block:: python

     user = User.create(username='admin', password='test')

  .. note::
     ``create()`` is a shorthand for instantiate -> save.

:param iterable model_list: a list or other iterable of unsaved
      :class:`Model` instances.
  :param int batch_size: number of rows to batch per insert. If
      unspecified, all models will be inserted in a single query.
  :return: no return value.

  Efficiently INSERT multiple unsaved model instances into the database.
  Unlike :meth:`~Model.insert_many`, which accepts row data as a list
  of either dictionaries or lists, this method accepts a list of unsaved
  model instances.

  Example:

  .. code-block:: python

     user_list = [User(username='u%s' % i) for i in range(10)]

     with db.atomic():
         # All 10 users are inserted in a single query.
         User.bulk_create(user_list)

  Batches:

  .. code-block:: python

      user_list = [User(username='u%s' % i) for i in range(10)]

      with database.atomic():
          # Will execute 4 INSERT queries (3 batches of 3, 1 batch of 1).
          User.bulk_create(user_list, batch_size=3)

  * The primary-key value for the newly-created models will only be
    set if you are using Postgresql (which supports the ``RETURNING``
    clause).
  * SQLite has a limit of bound parameters for a query, typically 999
    for Sqlite < 3.32.0, and 32766 for newer versions.
  * **Strongly recommended** that you wrap the call in a transaction
    using :meth:`Database.atomic`. Otherwise an error in a batch mid-way
    through could leave the database in an inconsistent state.

:param iterable model_list: a list or other iterable of
      :class:`Model` instances.
  :param list fields: list of fields to update.
  :param int batch_size: number of rows to batch per insert. If
      unspecified, all models will be inserted in a single query.
  :return: total number of rows updated.

  UPDATE multiple model instances in a single query by generating a
  ``CASE`` statement mapping ids to new field values.

  Example:

  .. code-block:: python

     # First, create 3 users.
     u1, u2, u3 = [User.create(username='u%s' % i) for i in (1, 2, 3)]

     # Now let's modify their usernames.
     u1.username = 'u1-x'
     u2.username = 'u2-y'
     u3.username = 'u3-z'

     # Update all three rows using a single UPDATE query.
     User.bulk_update([u1, u2, u3], fields=[User.username])

  This will result in executing the following SQL:

  .. code-block:: sql

     UPDATE "users" SET "username" = CASE "users"."id"
         WHEN 1 THEN 'u1-x'
         WHEN 2 THEN 'u2-y'
         WHEN 3 THEN 'u3-z' END
     WHERE "users"."id" IN (1, 2, 3);

  If you have a large number of objects to update, it is strongly
  recommended that you specify a ``batch_size`` and wrap the operation in
  a transaction:

  .. code-block:: python

     with database.atomic():
         User.bulk_update(user_list, fields=['username'], batch_size=50)

  ``bulk_update`` may be slower than a direct UPDATE query when the list is
  very large, because the generated ``CASE`` expression grows proportionally.
  For updates that can be expressed as a single WHERE clause, the direct
  :meth:`~Model.update` approach is faster.

:param query: Zero or more :class:`Expression` objects.
  :param filters: Mapping of field-name to value for Django-style filter.
  :raises: :class:`DoesNotExist`
  :return: Model instance matching the specified filters.

  Retrieve a single model instance matching the given filters. If no
  model is returned, a :class:`DoesNotExist` is raised.

  .. code-block:: python

     user = User.get(User.username == username, User.active == True)

  This method is also exposed via the :class:`SelectQuery`, though it
  takes no parameters:

  .. code-block:: python

     active = User.select().where(User.active == True)
     try:
         user = (active
                 .where(
                     (User.username == username) &
                     (User.active == True))
                 .get())
     except User.DoesNotExist:
         user = None

  The :meth:`~Model.get` method is shorthand for selecting with a
  limit of 1. It has the added behavior of raising an exception when
  no matching row is found. If more than one row is found, the first
  row returned by the database cursor will be used.

Identical to :meth:`Model.get` but returns ``None`` if no model
  matches the given filters.

  .. code-block:: python

     active = User.select().where(User.active == True)
     user = (active
             .where(
                 (User.username == username) &
                 (User.active == True))
             .get_or_none())

:param pk: Primary-key value.

  Short-hand for calling :meth:`Model.get` specifying a lookup by
  primary key. Raises a :class:`DoesNotExist` if instance with the
  given primary key value does not exist.

  Example:

  .. code-block:: python

     user = User.get_by_id(1)  # Returns user with id = 1.

:param key: Primary-key value.
  :param dict value: Mapping of field to value to update.

  Short-hand for updating the data with the given primary-key. If no row
  exists with the given primary key, no exception will be raised.

  Example:

  .. code-block:: python

     # Set "is_admin" to True on user with id=3.
     User.set_by_id(3, {'is_admin': True})

:param pk: Primary-key value.

  Short-hand for deleting the row with the given primary-key. If no row
  exists with the given primary key, no exception will be raised.

:param kwargs: Mapping of field-name to value.
  :param defaults: Default values to use if creating a new row.
  :return: Tuple of :class:`Model` instance and boolean indicating
      if a new object was created.

  Attempt to get the row matching the given filters. If no matching row
  is found, create a new row.

  .. warning:: Race-conditions are possible when using this method.

  Example **without** ``get_or_create``:

  .. code-block:: python

     # Without `get_or_create`, we might write:
     try:
         person = Person.get(
             (Person.first_name == 'John') &
             (Person.last_name == 'Lennon'))
     except Person.DoesNotExist:
         person = Person.create(
             first_name='John',
             last_name='Lennon',
             birthday=datetime.date(1940, 10, 9))

  Equivalent code using ``get_or_create``:

  .. code-block:: python

     person, created = Person.get_or_create(
         first_name='John',
         last_name='Lennon',
         defaults={'birthday': datetime.date(1940, 10, 9)})

:param dq_nodes: Zero or more :class:`DQ` objects.
  :param filters: Django-style filters.
  :return: :class:`ModelSelect` query.

:return: The primary-key of the model instance.

:param bool force_insert: Force INSERT query.
  :param list only: Only save the given :class:`Field` instances.
  :return: Number of rows modified.

  Save the data in the model instance. By default, the presence of a
  primary-key value will cause an UPDATE query to be executed.

  Example showing saving a model instance:

  .. code-block:: python

     user = User()
     user.username = 'some-user'  # does not touch the database
     user.save()  # change is persisted to the db

  When a model uses any primary key OTHER than an auto-incrementing integer
  it is necessary to specify ``force_insert=True`` when calling ``save()``
  with a new instance:

  .. code-block:: python

     class Tag(Model):
         tag = TextField(primary_key=True)

     t = Tag(tag='python')
     t.save(force_insert=True)

     # create() automatically specifies force_insert=True:
     t = Tag.create(tag='sqlite')

Return list of fields that have been modified.

  :rtype: list

  If you just want to persist modified fields, you can call
  ``model.save(only=model.dirty_fields)``.

  To **always** save a model's dirty fields, use the Meta option
  ``only_save_dirty = True``. Any calls to :meth:`Model.save()` will
  only save the dirty fields by default:

  .. code-block:: python

     class Person(Model):
         first_name = CharField()
         last_name = CharField()
         dob = DateField()

         class Meta:
             database = db
             only_save_dirty = True

  Peewee determines whether a field is "dirty" by observing when the
  field attribute is set on a model instance. If the field contains a
  value that is mutable, such as a dictionary instance, and that
  dictionary is then modified, Peewee will not notice the change.

  .. warning::
     Do not do membership tests on this list, e.g. ``f in dirty_fields``
     because if there is one or more fields in the dirty fields list,
     the field equality override will return a truthy Expression object.
     If you want to test if a field is dirty, instead
     check ``f.name in model.dirty_field_names``.

Return list of field names that have been modified.

  :rtype: list

Return boolean indicating whether any fields were manually set.

:param bool recursive: Delete related models.
   :param bool delete_nullable: Delete related models that have a null
       foreign key. If ``False`` nullable relations will be set to NULL.

   Delete the given instance.  Any foreign keys set to cascade on
   delete will be deleted automatically.  For more programmatic control,
   you can specify ``recursive=True``, which will delete any non-nullable
   related models (those that *are* nullable will be set to NULL).  If you
   wish to delete all dependencies regardless of whether they are nullable,
   set ``delete_nullable=True``.

   Example:

   .. code-block:: python

      some_obj.delete_instance()

   See :ref:`deleting-records` for additional discussion.

:param Database database: database to bind to.
  :param bool bind_refs: Bind related models.
  :param bool bind_backrefs: Bind back-reference related models.

  Bind the model (and specified relations) to the given database.

  See also: :meth:`Database.bind`.

Like :meth:`~Model.bind`, but returns a context manager that only
  binds the models for the duration of the wrapped block.

  See also: :meth:`Database.bind_ctx`.

:return: boolean indicating whether the table exists.

:param bool safe: When ``True``, the create table query will
      include an ``IF NOT EXISTS`` clause.

  Create the model table, indexes, constraints and sequences.

  Example:

  .. code-block:: python

     with database:
         SomeModel.create_table()

:param bool safe: If set to ``True``, the drop table query will
      include an ``IF EXISTS`` clause.
  :param bool drop_sequences: Drop any sequences associated with the
      columns on the table (postgres only).

  Drop the model table.

:param bool restart_identity: Restart the id sequence (postgresql-only).
  :param bool cascade: Truncate related tables as well (postgresql-only).

  Truncate (delete all rows) for the model.

:param fields: Fields to index.
  :param bool unique: Whether index is UNIQUE.
  :param bool safe: Whether to add IF NOT EXISTS clause.
  :param Expression where: Optional WHERE clause for index.
  :param str using: Index algorithm.
  :param str name: Optional index name.

  Expressive method for declaring an index on a model. Wraps the
  declaration of a :class:`ModelIndex` instance.

  Examples:

  .. code-block:: python

     class Article(Model):
         name = TextField()
         timestamp = TimestampField()
         status = IntegerField()
         flags = BitField()

         is_sticky = flags.flag(1)
         is_favorite = flags.flag(2)

     # CREATE INDEX ... ON "article" ("name", "timestamp" DESC)
     idx = Article.index(Article.name, Article.timestamp.desc())

     # Be sure to add the index to the model:
     Article.add_index(idx)

     # CREATE UNIQUE INDEX ... ON "article" ("timestamp" DESC, "flags" & 2)
     # WHERE ("status" = 1)
     idx = (Article
            .index(Article.timestamp.desc(),
                   Article.flags.bin_and(2),
                   unique=True)
            .where(Article.status == 1))

     # Add index to model:
     Article.add_index(idx)

:param args: a :class:`ModelIndex` instance, Field(s) to index,
      or a :class:`SQL` instance that contains the SQL for creating
      the index.
  :param kwargs: Keyword arguments passed to :class:`ModelIndex`
      constructor.

  Add an index to the model's definition.

  This method does not actually create the index in the database.
  Rather, it adds the index definition to the model's metadata, so
  that a subsequent call to :meth:`~Model.create_table` will
  create the new index (along with the table).

  Examples:

  .. code-block:: python

     class Article(Model):
         name = TextField()
         timestamp = TimestampField()
         status = IntegerField()
         flags = BitField()

         is_sticky = flags.flag(1)
         is_favorite = flags.flag(2)

     # CREATE INDEX ... ON "article" ("name", "timestamp") WHERE "status" = 1
     idx = Article.index(Article.name, Article.timestamp).where(Article.status == 1)
     Article.add_index(idx)

     # CREATE UNIQUE INDEX ... ON "article" ("timestamp" DESC, "flags" & 2)
     ts_flags_idx = Article.index(
         Article.timestamp.desc(),
         Article.flags.bin_and(2),
         unique=True)
     Article.add_index(ts_flags_idx)

     # You can also specify a list of fields and use the same keyword
     # arguments that the ModelIndex constructor accepts:
     Article.add_index(
         Article.name,
         Article.timestamp.desc(),
         where=(Article.status == 1))

     # Or even specify a SQL query directly:
     Article.add_index(SQL('CREATE INDEX ...'))

:param bool search_nullable: Follow dependencies reachable via nullable
      foreign keys (enabled by default).
  :param bool exclude_null_children: Do not descend into the dependencies
      of models reached via a nullable foreign key.
  :rtype: Generator expression yielding queries and foreign key fields.

  Generate a list of queries of dependent models. Yields a 2-tuple
  containing the query and corresponding foreign key field.  Useful for
  searching dependencies of a model, i.e. things that would be orphaned
  in the event of a delete.

:return: a :class:`ModelSelect` for the given class.

  Convenience function for iterating over all instances of a model.

  Example:

  .. code-block:: python

     Setting.insert_many([
         {'key': 'host', 'value': '192.168.1.2'},
         {'key': 'port', 'value': '1337'},
         {'key': 'user', 'value': 'nuggie'}]).execute()

     # Load settings from db into dict.
     settings = {setting.key: setting.value for setting in Setting}

:return: Count of rows in table.

  Example:

  .. code-block:: python

     n_accounts = len(Account)

     # Equivalent:
     n_accounts = Account.select().count()

Owner = User.alias()
   query = (Favorite
            .select(Favorite, Tweet.content, User.username, Owner.username)
            .join_from(Favorite, Owner)  # Determine owner of favorite.
            .join_from(Favorite, Tweet)  # Join favorite -> tweet.
            .join_from(Tweet, User))     # Join tweet -> user.

class User(Model):
      ...
      class Meta:
          database = db
          table_name = 'user'

  # After class-creation, Meta configuration lives here:
  isinstance(User._meta, Metadata)  # True
  User._meta.database is db         # True
  User._meta.table_name == 'user'   # True

Return a reference to the underlying :class:`Table` object.

:param bool refs: Follow foreign-key references.
  :param bool backrefs: Follow foreign-key back-references.
  :param bool depth_first: Do a depth-first search (``False`` for
      breadth-first).

  Traverse the model graph and return a list of 3-tuples, consisting of
  ``(foreign key field, model class, is_backref)``.

:param Database database: database object to bind Model to.

  Bind the model class to the given :class:`Database` instance.

  .. warning::
     This API should not need to be used. Instead, to change a
     :class:`Model` database at run-time, use one of the following:

     * :meth:`Model.bind`
     * :meth:`Model.bind_ctx` (bind for scope of a context manager).
     * :meth:`Database.bind`
     * :meth:`Database.bind_ctx`

:param str table_name: table name to bind Model to.

  Bind the model class to the given table name at run-time.

from peewee import SubclassAwareMetadata

  class Base(Model):
      class Meta:
          database = db
          model_metadata_class = SubclassAwareMetadata

  # Create 3 model classes that inherit from Base.
  class A(Base): pass
  class B(Base): pass
  class C(Base): pass

  # Now let's make a helper for changing the `schema` for each Model.
  def change_schema(schema):
      def _update(model):
          model._meta.schema = schema
      return _update

  # Set all models to use "schema1", e.g. "schema1.a", "schema1.b", etc.
  # Will apply the function to every subclass of Base.
  Base._meta.map_models(change_schema('schema1'))

  # Set all models to use "schema2", e.g. "schema2.a", "schema2.b", etc.
  Base._meta.map_models(change_schema('schema2'))

Apply a function to all subclasses.

:param Database database: database to execute query against (defaults to
      the model's configured database).
  :return: A single row from the database.
  :raises: ``DoesNotExist`` if row not found.

  Execute the query and return the first row, if it exists. Multiple
  calls will result in multiple queries being executed.

  If no matching row is found, raise ``DoesNotExist``.

:param int n: Number of rows to return.
  :return: A single row if n = 1, else a list of rows.

  Execute the query and return the given number of rows from the start
  of the cursor. This function may be called multiple times safely, and
  will always return the first N rows of results.

:param int n: Number of rows to return.
  :return: A single row if n = 1, else a list of rows.

  Like the :meth:`~ModelSelect.peek` method, except a ``LIMIT`` is
  applied to the query to ensure that only ``n`` rows are returned.
  Multiple calls for the same value of ``n`` will not result in multiple
  executions.

  The query is altered in-place so it is **not** possible to call
  :meth:`~ModelSelect.first` and then later iterate over the full
  result-set using the same query object. Again, this is done to ensure
  that multiple calls to ``first()`` will not result in multiple query
  executions.

:param bool as_tuple: Return the result as a tuple?
  :param bool as_dict: Return the result as a dict?
  :return: Single scalar value. If ``as_tuple = True``, a row tuple is
      returned. If ``as_dict = True``, a row dict is returned.

  Return a scalar value from the first row of results. If multiple
  scalar values are anticipated (e.g. multiple aggregations in a single
  query) then you may specify ``as_tuple=True`` to get the row tuple.

  A ``LIMIT 1`` is applied internally, so only a single row is
  requested from the database. The query itself is not modified.

  Example:

  .. code-block:: python

     query = Note.select(fn.MAX(Note.timestamp))
     max_ts = query.scalar()

     query = Note.select(fn.MAX(Note.timestamp), fn.COUNT(Note.id))
     max_ts, n_notes = query.scalar(as_tuple=True)

     query = Note.select(fn.COUNT(Note.id).alias('count'))
     assert query.scalar(as_dict=True) == {'count': 123}

Return an iterator that yields scalar values from the first column of
  each result row. This is the multi-row equivalent of
  :py:meth:`~ModelSelect.scalar`.

  Equivalent to:

  .. code-block:: python

     [row[0] for row in query.tuples()]

  Example:

  .. code-block:: python

     query = Note.select(Note.timestamp).order_by(Note.timestamp)
     all_timestamps = list(query.scalars())

     # Can also be iterated directly:
     for ts in Note.select(Note.timestamp).scalars():
         print(ts)

:param bool clear_limit: Clear any LIMIT clause when counting.
  :return: Number of rows in the query result-set.

  Return number of rows in the query result-set.

  Implemented by running SELECT COUNT(1) FROM (<current query>).

  Example:

  .. code-block:: python

     n = Tweet.select().where(Tweet.is_published == True).count()
     print('%d published tweets' % n)

:return: Whether any results exist for the current query.

  Return a boolean indicating whether the current query has any results.

  Example:

  .. code-block:: python

     if User.select().where(User.username == 'Alice').exists():
         print('User found')

:param bool as_dict: Specify whether to return rows as dictionaries.

  Return rows as dictionaries.

  Example:

  .. code-block:: python
     :emphasize-lines: 5, 8

     query = (User
              .select(User.username, fn.COUNT(Tweet.id).alias('tweet_count'))
              .join(Tweet, JOIN.LEFT_OUTER)
              .group_by(User.username)
              .dicts())

     for row in query:
         print(row)  # {'username': 'Alice', 'tweet_count': 12}

:param bool as_tuple: Specify whether to return rows as tuples.

  Return rows as tuples.

  Example:

  .. code-block:: python
     :emphasize-lines: 5, 8

     query = (User
              .select(User.username, fn.COUNT(Tweet.id).alias('tweet_count'))
              .join(Tweet, JOIN.LEFT_OUTER)
              .group_by(User.username)
              .tuples())

     for row in query:
         print(row)  # ('Alice', 12)

:param bool as_namedtuple: Specify whether to return rows as named
      tuples.

  Return rows as named tuples.

  Example:

  .. code-block:: python
     :emphasize-lines: 5, 8

     query = (User
              .select(User.username, fn.COUNT(Tweet.id).alias('tweet_count'))
              .join(Tweet, JOIN.LEFT_OUTER)
              .group_by(User.username)
              .namedtuples())

     for row in query:
         print(row)  # Row(username='Alice', tweet_count=12)

:param constructor: Constructor (defaults to returning model instances)

  Return result rows as objects created using the given constructor. The
  default behavior is to create model instances.

  This method can be used, when selecting field data from multiple
  sources/models, to make all data available as attributes on the
  model being queried (as opposed to constructing the graph of joined
  model instances). For very complex queries this can have a positive
  performance impact, especially iterating large result sets.

  Example:

  .. code-block:: python

     query = (Tweet
              .select(Tweet.id, Tweet.content, User.username)
              .join(User)
              .objects())  # Apply all selections to Tweet instance.

     # NOTE: the username is applied directly to the tweet object
     # and accessed via `tweet.username`:
     for tweet in query:
         print(tweet.id, tweet.content, tweet.username)

  Similarly, you can use :meth:`~ModelSelect.dicts`,
  :meth:`~ModelSelect.tuples` or :meth:`~ModelSelect.namedtuples`
  to achieve even more performance.

Return result rows as :class:`Model` instances, rebuilding the model
  graph from explicitly selected and joined data. **This is the default**.

  .. code-block:: python

     query = (Tweet
              .select(Tweet, User)
              .join(User))

     # Note that `tweet.user` is populated already since we SELECTed
     # columns from the joined User model.
     for tweet in query:
         print(tweet.user.username, '->', tweet.content)

  For an in-depth discussion of foreign-keys, joins and relationships
  between models, refer to :ref:`relationships`.

:param dest: A :class:`Model`, :class:`ModelAlias`,
      :class:`Select` query, or other object to join to.
  :param str join_type: Join type, defaults to INNER.
  :param on: Join predicate or a :class:`ForeignKeyField` to join on.
  :param src: Explicitly specify the source of the join. If not specified
      then the current *join context* will be used.
  :param str attr: Attribute to use when projecting columns from the
      joined model.

  Join with another table-like object.

  Join type may be one of:

  * ``JOIN.INNER``
  * ``JOIN.LEFT_OUTER``
  * ``JOIN.RIGHT_OUTER``
  * ``JOIN.FULL``
  * ``JOIN.FULL_OUTER``
  * ``JOIN.CROSS``

  Example selecting tweets and joining on user in order to restrict to
  only those tweets made by "admin" users:

  .. code-block:: python

     sq = Tweet.select().join(User).where(User.is_admin == True)

  Example selecting users and joining on a particular foreign key field.
  See the :ref:`example app <example>` for a real-life usage:

  .. code-block:: python

     sq = User.select().join(Relationship, on=Relationship.to_user)

  For an in-depth discussion of foreign-keys, joins and relationships
  between models, refer to :ref:`relationships`.

:param src: Source for join.
  :param dest: Table to join to.

  Use same parameter order as the non-model-specific
  :meth:`~ModelSelect.join`. Bypasses the *join context* by requiring
  the join source to be specified.

:param ctx: A :class:`Model`, :class:`ModelAlias`, subquery, or
      other object that was joined-on.

  Switch the *join context* - the source which subsequent calls to
  :meth:`~ModelSelect.join` will be joined against. Used for
  specifying multiple joins against a single table.

  See :ref:`relationships` for additional discussion.

  If the ``ctx`` is not given, then the query's model will be used.

  The following example selects from tweet and joins on both user and
  tweet-flag:

  .. code-block:: python

      sq = Tweet.select().join(User).switch(Tweet).join(TweetFlag)

      # Equivalent (since Tweet is the query's model)
      sq = Tweet.select().join(User).switch().join(TweetFlag)

:param args: Zero or more :class:`DQ` objects.
  :param kwargs: Django-style keyword-argument filters.

  Use Django-style filters to express a WHERE clause. Joins can be
  followed by chaining foreign-key fields. The supported operations are:

  * ``eq`` - equals
  * ``ne`` - not equals
  * ``lt``, ``lte`` - less-than, less-than or equal-to
  * ``gt``, ``gte`` - greater-than, greater-than or equal-to
  * ``in``, ``not_in`` - IN and NOT IN set of values
  * ``is``, ``is_not`` - IS and IS NOT (e.g. IS NULL)
  * ``is_null`` - IS NULL if value is True, IS NOT NULL if False
  * ``like``, ``ilike`` - LIKE and ILIKE (case-insensitive)
  * ``regexp``, ``iregexp`` - regular expression match
  * ``contains``, ``startswith``, ``endswith`` - case-insensitive
    substring, prefix or suffix search. Wildcards in the value are
    escaped, matching the corresponding :py:class:`ColumnBase` methods.
  * ``between`` - BETWEEN low AND high, value must be a 2-tuple

  Examples:

  .. code-block:: python

     # Get all tweets by user with username="peewee".
     q = Tweet.filter(user__username='peewee')

     # Case-insensitive search of tweet content. Special characters in
     # the search string ("%", "_") are escaped automatically.
     q = Tweet.filter(content__contains='sql')

     # Get all posts that are draft or published, and written after 2023.
     q = Post.filter(
         (DQ(status='draft') | DQ(status='published')),
         timestamp__gte=datetime.date(2023, 1, 1))

:param subqueries: A list of :class:`Model` classes or select
      queries to prefetch. Each element may also be a ``(query, target_model)``
      tuple: the ``target_model`` names which previously-listed model
      should be joined through when more than one candidate exists.
  :param prefetch_type: Query type to use for the subqueries.
  :return: a list of models with selected relations prefetched.

  Execute the query, prefetching the given additional resources.

  .. note::
     :meth:`with_related` is the declarative, nestable form and is preferred
     for new code. ``prefetch`` is the flat-list form, kept for
     compatibility. Minimal example of using :meth:`with_related`:

     .. code-block:: python

        query = User.select().with_related(Load(User.tweets))

  Prefetch type may be one of:

  * ``PREFETCH_TYPE.WHERE``
  * ``PREFETCH_TYPE.JOIN``

  See also :func:`prefetch` standalone function.

  Example:

  .. code-block:: python

     # Fetch all Users and prefetch their associated tweets.
     query = User.select().prefetch(Tweet)
     for user in query:
         print(user.username)
         for tweet in user.tweets:
             print('  *', tweet.content)

  Because ``prefetch`` must reconstruct a graph of models, it is
  necessary to be sure that the foreign-key/primary-key of any
  related models are selected, so that the related objects can be
  mapped correctly.

  **Disambiguating multi-reference subqueries.** If a subquery relates to
  more than one previously-fetched query (for example, a ``Favorite`` row
  that has foreign keys to both ``User`` and ``Tweet``), use the
  ``(subquery, target_model)`` tuple form to pin the relationship:

  .. code-block:: python

     users = User.select()
     tweets = Tweet.select()
     favorites = Favorite.select()

     # Favorite will be attached to User (via Favorite.user), not to Tweet.
     query = prefetch(users, tweets, (favorites, User))

:param loads: One or more :class:`Load` nodes, or foreign-key /
      back-reference fields (wrapped in a :class:`Load` implicitly),
      describing the relationships to eagerly load.
  :return: the query. Related rows are loaded when it is executed.

  Eagerly load related objects described by a tree of :class:`Load` nodes.
  This is a declarative, nestable form of :meth:`prefetch`: each
  :class:`Load` names one relationship and supplies an ordinary query to
  fetch it. ``Load.then()`` is used to chain nested fetches.

  .. code-block:: python

     # For each user, load their tweets (ordered newest-to-oldest), and for
     # each Tweet, load associated Favorites.
     rels = (Load(User.tweets,
                  Tweet.select().order_by(Tweet.timestamp.desc()))
             .then(Load(Tweet.favorites)))

     query = User.select().with_related(rels)

     # Avoids N+1 problem - tweets and favorites are efficiently loaded.
     for user in query:
         for tweet in user.tweets:
             print(user.username, tweet.content, len(tweet.favorites))

     # Prints (tweets newest-first, with each tweet's favorite count):
     # alice alice-3 2
     # alice alice-2 0
     # alice alice-1 1
     # bob bob-2 1
     # bob bob-1 0

  The related rows are loaded once, when the query is first executed -
  whether by iteration, :py:meth:`get`, ``first()``, indexing or ``len()``.
  The relation queries run against the same database as the parent query.

  See :class:`Load` for the per-relation options, and :ref:`relationships` for
  a fuller discussion of joins and prefetching.

def get_user(email):
      try:
          return User.get(fn.LOWER(User.email) == email.lower())
      except User.DoesNotExist:
          return None

Attribute used to map this field to a column type, e.g. "INT". See
  the ``FIELD`` object in the source for more information.

Retrieve a reference to the underlying :class:`Column` object.

The model the field is bound to.

The name of the field.

Coerce a Python value into a value suitable for storage in the
  database. Sub-classes operating on special data-types will most likely
  want to override this method.

  Example:

  .. code-block:: python
     :emphasize-lines: 3

     class PickleField(BlobField):
         # Values going from Python -> Database should be pickled.
         def db_value(self, value):
             if value is not None:
                 return pickle.dumps(value, pickle.HIGHEST_PROTOCOL)

         # Values coming from the Database -> Python should be unpickled.
         def python_value(self, value):
             if value is not None:
                 return pickle.loads(value)

Coerce a value from the database into a Python object. Sub-classes
  operating on special data-types will most likely want to override this
  method.

  Example:

  .. code-block:: python
     :emphasize-lines: 8

     class PickleField(BlobField):
         # Values going from Python -> Database should be pickled.
         def db_value(self, value):
             if value is not None:
                 return pickle.dumps(value, pickle.HIGHEST_PROTOCOL)

         # Values coming from the Database -> Python should be unpickled.
         def python_value(self, value):
             if value is not None:
                 return pickle.loads(value)

This method is a shorthand that is used, by default, by both
  :meth:`~Field.db_value` and :meth:`~Field.python_value` to coerce the
  value to the field's underlying data-type.

  :param value: arbitrary data from app or backend
  :rtype: python data type

id = IdentityField()
  # "id" INT GENERATED BY DEFAULT AS IDENTITY NOT NULL PRIMARY KEY

Field class for storing decimal numbers. Values are represented as
``decimal.Decimal`` objects.

class Post(Model):
      content = TextField()
      flags = BitField()

      is_favorite = flags.flag(1)
      is_sticky = flags.flag(2)
      is_minimized = flags.flag(4)
      is_deleted = flags.flag(8)

  >>> p = Post()
  >>> p.is_sticky = True
  >>> p.is_minimized = True
  >>> print(p.flags)  # Prints 4 | 2 --> "6"
  6
  >>> p.is_favorite
  False
  >>> p.is_sticky
  True

# Generates a WHERE clause that looks like:
  # WHERE (post.flags & 1 != 0)
  query = Post.select().where(Post.is_favorite)

  # Query for sticky + favorite posts:
  query = Post.select().where(Post.is_sticky & Post.is_favorite)

# Set the 4th bit on all Post objects.
  Post.update(flags=Post.flags | 8).execute()

  # Clear the 1st and 3rd bits on all Post objects.
  Post.update(flags=Post.flags & ~(1 | 4)).execute()

# Set the "is_deleted" bit on all posts.
  Post.update(flags=Post.is_deleted.set()).execute()

  # Clear the "is_deleted" bit on all posts.
  Post.update(flags=Post.is_deleted.clear()).execute()

:param int value: Value associated with flag, typically a power of 2.

  Returns a descriptor that can get or set specific bits in the overall
  value. When accessed on the class itself, it returns a
  :class:`Expression` object suitable for use in a query.

  If the value is not provided, it is assumed that each flag will be an
  increasing power of 2, so if you had four flags, they would have the
  values 1, 2, 4, 8.

class Bitmap(Model):
      data = BigBitField()

  bitmap = Bitmap()

  # Sets the ith bit, e.g. the 1st bit, the 11th bit, the 63rd, etc.
  bits_to_set = (1, 11, 63, 31, 55, 48, 100, 99)
  for bit_idx in bits_to_set:
      bitmap.data.set_bit(bit_idx)

  # We can test whether a bit is set using "is_set":
  assert bitmap.data.is_set(11)
  assert not bitmap.data.is_set(12)

  # We can clear a bit:
  bitmap.data.clear_bit(11)
  assert not bitmap.data.is_set(11)

  # We can also "toggle" a bit. Recall that the 63rd bit was set earlier.
  assert bitmap.data.toggle_bit(63) is False
  assert bitmap.data.toggle_bit(63) is True
  assert bitmap.data.is_set(63)

  # BigBitField supports item accessor by bit-number, e.g.:
  assert bitmap.data[63]
  bitmap.data[0] = 1
  del bitmap.data[0]

  # We can also combine bitmaps using bitwise operators, e.g.
  b = Bitmap(data=b'\x01')
  b.data |= b'\x02'
  assert list(b.data) == [1, 1, 0, 0, 0, 0, 0, 0]
  assert len(b.data) == 1

Clears the bitmap and sets length to 0.

:param int idx: Bit to set, indexed starting from zero.

  Sets the *idx*-th bit in the bitmap.

:param int idx: Bit to clear, indexed starting from zero.

  Clears the *idx*-th bit in the bitmap.

:param int idx: Bit to toggle, indexed starting from zero.
  :return: Whether the bit is set or not.

  Toggles the *idx*-th bit in the bitmap and returns whether the bit is
  set or not.

  Example:

  .. code-block:: pycon

      >>> bitmap = Bitmap()
      >>> bitmap.data.toggle_bit(10)  # Toggle the 10th bit.
      True
      >>> bitmap.data.toggle_bit(10)  # This will clear the 10th bit.
      False

:param int idx: Bit index, indexed starting from zero.
  :return: Whether the bit is set or not.

  Returns boolean indicating whether the *idx*-th bit is set or not.

Same as :meth:`~BigBitField.is_set`

Set the bit at ``idx`` to value (True or False).

Same as :meth:`~BigBitField.clear_bit`

Return the length of the bitmap **in bytes**.

Returns an iterator yielding 1 or 0 for each bit in the bitmap.

:param other: Either :class:`BigBitField`, ``bytes``, ``bytearray``
      or ``memoryview`` object.
  :return: bitwise ``and`` of two bitmaps.

:param other: Either :class:`BigBitField`, ``bytes``, ``bytearray``
      or ``memoryview`` object.
  :return: bitwise ``or`` of two bitmaps.

:param other: Either :class:`BigBitField`, ``bytes``, ``bytearray``
      or ``memoryview`` object.
  :return: bitwise ``xor`` of two bitmaps.

'%Y-%m-%d %H:%M:%S.%f' # year-month-day hour-minute-second.microsecond
  '%Y-%m-%d %H:%M:%S' # year-month-day hour-minute-second
  '%Y-%m-%d %H:%M:%S.%f%z' # ...with timezone offset
  '%Y-%m-%d %H:%M:%S%z' # ...with timezone offset
  '%Y-%m-%d' # year-month-day

Reference the year of the value stored in the column in a query.

  .. code-block:: python

     Blog.select().where(Blog.pub_date.year == 2018)

Reference the month of the value stored in the column in a query.

Reference the day of the value stored in the column in a query.

Reference the hour of the value stored in the column in a query.

Reference the minute of the value stored in the column in a query.

Reference the second of the value stored in the column in a query.

Method that returns a database-specific function call that will allow
  you to work with the given date-time value as a numeric timestamp. This
  can sometimes simplify tasks like date math in a compatible way.

  Example:

  .. code-block:: python

      # Find all events that are exactly 1 hour long.
      query = (Event
               .select()
               .where((Event.start.to_timestamp() + 3600) ==
                      Event.stop.to_timestamp())
               .order_by(Event.start))

:param str date_part: year, month, day, hour, minute or second.
  :return: expression node to truncate date/time to given resolution.

  Truncates the value in the column to the given part. This method is
  useful for finding all rows within a given month, for instance.

'%Y-%m-%d' # year-month-day
  '%Y-%m-%d %H:%M:%S' # year-month-day hour-minute-second
  '%Y-%m-%d %H:%M:%S.%f' # year-month-day hour-minute-second.microsecond

Reference the year of the value stored in the column in a query.

  .. code-block:: python

     Person.select().where(Person.dob.year == 1983)

Reference the month of the value stored in the column in a query.

Reference the day of the value stored in the column in a query.

See :meth:`DateTimeField.to_timestamp`.

See :meth:`DateTimeField.truncate`. Note that only *year*, *month*,
  and *day* are meaningful for :class:`DateField`.

'%H:%M:%S.%f' # hour:minute:second.microsecond
  '%H:%M:%S' # hour:minute:second
  '%H:%M' # hour:minute
  '%Y-%m-%d %H:%M:%S.%f' # year-month-day hour-minute-second.microsecond
  '%Y-%m-%d %H:%M:%S' # year-month-day hour-minute-second

Reference the hour of the value stored in the column in a query.

  .. code-block:: python

     evening_events = Event.select().where(Event.time.hour > 17)

Reference the minute of the value stored in the column in a query.

Reference the second of the value stored in the column in a query.

For Postgresql, to specify a ``GIN`` or ``GIST`` index use ``index_type``:

  .. code-block:: python

      # Postgres only.
      data = JSONField(index=True, index_type='GIN')  # or GIST.

:param key: a dict key (``str``) or array index (``int``).
  :rtype: JSONPath

  Return a :class:`JSONPath` rooted at the given key. Chains:

  .. code-block:: python

     Doc.data['profile']['social']['fb']
     Doc.data['tags'][0]
     Doc.data['tags'][-1]  # negative indices supported on SQLite + Postgresql

:rtype: JSONPath

  Equivalent to chained :meth:`__getitem__`:

  .. code-block:: python

     Doc.data.path('profile', 'social', 'fb')
     # Same as Doc.data['profile']['social']['fb']

Equality on the full document. The right-hand side is serialized
  through ``dumps`` and compared structurally on Postgresql (``jsonb =
  jsonb``) and MySQL (native ``JSON`` comparison). On SQLite and
  MariaDB the comparison is a byte-compare of the stored JSON text.
  On SQLite, peewee canonicalizes values it writes and the right-hand
  side via ``json()`` - JSON written to the table by other tools is
  compared as stored.

  .. code-block:: python

     Doc.select().where(Doc.data == {'k': 'v'})  # structural where supported
     Doc.select().where(Doc.data == None)        # column IS NULL

On SQLite and MariaDB, the full-document equality is a byte
  comparison of the JSON text. Two dictionaries with the same contents
  but different insertion order may *not* match. If you need
  order-insensitive document equality on those backends, pass
  ``dumps=functools.partial(json.dumps, sort_keys=True)`` so both sides
  are canonicalized. On Postgresql and MySQL the comparison is
  structural and key order does not matter.

Return the array length of the root document. See
  :meth:`JSONPath.length` for the per-backend behavior on non-arrays.

Return an UPDATE-clause expression that appends ``value`` to the root
  array. See :meth:`JSONPath.append` for the per-backend SQL and notes.

  .. code-block:: python

     Doc.update(data=Doc.data.append('new')).execute()

Return an UPDATE-clause expression that merges ``value`` into the root
  document. **The semantics intentionally diverge by backend** -
  see the "update divergence" note below.

  .. code-block:: python

     Doc.update(data=Doc.data.update({'new_field': 1})).execute()

Key-existence predicates, supported on **every** backend. Postgresql
  uses ``?`` / ``?&`` / ``?|``, MySQL / MariaDB use ``JSON_CONTAINS_PATH``,
  and SQLite tests ``json_type(field, path) IS NOT NULL`` per key. These
  check for object-key existence; note that Postgresql's ``?`` *also*
  matches a string against the elements of a top-level array, which the
  MySQL and SQLite emulations do not.

  .. code-block:: python

     Doc.select().where(Doc.data.has_key('email'))
     Doc.select().where(Doc.data.has_keys(['env', 'region']))
     Doc.select().where(Doc.data.has_any_keys(['admin', 'staff']))

JSON structural containment. Postgresql uses ``@>`` / ``<@``, MySQL /
  MariaDB use ``JSON_CONTAINS``. SQLite's JSON1 has no containment
  operator, so it is emulated with a registered UDF
  (``_pw_json_contains``) that deserializes and compares each candidate
  row. That means **no index can be used - it is a full table scan**, so
  prefer Postgresql or MySQL for containment queries over large tables.

  .. code-block:: python

     Doc.select().where(Doc.data.contains({'env': 'prod'}))

Doc.create(data={'k': 'v', 'nested': {'a': 1, 'b': 2}})
  Doc.update(data=Doc.data.update({'k': None,
                                   'nested': {'b': 99}})).execute()

  # SQLite / MySQL / MariaDB:
  #   {'nested': {'a': 1, 'b': 99}}      ('k' deleted, nested merged)
  # Postgresql:
  #   {'k': None, 'nested': {'b': 99}}   ('k' kept as null, nested overwritten)

Extend the path with another key:

  .. code-block:: python

     Doc.data['profile']['social']     # path = ('profile', 'social')
     Doc.data['tags'][0]               # path = ('tags', 0)

Variadic equivalent of chained :meth:`__getitem__`:

  .. code-block:: python

     Doc.data.path('profile', 'social', 'fb')

:rtype: JSONPath

  Return the path value in *text mode*. SQL emission switches to the
  text-extract operator (``->>`` on SQLite, ``#>>`` on Postgresql,
  ``JSON_UNQUOTE(JSON_EXTRACT(...))`` on MySQL). In text mode, the returned
  value is a raw scalar (no JSON quoting) and equality is byte-text
  compare.

  .. code-block:: python

     Doc.data['name'].as_text() == 'alice'
     Doc.data['name'].as_text().ilike('h%')

  Pattern-matching operators (:meth:`like`, :meth:`ilike`,
  :meth:`startswith`, :meth:`endswith`, :meth:`regexp`,
  :meth:`iregexp`) automatically apply ``as_text()`` so calling them on
  a path does the right thing without needing ``.as_text()`` explicitly.
  :meth:`contains` is **not** among them - on a default-mode path it
  performs JSON structural containment. In text mode it is a substring
  match, so for a substring test use ``.as_text().contains(...)``.

:rtype: Cast

  Return the path's text extract cast to the backend's integer type. Use
  for numeric comparisons:

  .. code-block:: python

     Doc.select().where(Doc.data['count'].as_int() > 10)
     Doc.select().order_by(Doc.data['count'].as_int())

:rtype: Cast

  Return the path's text extract cast to the backend's floating-point
  type.

  .. code-block:: python

     Doc.select().where(Doc.data['rating'].as_float() > 4.5)

Equality on the path. In default (JSON) mode the right-hand side is
  canonicalized to match the extract (``fn.json(...)`` on SQLite, the
  psycopg ``Jsonb`` adapter on Postgresql, ``JSON_COMPACT`` on MariaDB,
  ``CAST(... AS JSON)`` on MySQL) so the comparison works across
  backends:

  .. code-block:: python

     Doc.select().where(Doc.data['name'] == 'alice')
     Doc.select().where(Doc.data['count'] == 42)
     Doc.select().where(Doc.data['profile'] == {'fb': 'alice.cat'})

  In ``.as_text()`` mode the right-hand side is compared as plain text.

  Comparison against ``None`` is special, see :meth:`is_null`.

Path-level "is empty" check. Matches rows where the extracted value
  is effectively absent, covering three distinct storage states:

  * Underlying column is SQL ``NULL``.
  * The key is missing from the JSON document.
  * The key is present but the stored value is JSON ``null``.

  All three return Python ``None`` when extracted, and ``is_null()``
  matches them uniformly. ``is_null(False)`` matches rows where the
  path resolves to a non-null Python value.

  .. code-block:: python

     # Rows where data['profile'] is missing, null, or column is NULL.
     Doc.select().where(Doc.data['profile'].is_null())

     # Rows where data['profile'] has a non-null value.
     Doc.select().where(Doc.data['profile'].is_null(False))

  ``path == None`` and ``path != None`` are equivalent to ``is_null()``
  and ``is_null(False)`` respectively.

On MySQL and MariaDB, extracting a stored JSON ``null`` yields the
  string ``'null'`` rather than SQL ``NULL``, so :meth:`is_null` does
  **not** match stored JSON nulls there. Missing keys and column SQL
  ``NULL`` are matched as documented.

Membership test. In default mode each right-hand-side element is
  canonicalized through the field's value wrapper. In ``.as_text()``
  mode elements are compared as plain text.

  .. code-block:: python

     Doc.select().where(Doc.data['name'].in_(['alice', 'bob']))

Ordering and range comparisons. The right-hand side is canonicalized
  the same way as for equality. Per-backend behavior:

  * **Postgresql** - structural ``jsonb`` ordering (type class then value).
  * **MySQL** - JSON-typed comparison rules.
  * **SQLite and MariaDB** - text comparison of the json-encoded value.
    ``'10' > '2'`` is lexicographic, **which is rarely what you want**.

  For portable strict-numeric ordering, use :meth:`as_int` or
  :meth:`as_float` first:

  .. code-block:: python

     # Backend-native ordering (lexicographic on SQLite!)
     Doc.select().where(Doc.data['count'] > 10)

     # Strict numeric ordering on every backend.
     Doc.select().where(Doc.data['count'].as_int() > 10)

Pattern-matching operators. Each automatically applies ``as_text()``
  to the path before comparing. On SQLite, ``regexp()`` and
  ``iregexp()`` require the database be created with
  ``regexp_function=True``.

  .. code-block:: python

     Doc.select().where(Doc.data['name'].ilike('h%'))
     Doc.select().where(Doc.data['name'].regexp(r'^h'))

Substring shortcuts that wrap the right-hand side in ``%`` wildcards.
  Like :meth:`like`, they auto-route through ``as_text()``:

  .. code-block:: python

     Doc.select().where(Doc.data['name'].startswith('h'))

JSON structural containment - ``@>`` on Postgresql, ``JSON_CONTAINS``
  on MySQL / MariaDB, and a full-scan ``_pw_json_contains`` UDF on SQLite.
  On a text-mode path (``.as_text()``) it is a substring ``LIKE`` instead.

  .. code-block:: python

     # JSON structural containment (sub-array membership).
     Doc.select().where(Doc.data['tags'].contains(['python']))

     # For a text substring test, drop to text mode instead:
     Doc.select().where(Doc.data['name'].as_text().contains('uey'))

Return an UPDATE-clause expression that writes ``value`` at this path.
  Uses ``json_set`` / ``jsonb_set`` / ``JSON_SET`` per backend. Existing
  values are replaced, ``value=None`` writes JSON ``null`` (not SQL
  NULL):

  .. code-block:: python

     Doc.update(data=Doc.data['count'].set(99)).execute()
     Doc.update(data=Doc.data['profile'].set({'env': 'prod'})).execute()

  .. note::

     Behavior when intermediate keys are missing diverges:
     ``data['a']['b'].set(1)`` on ``data={}`` creates the full chain on
     SQLite (``{"a": {"b": 1}}``), but is a silent no-op on Postgresql
     and MySQL / MariaDB, which only create the leaf when its parent
     already exists.

Return an UPDATE-clause expression that writes ``value`` at this path
  **only if the path is currently absent**. A stored JSON ``null``
  counts as "present" and is not overwritten. Uses ``json_insert`` on
  SQLite and ``JSON_INSERT`` on MySQL / MariaDB, emulated on Postgresql
  via ``CASE WHEN (field #> '{k}') IS NULL THEN jsonb_set(...) ELSE field
  END`` (correct because ``#>`` returns SQL ``NULL`` for absent keys
  and jsonb ``'null'`` for stored JSON nulls).

  .. code-block:: python

     # Initialize a counter only on rows that don't have one yet.
     Doc.update(data=Doc.data['count'].insert(0)).execute()

Return an UPDATE-clause expression that writes ``value`` at this path
  **only if the path already exists**. Uses ``json_replace`` on SQLite,
  ``jsonb_set(..., create_missing=false)`` on Postgresql, and
  ``JSON_REPLACE`` on MySQL / MariaDB.

  .. code-block:: python

     # Update existing counters. Leave rows without one untouched.
     Doc.update(data=Doc.data['count'].replace(99)).execute()

Return an UPDATE-clause expression that appends ``value`` to the
  array at this path. Uses ``json_set(field, '$.path[#]', value)`` on
  SQLite, ``jsonb_insert`` with a trailing ``'-1'`` path element on
  Postgresql, and ``JSON_ARRAY_APPEND`` on MySQL / MariaDB.

  .. code-block:: python

     Doc.update(data=Doc.data['tags'].append('python')).execute()

  .. note::

     Behavior when the path holds a non-array value diverges across
     backends:

     * **SQLite** - silently leaves the document unchanged.
     * **MySQL / MariaDB** - wraps the existing value into an array
       before appending: ``{"a": 1}`` becomes ``{"a": [1, "x"]}``.
     * **Postgresql** - silently leaves scalars unchanged, but
       appending to an *object* inserts a literal ``"-1"`` key:
       ``{"a": {"b": 1}}`` becomes ``{"a": {"b": 1, "-1": "x"}}``.

     Use only on values you know are arrays.

  .. warning::

     Appending at a path that does not exist at all also diverges.
     SQLite creates a new single-element array. Postgresql and MySQL
     leave the document unchanged. On MariaDB ``JSON_ARRAY_APPEND``
     returns SQL NULL for a missing path, so the update **overwrites
     the entire column with NULL**. If the key may be missing,
     initialize the array with :meth:`set` first.

Return an UPDATE-clause expression that removes the value at this path.
  Uses ``json_remove`` / ``#-`` / ``JSON_REMOVE`` per backend.

  .. code-block:: python

     Doc.update(data=Doc.data['stale_key'].remove()).execute()

Return the array length at this path. On non-array values the result
  diverges by backend:

  * **SQLite** - returns ``0`` for non-arrays.
  * **Postgresql** - raises ``cannot get array length of a non-array``.
  * **MySQL / MariaDB** - returns object key count for objects,
    ``1`` for scalars.

  Use only on values you know are arrays, or be prepared for the
  backend-specific semantics.

  .. code-block:: python

     Doc.select(Doc.data['tags'].length().alias('n_tags'))

Inverse of :meth:`contains` - test whether the value at this path is a
  subset of ``value``. Postgresql ``<@``, MySQL / MariaDB
  ``JSON_CONTAINS(value, lhs)``, SQLite the ``_pw_json_contains`` UDF
  (full scan).

  .. code-block:: python

     Doc.select().where(Doc.data['tags'].contained_by(
         ['python', 'orm', 'sql']))

Test whether the value at this path is an object containing the given
  key(s). Supported on all backends: Postgresql uses the ``?`` / ``?&`` /
  ``?|`` operators, MySQL / MariaDB use ``JSON_CONTAINS_PATH``, and SQLite
  tests ``json_type()`` per key.

  .. code-block:: python

     Doc.select().where(Doc.data.has_key('email'))
     Doc.select().where(Doc.data['profile'].has_keys(['env', 'region']))
     Doc.select().where(Doc.data.has_any_keys(['admin', 'staff']))

class User(Model):
      name = TextField()

  class Tweet(Model):
      user = ForeignKeyField(User, backref='tweets')
      content = TextField()

  # "user" attribute
  >>> some_tweet.user
  

  # "tweets" backref attribute
  >>> for tweet in charlie.tweets:
  ...     print(tweet.content)
  Some tweet
  Another tweet
  Yet another tweet

class Husband(Model):
      name = TextField()
      wife = DeferredForeignKey('Wife', deferrable='INITIALLY DEFERRED')

  class Wife(Model):
      name = TextField()
      husband = ForeignKeyField(Husband, deferrable='INITIALLY DEFERRED')

class User(Model):
      username = TextField()

  class Tweet(Model):
      # This will never actually be resolved, because the User
      # model has already been declared.
      user = DeferredForeignKey('user', backref='tweets')
      content = TextField()

# Tweet.user will be resolved into a ForeignKeyField:
  DeferredForeignKey.resolve(User)

class Student(Model):
      name = CharField()

  class Course(Model):
      name = CharField()

  class StudentCourse(Model):
      student = ForeignKeyField(Student)
      course = ForeignKeyField(Course)

# List the courses that "Alice" is enrolled in:
  courses = (Course
             .select()
             .join(StudentCourse)
             .join(Student)
             .where(Student.name == 'Alice'))
  for course in courses:
      print(course.name)

class Student(Model):
      name = CharField()

  class Course(Model):
      name = CharField()
      students = ManyToManyField(Student, backref='courses')

# Create tables for the students, courses, and relationships between
  # the two.
  db.create_tables([
      Student,
      Course,
      Course.students.get_through_model()])

>>> alice = Student.get(Student.name == 'alice')
  >>> [course.name for course in alice.courses]
  ['English 101', 'CS 101']

  >>> engl_101 = Course.get(Course.name == 'English 101')
  >>> [student.name for student in engl_101.students]
  ['Alice', 'Bob', 'Carol']

>>> alice.courses = Course.select().where(Course.name.contains('english'))
  >>> for course in alice.courses.order_by(Course.name):
  ...     print(course.name)
  English 101
  English 151
  English 201
  English 221

  >>> cs_101 = Course.get(Course.name == 'CS 101')
  >>> cs_151 = Course.get(Course.name == 'CS 151')
  >>> alice.courses.add([cs_101, cs_151])
  >>> [course.name for course in alice.courses.order_by(Course.name)]
  ['CS 101', 'CS 151', 'English 101', 'English 151', 'English 201',
   'English 221']

>>> alice.courses.remove(Course.select().where(Course.name.contains('2')))
  2
  >>> [course.name for course in alice.courses.order_by(Course.name)]
  ['CS 101', 'CS 151', 'English 101', 'English 151']

>>> engl_101 = Course.get(Course.name == 'English 101')
  >>> engl_101.students.clear()

The :class:`Model` representing the many-to-many junction table.
  Will be auto-generated if not explicitly declared.

:param value: Either a :class:`Model` instance, a list of model
      instances, or a :class:`SelectQuery`.
  :param bool clear_existing: Whether to remove existing relationships.

  Associate ``value`` with the current instance. You can pass in a single
  model instance, a list of model instances, or even a :class:`ModelSelect`.

  Example code:

  .. code-block:: python

     # Alice needs to enroll in a bunch of courses, including all
     # the English classes, and a couple Comp-Sci classes.
     alice = Student.get(Student.name == 'Alice')

     # We can add all the objects represented by a query.
     english_courses = Course.select().where(
         Course.name.contains('english'))
     alice.courses.add(english_courses)

     # We can also add lists of individual objects.
     cs101 = Course.get(Course.name == 'CS 101')
     cs151 = Course.get(Course.name == 'CS 151')
     alice.courses.add([cs101, cs151])

:param value: Either a :class:`Model` instance, a list of model
      instances, or a :class:`ModelSelect`.

  Disassociate ``value`` from the current instance. Like
  :meth:`~ManyToManyField.add`, you can pass in a model instance, a
  list of model instances, or even a :class:`ModelSelect`.

  Example code:

  .. code-block:: python

     # Alice is currently enrolled in a lot of english classes
     # as well as some Comp-Sci. He is changing majors, so we
     # will remove all his courses.
     english_courses = Course.select().where(
         Course.name.contains('english'))
     alice.courses.remove(english_courses)

     # Remove the two Comp-Sci classes Alice is enrolled in.
     cs101 = Course.get(Course.name == 'CS 101')
     cs151 = Course.get(Course.name == 'CS 151')
     alice.courses.remove([cs101, cs151])

Remove all associated objects.

  Example code:

  .. code-block:: python

     # English 101 is canceled this semester, so remove all
     # the enrollments.
     english_101 = Course.get(Course.name == 'English 101')
     english_101.students.clear()

Return the :class:`Model` representing the many-to-many junction
  table. This can be specified manually when the field is being
  instantiated using the ``through_model`` parameter. If a
  ``through_model`` is not specified, one will automatically be created.

  When creating tables for an application that uses
  :class:`ManyToManyField`, **you must explicitly create the through table**.

  .. code-block:: python

     # Get a reference to the automatically-created through table.
     StudentCourseThrough = Course.students.get_through_model()

     # Create tables for our two models as well as the through model.
     db.create_tables([
         Student,
         Course,
         StudentCourseThrough])

class Note(BaseModel):
      content = TextField()

  NoteThroughDeferred = DeferredThroughModel()

  class User(BaseModel):
      username = TextField()
      notes = ManyToManyField(Note, through_model=NoteThroughDeferred)

  # Cannot declare this before "User" since it has a foreign-key to
  # the User model.
  class NoteThrough(BaseModel):
      note = ForeignKeyField(Note)
      user = ForeignKeyField(User)

  # Resolve dependencies.
  NoteThroughDeferred.set_model(NoteThrough)

class BlogTagThrough(Model):
      blog = ForeignKeyField(Blog, backref='tags')
      tag = ForeignKeyField(Tag, backref='blogs')

      class Meta:
          primary_key = CompositeKey('blog', 'tag')

:param bool safe: Specify IF NOT EXISTS clause.
  :param options: Arbitrary options.

  Execute CREATE TABLE query for the given model.

:param bool safe: Specify IF EXISTS clause.
  :param options: Arbitrary options.

  Execute DROP TABLE query for the given model.

:param bool restart_identity: Restart the id sequence (postgres-only).
  :param bool cascade: Truncate related tables as well (postgres-only).

  Execute TRUNCATE TABLE for the given model. If the database is Sqlite,
  which does not support TRUNCATE, then an equivalent DELETE query will
  be executed.

:param bool safe: Specify IF NOT EXISTS clause.

  Execute CREATE INDEX queries for the indexes defined for the model.

:param bool safe: Specify IF EXISTS clause.

  Execute DROP INDEX queries for the indexes defined for the model.

:param Field field: field index to drop (for single-column indexes).
  :param ModelIndex index: index to drop (for indexes other than
     single-column, e.g. multi-col, partial, etc).
  :param bool safe: Specify IF EXISTS clause.

  Execute DROP INDEX query for the index specified.

:param Field field: Field instance which specifies a sequence.

  Create sequence for the given :class:`Field`.

:param Field field: Field instance which specifies a sequence.

  Drop sequence for the given :class:`Field`.

:param ForeignKeyField field: Foreign-key field constraint to add.

  Add a foreign-key constraint for the given field. This method should
  not be necessary in most cases, as foreign-key constraints are created
  as part of table creation. The exception is when you are creating a
  circular foreign-key relationship using :class:`DeferredForeignKey`.
  In those cases, it is necessary to first create the tables, then add
  the constraint for the deferred foreign-key:

  .. code-block:: python

     class Language(Model):
         name = TextField()
         selected_snippet = DeferredForeignKey('Snippet')

     class Snippet(Model):
         code = TextField()
         language = ForeignKeyField(Language, backref='snippets')

     # Creates both tables but does not create the constraint for the
     # Language.selected_snippet foreign key (because of the circular
     # dependency).
     db.create_tables([Language, Snippet])

     # Explicitly create the constraint:
     Language._schema.create_foreign_key(Language.selected_snippet)

  For more information, see documentation on :ref:`circular-fks`.

  Because SQLite has limited support for altering existing tables, it
  is not possible to add a foreign-key constraint to an existing
  SQLite table.

:param bool safe: Whether to specify IF NOT EXISTS.

  Create sequence(s), index(es) and table for the model.

:param bool safe: Whether to specify IF EXISTS.
  :param bool drop_sequences: Drop any sequences associated with the
      columns on the table (postgres only).
  :param options: Arbitrary options.

  Drop table for the model and associated indexes.

:param str table_name: Name of the new table.
  :param Select query: Query whose result set will populate the new
      table.
  :param bool safe: Specify IF NOT EXISTS clause.
  :param meta: Additional table options forwarded to the context.

  Execute ``CREATE TABLE ... AS SELECT ...`` for the given model. The
  new table's schema and column names are derived from the SELECT
  query's result set.

Create every sequence referenced by a field on the model. On
  databases where :attr:`Database.sequences` is ``False`` this method
  is a no-op. Called implicitly by :meth:`create_all`.

Drop every sequence referenced by a field on the model. On
  databases where :attr:`Database.sequences` is ``False`` this method
  is a no-op. Called implicitly by :meth:`drop_all`.

:param bool _safe: Whether to add IF NOT EXISTS clause.

:param expressions: zero or more expressions to include in the WHERE
      clause.

  Include the given expressions in the WHERE clause of the index. The
  expressions will be AND-ed together with any previously-specified
  WHERE expressions.

:param str _using: Specify index algorithm for USING clause.

:param bool nulls_distinct: specify True (NULLS DISTINCT) or False
      for (NULLS NOT DISTINCT).

  Requires Postgres 15 or newer.

  Control handling of NULL values in unique indexes.

class Article(Model):
      name = TextField()
      timestamp = TimestampField()
      status = IntegerField()
      flags = BitField()

      is_sticky = flags.flag(1)
      is_favorite = flags.flag(2)

  # CREATE INDEX ... ON "article" ("name", "timestamp")
  idx = ModelIndex(Article, (Article.name, Article.timestamp))

  # CREATE INDEX ... ON "article" ("name", "timestamp") WHERE "status" = 1
  idx = idx.where(Article.status == 1)

  # CREATE UNIQUE INDEX ... ON "article" ("timestamp" DESC, "flags" & 2) WHERE "status" = 1
  idx = ModelIndex(
      Article,
      (Article.timestamp.desc(), Article.flags.bin_and(2)),
      unique = True).where(Article.status == 1)

idx = Article.index(Article.name, Article.timestamp).where(Article.status == 1)

idx = Article.index(Article.name, Article.timestamp).where(Article.status == 1)

  # Add above index definition to the model definition. When you call
  # Article.create_table() (or database.create_tables([Article])), the
  # index will be created.
  Article.add_index(idx)

Decorator to use with Node methods that mutate the node's state.
  This allows method-chaining, e.g.:

  .. code-block:: python

      query = MyModel.select()
      new_query = query.where(MyModel.field == 'value')

API for recursively unwrapping "wrapped" nodes. Base case is to
  return self.

API for determining if a node, at any point, has been explicitly
  aliased by the user.

User = Table('users')
  query = (User
           .select(User.c.username)
           .where(User.c.active == True)
           .order_by(User.c.username))

Returns a copy of the object with the given alias applied.

:param columns: :class:`Column` instances, expressions, functions,
      sub-queries, or anything else that you would like to select.

  Create a :class:`Select` query on the table. If the table explicitly
  declares columns and no columns are provided, then by default all the
  table's defined columns will be selected.

:param Source dest: Join the table with the given destination.
  :param str join_type: Join type.
  :param on: Expression to use as join predicate.
  :return: a :class:`Join` instance.

  Join type may be one of:

  * ``JOIN.INNER``
  * ``JOIN.LEFT_OUTER``
  * ``JOIN.RIGHT_OUTER``
  * ``JOIN.FULL``
  * ``JOIN.FULL_OUTER``
  * ``JOIN.CROSS``

:param Source dest: Join the table with the given destination.
  :param on: Expression to use as join predicate.
  :return: a :class:`Join` instance.

  Convenience method for calling :meth:`~Source.join` using a LEFT
  OUTER join.

Perform an INNER join on ``dest``.

Perform a LEFT OUTER join on ``dest``.

Perform a RIGHT OUTER join on ``dest``.

Perform a FULL OUTER join on ``dest``.

Perform a CROSS join on ``dest``.

User = Table('users')
  query = (User
           .select(User.c.id, User.c.username)
           .order_by(User.c.username))

User = Table('users', ('id', 'username'))
  query = (User
           .select(User.id, User.username)
           .order_by(User.username))

:param database: :class:`Database` object.

  Bind this table to the given database (or unbind by leaving empty).

  When a table is *bound* to a database, queries may be executed against
  it without the need to specify the database in the query's execute
  method.

:param database: :class:`Database` object.

  Return a context manager that will bind the table to the given database
  for the duration of the wrapped block.

:param columns: :class:`Column` instances, expressions, functions,
      sub-queries, or anything else that you would like to select.

  Create a :class:`Select` query on the table. If the table explicitly
  declares columns and no columns are provided, then by default all the
  table's defined columns will be selected.

  Examples:

  .. code-block:: python

     User = Table('users', ('id', 'username'))

     # Because columns were defined on the Table, we will default to
     # selecting both of the User table's columns.
     # Evaluates to SELECT id, username FROM users
     query = User.select()

     Note = Table('notes')
     query = (Note
              .select(Note.c.content, Note.c.timestamp, User.username)
              .join(User, on=(Note.c.user_id == User.id))
              .where(Note.c.is_published == True)
              .order_by(Note.c.timestamp.desc()))

     # Using a function to select users and the number of notes they
     # have authored.
     query = (User
              .select(
                 User.username,
                 fn.COUNT(Note.c.id).alias('n_notes'))
              .join(
                 Note,
                 JOIN.LEFT_OUTER,
                 on=(User.id == Note.c.user_id))
              .order_by(fn.COUNT(Note.c.id).desc()))

:param insert: A dictionary mapping column to value, an iterable that
      yields dictionaries (i.e. list), or a :class:`Select` query.
  :param list columns: The list of columns to insert into when the
      data being inserted is not a dictionary.
  :param kwargs: Mapping of column-name to value.

  Create a :class:`Insert` query into the table.

:param insert: A dictionary mapping column to value, an iterable that
      yields dictionaries (i.e. list), or a :class:`Select` query.
  :param list columns: The list of columns to insert into when the
      data being inserted is not a dictionary.
  :param kwargs: Mapping of column-name to value.

  Create a :class:`Insert` query into the table whose conflict
  resolution method is to replace.

:param update: A dictionary mapping column to value.
  :param kwargs: Mapping of column-name to value.

  Create a :class:`Update` query for the table.

Create a :class:`Delete` query for the table.

:param Expression predicate: join predicate.

   Specify the predicate expression used for this join.

data = [(1, 'first'), (2, 'second')]
  vl = ValuesList(data, columns=('idx', 'name'))

  query = (vl
           .select(vl.c.idx, vl.c.name)
           .order_by(vl.c.idx))
  # Yields:
  # SELECT t1.idx, t1.name
  # FROM (VALUES (1, 'first'), (2, 'second')) AS t1(idx, name)
  # ORDER BY t1.idx

:param names: names to apply to the columns of data.

  Example:

  .. code-block:: python

     vl = ValuesList([(1, 'first'), (2, 'second')])
     vl = vl.columns('idx', 'name').alias('v')

     query = vl.select(vl.c.idx, vl.c.name)
     # Yields:
     # SELECT v.idx, v.name
     # FROM (VALUES (1, 'first'), (2, 'second')) AS v(idx, name)

Create a SELECT query that utilizes the given common table expression
  as the source for a new query.

  :param columns: One or more columns to select from the CTE.
  :return: :class:`Select` query utilizing the common table expression

Used on the base-case CTE to construct the recursive term of the CTE.

  :param other: recursive term, generally a :class:`Select` query.
  :return: a recursive :class:`CTE` with the given recursive term.

:param str alias: Alias for the given column-like object.
  :return: a :class:`Alias` object.

  Indicate the alias that should be given to the specified column-like
  object.

:param dest: Model to bind this expression to when constructing the
     model-graph. Destination must be among the JOINed tables.
  :return: a :class:`BindTo` object encapsulating the binding.

  Bind the current column/expression to a specific model.

  Example:

  .. code-block:: python

     name = Case(User.username, [
         ('u1', 'User One'),
         ('u2', 'User Two')], 'Someone Else')
     query = (Tweet
              .select(Tweet.content, name.alias('display').bind_to(User))
              .join(User))
     for tweet in query:
         print(tweet.content, tweet.user.display)

:param str as_type: Type name to cast to.
  :return: a :class:`Cast` object.

  Create a ``CAST`` expression.

  Example:

  .. code-block:: python

     # Cast a text column to integer for comparison.
     query = (Entry
              .select()
              .where(Entry.legacy_code.cast('INTEGER') > 100))

:param str collation: Collation name to use for sorting.
  :param str nulls: Sort nulls (FIRST or LAST).
  :return: an ascending :class:`Ordering` object for the column.

:param str collation: Collation name to use for sorting.
  :param str nulls: Sort nulls (FIRST or LAST).
  :return: an descending :class:`Ordering` object for the column.

:return: a :class:`Negated` wrapper for the column.

:param str alias: new name (or None) for aliased column.

  Create a new :class:`Alias` for the aliased column-like object. If
  the new alias is ``None``, then the original column-like object is
  returned.

:param str collation: Collation name to use for sorting.

Factory method for creating sub-entities.

# "added" DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP.
 added = DateTimeField(constraints=[Default('CURRENT_TIMESTAMP')])

 # "label" TEXT NOT NULL DEFAULT 'string literal'
 label = TextField(constraints=[Default("'string literal'")])

 # "status" INTEGER NOT NULL DEFAULT 0
 status = IntegerField(constraints=[Default(0)])

# Query users and count of tweets authored.
  query = (User
           .select(User.username, fn.COUNT(Tweet.id).alias('ct'))
           .join(Tweet, JOIN.LEFT_OUTER, on=(User.id == Tweet.user_id))
           .group_by(User.username)
           .order_by(fn.COUNT(Tweet.id).desc()))

:param list partition_by: List of columns to partition by.
  :param list order_by: List of columns / expressions to order window by.
  :param start: A :class:`SQL` instance or a string expressing the
      start of the window range.
  :param end: A :class:`SQL` instance or a string expressing the
      end of the window range.
  :param str frame_type: ``Window.RANGE``, ``Window.ROWS`` or
      ``Window.GROUPS``.
  :param Window window: A :class:`Window` instance.
  :param exclude: Frame exclusion, one of ``Window.CURRENT_ROW``,
      ``Window.GROUP``, ``Window.TIES`` or ``Window.NO_OTHERS``.

  For an in-depth guide to using window functions with Peewee,
  see the :ref:`window-functions` section.

  Examples:

  .. code-block:: python

     # Using a simple partition on a single column.
     query = (Sample
              .select(
                 Sample.counter,
                 Sample.value,
                 fn.AVG(Sample.value).over([Sample.counter]))
              .order_by(Sample.counter))

     # Equivalent example Using a Window() instance instead.
     window = Window(partition_by=[Sample.counter])
     query = (Sample
              .select(
                 Sample.counter,
                 Sample.value,
                 fn.AVG(Sample.value).over(window))
              .window(window)  # Note call to ".window()"
              .order_by(Sample.counter))

     # Example using bounded window.
     query = (Sample
              .select(Sample.value,
                      fn.SUM(Sample.value).over(
                         partition_by=[Sample.counter],
                         start=Window.CURRENT_ROW,  # current row
                         end=Window.following()))  # unbounded following
              .order_by(Sample.id))

:param where: Expression for filtering aggregate.

  Add a ``FILTER (WHERE...)`` clause to an aggregate function. The where
  expression is evaluated to determine which rows are fed to the
  aggregate function. This SQL feature is supported for Postgres and
  SQLite.

:param ordering: Column(s) or expression(s) to order the aggregate's
      input by.

  Add an ``ORDER BY`` clause inside an aggregate function call:

  .. code-block:: python

     # GROUP_CONCAT("t1"."content" ORDER BY "t1"."timestamp")
     fn.GROUP_CONCAT(Tweet.content).order_by(Tweet.timestamp)

:param bool _coerce: Whether to attempt to coerce function-call result
      to a Python data-type.

  When coerce is ``True``, the target data-type is inferred using several
  heuristics. Read the source for ``BaseModelCursorWrapper._initialize_columns``
  method to see how this works.

:param callable python_value: Function to use for converting the return
      value from the cursor.

  Specify a particular function to use when converting values returned by
  the database cursor. For example:

  .. code-block:: python

     # Get user and a list of their tweet IDs. The tweet IDs are
     # returned as a comma-separated string by the db, so we'll split
     # the result string and convert the values to python ints.
     convert_ids = lambda s: [int(i) for i in (s or '').split(',') if i]
     tweet_ids = (fn
                  .GROUP_CONCAT(Tweet.id)
                  .python_value(convert_ids))

     query = (User
              .select(User.username, tweet_ids.alias('tweet_ids'))
              .join(Tweet)
              .group_by(User.username))

     for user in query:
         print(user.username, user.tweet_ids)

     # e.g.,
     # alice [1, 4, 5, 7]
     # bob [2, 3, 6]
     # carol []

# List users and the number of tweets they have authored,
  # from highest-to-lowest:
  sql_count = fn.COUNT(Tweet.id)
  query = (User
           .select(User, sql_count.alias('count'))
           .join(Tweet, JOIN.LEFT_OUTER)
           .group_by(User)
           .order_by(sql_count.desc()))

  # Get the timestamp of the most recent tweet:
  query = Tweet.select(fn.MAX(Tweet.timestamp))
  max_timestamp = query.scalar()  # Retrieve scalar result from query.

# Get users whose username begins with "A" or "a":
  a_users = User.select().where(fn.LOWER(fn.SUBSTR(User.username, 1, 1)) == 'a')

Specify the window ``frame_type``. See :ref:`window-frame-types`.

Reference to current row for use in start/end clause or the frame
  exclusion parameter.

Specify the window frame exclusion parameter.

:param value: Number of rows preceding. If ``None`` is UNBOUNDED.

  Convenience method for generating SQL suitable for passing in as the
  ``start`` parameter for a window range.

:param value: Number of rows following. If ``None`` is UNBOUNDED.

  Convenience method for generating SQL suitable for passing in as the
  ``end`` parameter for a window range.

Specify the frame type.

:param Window window: A :class:`Window` definition to extend.
      Alternately, you may specify the window's alias instead.

:param frame_exclusion: Frame exclusion, one of ``Window.CURRENT_ROW``,
      ``Window.GROUP``, ``Window.TIES`` or ``Window.NO_OTHERS``.

:param str alias: Alias to use for window.

Number = Table('numbers', ('val',))

  num_as_str = Case(Number.val, (
      (1, 'one'),
      (2, 'two'),
      (3, 'three')), 'a lot')

  query = Number.select(Number.val, num_as_str.alias('num_str'))

SELECT "val",
    CASE "val"
        WHEN 1 THEN 'one'
        WHEN 2 THEN 'two'
        WHEN 3 THEN 'three'
        ELSE 'a lot' END AS "num_str"
  FROM "numbers"

num_as_str = Case(None, (
      (Number.val == 1, 'one'),
      (Number.val == 2, 'two'),
      (Number.val == 3, 'three')), 'a lot')
  query = Number.select(Number.val, num_as_str.alias('num_str'))

SELECT "val",
    CASE
        WHEN "val" = 1 THEN 'one'
        WHEN "val" = 2 THEN 'two'
        WHEN "val" = 3 THEN 'three'
        ELSE 'a lot' END AS "num_str"
  FROM "numbers"

:param columns: Columns whose values should be preserved.

:param dict _data: Dictionary mapping column to new value.
  :param kwargs: Dictionary mapping column name to new value.

  The ``update()`` method supports being called with either a dictionary
  of column-to-value, **or** keyword arguments representing the same.

:param expressions: Expressions that restrict the action of the
      conflict resolution clause.

:param constraints: Column(s) to use as target for conflict resolution.

:param expressions: Expressions that match the conflict target index,
      in the case the conflict target is a partial index.

:param str constraint: Name of constraints to use as target for
      conflict resolution. Currently only supported by Postgres.

:param Database database: Database to execute query against.

  Bind the query to the given database for execution.

:param bool as_dict: Specify whether to return rows as dictionaries.

  Return rows as dictionaries.

:param bool as_tuple: Specify whether to return rows as tuples.

  Return rows as tuples.

:param bool as_namedtuple: Specify whether to return rows as named
      tuples.

  Return rows as named tuples.

:param constructor: Function that accepts row dict and returns an
      arbitrary object.

  Return rows as arbitrary objects using the given constructor.

:return: A 2-tuple consisting of the query's SQL and parameters.

:param Database database: Database to execute query against. Not
      required if query was previously bound to a database.

  Execute the query and return result (depends on type of query being
  executed). For example, select queries the return result will be an
  iterator over the query results.

Async counterpart of :py:meth:`execute`, for queries bound to an
  asyncio-compatible database. See :ref:`pwasyncio`.

:param Database database: Database to execute query against. Not
      required if query was previously bound to a database.

  Execute the query and return an iterator over the result-set. For large
  result-sets this method is preferable as rows are not cached in-memory
  during iteration.

  Because rows are not cached, the query may only be iterated over
  once. Subsequent iterations will return empty result-sets as the
  cursor will have been consumed.

  Example:

  .. code-block:: python

     query = StatTbl.select().order_by(StatTbl.timestamp).tuples()
     for row in query.iterator(db):
         process_row(row)

Execute the query and return an iterator over the result-set.

  Unlike :meth:`~BaseQuery.iterator`, this method will cause rows to
  be cached in order to allow efficient iteration, indexing and slicing.

:param value: Either an integer index or a slice.

  Retrieve a row or range of rows from the result-set.

Return the number of rows in the result-set.

  This does not issue a ``COUNT()`` query. Instead, the result-set
  is loaded as it would be during normal iteration, and the length
  is determined from the size of the result set.

:param cte_list: zero or more :class:`CTE` objects.

  Include the given common-table expressions in the query. Any previously
  specified CTEs will be overwritten. For examples of common-table
  expressions, see :ref:`cte`.

:param str name: Alias for common table expression.
  :param bool recursive: Will this be a recursive CTE?
  :param list columns: List of column names (as strings).
  :param bool materialized: Specify ``MATERIALIZED`` or ``NOT MATERIALIZED``
      clause.

  Indicate that a query will be used as a common table expression. For
  example, if we are modelling a category tree and are using a
  parent-link foreign key, we can retrieve all categories and their
  absolute depths using a recursive CTE:

  .. code-block:: python

     class Category(Model):
         name = TextField()
         parent = ForeignKeyField('self', backref='children', null=True)

     # The base case of our recursive CTE will be categories that are at
     # the root level -- in other words, categories without parents.
     roots = (Category
              .select(Category.name, Value(0).alias('level'))
              .where(Category.parent.is_null())
              .cte(name='roots', recursive=True))

     # The recursive term will select the category name and increment
     # the depth, joining on the base term so that the recursive term
     # consists of all children of the base category.
     RTerm = Category.alias()
     recursive = (RTerm
                  .select(RTerm.name, (roots.c.level + 1).alias('level'))
                  .join(roots, on=(RTerm.parent == roots.c.id)))

     # Express  UNION ALL <recursive term>.
     cte = roots.union_all(recursive)

     # Select name and level from the recursive CTE.
     query = (cte
              .select_from(cte.c.name, cte.c.level)
              .order_by(cte.c.name))

     for category in query:
         print(category.name, category.level)

  For more examples of CTEs, see :ref:`cte`.

:param expressions: zero or more expressions to include in the WHERE
      clause.

  Include the given expressions in the WHERE clause of the query. The
  expressions will be AND-ed together with any previously-specified
  WHERE expressions.

  Example selection users where the username is equal to 'somebody':

  .. code-block:: python

     sq = User.select().where(User.username == 'somebody')

  Example selecting tweets made by users who are either editors or
  administrators:

  .. code-block:: python

     sq = Tweet.select().join(User).where(
         (User.is_editor == True) |
         (User.is_admin == True))

  Example of deleting tweets by users who are no longer active:

  .. code-block:: python

     inactive_users = User.select().where(User.active == False)
     dq = (Tweet
           .delete()
           .where(Tweet.user.in_(inactive_users)))
     dq.execute()  # Return number of tweets deleted.

  :meth:`~Query.where` calls are chainable.  Multiple calls will
  be "AND"-ed together.

:param expressions: zero or more expressions to include in the WHERE
      clause.

  Include the given expressions in the WHERE clause of the query. This
  method is the same as the :meth:`Query.where` method, except that
  the expressions will be OR-ed together with any previously-specified
  WHERE expressions.

  Example:

  .. code-block:: python

     query = (User
              .select()
              .where(User.is_admin == True)
              .orwhere(User.is_moderator == True))

:param values: zero or more Column-like objects to order by.

  Define the ORDER BY clause. Any previously-specified values will be
  overwritten.

:param values: zero or more Column-like objects to order by.

  Extend any previously-specified ORDER BY clause with the given values.

:param int value: specify value for LIMIT clause.

:param int value: specify value for OFFSET clause.

:param int page: Page number of results (starting from 1).
  :param int paginate_by: Rows-per-page.

  Convenience method for specifying the LIMIT and OFFSET in a more
  intuitive way.

  This feature is designed with web-site pagination in mind, so the first
  page starts with ``page=1``.

  Example:

  .. code-block:: python

     @app.route('/users/')
     def users():
         query = User.select().order_by(User.username)
         page = request.args.get('page')
         if page and page.isdigit():
             page = max(1, int(page))
         else:
             page = 1

         # Render the requested page of results, displaying up to
         # 20 users per page.
         return render('users.html', users=query.paginate(page, 20))

:param columns: one or more columns to select from the inner query.
  :return: a new query that wraps the calling query.

  Create a new query that wraps the current (calling) query. For example,
  suppose you have a simple ``UNION`` query, and need to apply an
  aggregation on the union result-set. To do this, you need to write
  something like:

  .. code-block:: sql

     SELECT "u"."owner", COUNT("u"."id") AS "ct"
     FROM (
         SELECT "id", "owner", ... FROM "cars"
         UNION
         SELECT "id", "owner", ... FROM "motorcycles"
         UNION
         SELECT "id", "owner", ... FROM "boats") AS "u"
     GROUP BY "u"."owner"

  The :meth:`~SelectQuery.select_from` method is designed to simplify
  constructing this type of query.

  Example peewee code:

  .. code-block:: python

     class Car(Model):
         owner = ForeignKeyField(Owner, backref='cars')
         # ... car-specific fields, etc ...

     class Motorcycle(Model):
         owner = ForeignKeyField(Owner, backref='motorcycles')
         # ... motorcycle-specific fields, etc ...

     class Boat(Model):
         owner = ForeignKeyField(Owner, backref='boats')
         # ... boat-specific fields, etc ...

     cars = Car.select(Car.owner)
     motorcycles = Motorcycle.select(Motorcycle.owner)
     boats = Boat.select(Boat.owner)

     union = cars | motorcycles | boats

     query = (union
              .select_from(union.c.owner, fn.COUNT(union.c.id))
              .group_by(union.c.owner))

Create a UNION ALL query with ``dest``.

Create a UNION ALL query with ``dest``.

Create a UNION query with ``dest``.

Create a UNION query with ``dest``.

Create an INTERSECT query with ``dest``.

Create an INTERSECT query with ``dest``.

Create an EXCEPT query with ``dest``. Note that the method name has a
  trailing "_" character since ``except`` is a Python reserved word.

Create an EXCEPT query with ``dest``.

:param Database database: database to execute query against.
  :param int n: Number of rows to return.
  :return: A single row if n = 1, else a list of rows.

  Execute the query and return the given number of rows from the start
  of the cursor. This function may be called multiple times safely, and
  will always return the first N rows of results.

:param Database database: database to execute query against.
  :param int n: Number of rows to return.
  :return: A single row if n = 1, else a list of rows.

  Like the :meth:`~SelectBase.peek` method, except a ``LIMIT`` is
  applied to the query to ensure that only ``n`` rows are returned.
  Multiple calls for the same value of ``n`` will not result in multiple
  executions.

  The query is altered in-place so it is not possible to call
  :meth:`~SelectBase.first` and then later iterate over the full
  result-set using the same query object. Again, this is done to ensure
  that multiple calls to ``first()`` will not result in multiple query
  executions.

:param Database database: database to execute query against.
  :param bool as_tuple: Return the result as a tuple?
  :param bool as_dict: Return the result as a dict?
  :return: Single scalar value. If ``as_tuple = True``, a row tuple is
      returned. If ``as_dict = True``, a row dict is returned.

  Return a scalar value from the first row of results. If multiple
  scalar values are anticipated (e.g. multiple aggregations in a single
  query) then you may specify ``as_tuple=True`` to get the row tuple.

  A ``LIMIT 1`` is applied internally, so only a single row is
  requested from the database (the query itself is not mutated).

  Example:

  .. code-block:: python

     query = Note.select(fn.MAX(Note.timestamp))
     max_ts = query.scalar(db)

     query = Note.select(fn.MAX(Note.timestamp), fn.COUNT(Note.id))
     max_ts, n_notes = query.scalar(db, as_tuple=True)

     query = Note.select(fn.COUNT(Note.id).alias('count'))
     assert query.scalar(db, as_dict=True) == {'count': 123}

:param Database database: database to execute query against.
  :param bool clear_limit: Clear any LIMIT clause when counting.
  :return: Number of rows in the query result-set.

  Return number of rows in the query result-set.

  Implemented by running SELECT COUNT(1) FROM (<current query>).

:param Database database: database to execute query against.
  :return: Whether any results exist for the current query.

  Return a boolean indicating whether the current query has any results.

:param Database database: database to execute query against.
  :return: A single row from the database or ``None``.

  Execute the query and return the first row, if it exists. Multiple
  calls will result in multiple queries being executed.

  If no matching row is found this method returns ``None`` - this differs
  from the behavior of :meth:`ModelSelect.get` and :meth:`Model.get`, which
  raise ``DoesNotExist`` when no row is found.

query = User.select(User.id, User.username)
  for user in query:
      print(user.username)

query = (User
           .select(User, fn.COUNT(Tweet.id).alias('count'))
           .join(Tweet, JOIN.LEFT_OUTER)
           .group_by(User))
  for user in query:
      print(user.username, 'has tweeted', user.count, 'times')

:param columns: Zero or more column-like objects to SELECT.

  Specify which columns or column-like values to SELECT.

:param columns: Zero or more column-like objects to SELECT.

  Same as :meth:`Select.columns`, provided for
  backwards-compatibility.

:param columns: Zero or more column-like objects to SELECT.

  Extend the current selection with the given columns.

  Example:

  .. code-block:: python

     def get_users(with_count=False):
         query = User.select()
         if with_count:
             query = (query
                      .select_extend(fn.COUNT(Tweet.id).alias('count'))
                      .join(Tweet, JOIN.LEFT_OUTER)
                      .group_by(User))
         return query

:param sources: Zero or more sources for the FROM clause.

  Specify which table-like objects should be used in the FROM clause.

  .. code-block:: python

     User = Table('users')
     Tweet = Table('tweets')
     query = (User
              .select(User.c.username, Tweet.c.content)
              .from_(User, Tweet)
              .where(User.c.id == Tweet.c.user_id))
     for row in query.execute(db):
         print(row['username'], '->', row['content'])

:param dest: A table or table-like object.
  :param str join_type: Type of JOIN, default is "INNER".
  :param Expression on: Join predicate.

  Join type may be one of:

  * ``JOIN.INNER``
  * ``JOIN.LEFT_OUTER``
  * ``JOIN.RIGHT_OUTER``
  * ``JOIN.FULL``
  * ``JOIN.FULL_OUTER``
  * ``JOIN.CROSS``

  Express a JOIN:

  .. code-block:: python

     User = Table('users', ('id', 'username'))
     Note = Table('notes', ('id', 'user_id', 'content'))

     query = (Note
              .select(Note.content, User.username)
              .join(User, on=(Note.user_id == User.id)))

:param values: zero or more Column-like objects to group by.

  Define the GROUP BY clause. Any previously-specified values will be
  overwritten.

  Additionally, to specify all columns on a given table, you can pass the
  table/model object in place of the individual columns.

  Example:

  .. code-block:: python

     query = (User
              .select(User, fn.Count(Tweet.id).alias('count'))
              .join(Tweet)
              .group_by(User))

:param values: zero or more Column-like objects to group by.

  Extend the GROUP BY clause with the given columns.

:param expressions: zero or more expressions to include in the HAVING
      clause.

  Include the given expressions in the HAVING clause of the query. The
  expressions will be AND-ed together with any previously-specified
  HAVING expressions.

  Example:

  .. code-block:: python

     # Find users with 100 or more Tweets.
     query = (User
              .select(User, fn.Count(Tweet.id).alias('count'))
              .join(Tweet)
              .group_by(User)
              .having(fn.Count(Tweet.id) >= 100))

:param columns: Zero or more column-like objects.

  Indicate whether this query should use a DISTINCT clause. By specifying
  a single value of ``True`` the query will use a simple SELECT DISTINCT.
  Specifying one or more columns will result in a SELECT DISTINCT ON.

:param windows: zero or more :class:`Window` objects.

  Define the WINDOW clause. Any previously-specified values will be
  overwritten.

  Example:

  .. code-block:: python

     # Equivalent example Using a Window() instance instead.
     window = Window(partition_by=[Sample.counter])
     query = (Sample
              .select(
                 Sample.counter,
                 Sample.value,
                 fn.AVG(Sample.value).over(window))
              .window(window)  # Note call to ".window()"
              .order_by(Sample.counter))

:param for_update: Either a boolean or a string indicating the
      desired lock strength, e.g. "FOR SHARE" or "FOR NO KEY UPDATE".
  :param of: One or more models to restrict locking to.
  :param bool nowait: Specify NOWAIT option when locking.
  :param bool skip_locked: Specify SKIP LOCKED option when locking.

Mark this query as the right-hand side of a ``LATERAL`` join. When
  joined, the subquery may reference columns from the tables to its
  left.

:param returning: Zero or more column-like objects for RETURNING clause

  Specify the RETURNING clause of query (Postgresql and Sqlite):

  .. code-block:: python

     query = (User
              .insert_many([{'username': 'foo'},
                            {'username': 'bar'},
                            {'username': 'baz'}])
              .returning(User.id, User.username)
              .namedtuples())
     data = query.execute()
     for row in data:
         print('added:', row.username, 'with id=', row.id)

  .. seealso:: :ref:`returning-clause` for additional discussion.

PageView = Table('page_views')
  query = (PageView
           .update({PageView.c.page_views: PageView.c.page_views + 1})
           .where(PageView.c.url == url))
  query.execute(database)

:param Source sources: one or more :class:`Table`,
      :class:`Model`, query, or :class:`ValuesList` to join with.

  Specify additional tables to join with using the UPDATE ... FROM
  syntax, which is supported by Postgres. The `Postgres documentation <https://www.postgresql.org/docs/10/static/sql-update.html#id-1.9.3.176.8>`_
  provides additional detail, but to summarize:

     When a ``FROM`` clause is present, what essentially happens is that
     the target table is joined to the tables mentioned in the
     from_list, and each output row of the join represents an update
     operation for the target table. When using ``FROM`` you should
     ensure that the join produces at most one output row for each row
     to be modified.

  Example:

  .. code-block:: python

     # Update multiple users in a single query.
     data = [('alice', True),
             ('bob', False),
             ('carol', True)]
     vl = ValuesList(data, columns=('username', 'is_admin'), alias='vl')

     # Here we'll update the "is_admin" status of the above users,
     # "joining" the VALUES() on the "username" column.
     query = (User
              .update(is_admin=vl.c.is_admin)
              .from_(vl)
              .where(User.username == vl.c.username))

  The above query produces the following SQL:

  .. code-block:: sql

     UPDATE "users" SET "is_admin" = "vl"."is_admin"
     FROM (
         VALUES ('alice', t), ('bob', f), ('carol', t))
         AS "vl"("username", "is_admin")
     WHERE ("users"."username" = "vl"."username")

User = Table('users')

  query = User.insert({User.c.username: 'alice'})
  query.execute(database)

:param bool _as_rowcount: Whether to return the modified row count (as
      opposed to the last-inserted row id).

  SQLite and MySQL return the last inserted rowid. Postgresql will return a
  cursor for iterating over the inserted id(s).

  If you prefer to receive the inserted row-count, then specify
  ``as_rowcount()``:

  .. code-block:: python

     db = MySQLDatabase(...)

     query = User.insert_many([...])
     # By default, the last rowid is returned:
     #last_id = query.execute()

     # To get the modified row-count:
     rowcount = query.as_rowcount().execute()

:param bool ignore: Whether to add ON CONFLICT IGNORE clause.

  Specify IGNORE conflict resolution strategy.

:param bool replace: Whether to add ON CONFLICT REPLACE clause.

  Specify REPLACE conflict resolution strategy (SQLite and MySQL only).

:param str action: Action to take when resolving conflict. If blank,
      action is assumed to be "update".
  :param update: A dictionary mapping column to new value.
  :param preserve: A list of columns whose values should be preserved from the original INSERT.
  :param where: Expression to restrict the conflict resolution.
  :param conflict_target: Column(s) that comprise the constraint.
  :param conflict_where: Expressions needed to match the constraint target if it is a partial index (index with a WHERE clause).
  :param str conflict_constraint: Name of constraint to use for conflict
      resolution. Currently only supported by Postgres.

  Specify the parameters for an :class:`OnConflict` clause to use for
  conflict resolution.

  See :ref:`upsert` for additional discussion.

  Examples:

  .. code-block:: python

     class User(Model):
         username = TextField(unique=True)
         last_login = DateTimeField(null=True)
         login_count = IntegerField()

     def log_user_in(username):
         now = datetime.datetime.now()

         # INSERT a new row for the user with the current timestamp and
         # login count set to 1. If the user already exists, then we
         # will preserve the last_login value from the "insert()" clause
         # and atomically increment the login-count.
         userid = (User
                   .insert(username=username, last_login=now, login_count=1)
                   .on_conflict(
                       conflict_target=[User.username],
                       preserve=[User.last_login],
                       update={User.login_count: User.login_count + 1})
                   .execute())
         return userid

  Example using the special :class:`EXCLUDED` namespace:

  .. code-block:: python

     class KV(Model):
         key = CharField(unique=True)
         value = IntegerField()

     # Create one row.
     KV.create(key='k1', value=1)

     # Demonstrate usage of EXCLUDED.
     # Here we will attempt to insert a new value for a given key. If that
     # key already exists, then we will update its value with the *sum* of its
     # original value and the value we attempted to insert -- provided that
     # the new value is larger than the original value.
     query = (KV.insert(key='k1', value=10)
              .on_conflict(conflict_target=[KV.key],
                           update={KV.value: KV.value + EXCLUDED.value},
                           where=(EXCLUDED.value > KV.value)))

     # Executing the above query will result in the following data being
     # present in the "kv" table:
     # (key='k1', value=11)
     query.execute()

     # If we attempted to execute the query *again*, then nothing would be
     # updated, as the new value (10) is now less than the value in the
     # original row (11).

Tweet = Table('tweets')

  # Delete all unpublished tweets older than 30 days.
  cutoff = datetime.datetime.now() - datetime.timedelta(days=30)
  query = (Tweet
           .delete()
           .where(
               (Tweet.c.is_published == False) &
               (Tweet.c.timestamp < cutoff)))
  nrows = query.execute(database)

.. code-block:: python

     query = User.select().with_related(Load(User.tweets))

query = (Tweet
           .select(Tweet, User)
           .join(User))
  for tweet in query:
      # Looking up tweet.user.username does not require a query since
      # the related user's columns were selected.
      print(tweet.user.username, '->', tweet.content)

query = User.select()
  for user in prefetch(query, Tweet):
      print(user.username)
      for tweet in user.tweets:  # Does not require additional query.
          print('    ', tweet.content)

Nest one or more child :class:`Load` nodes (or foreign-key / back-reference
  fields) beneath this relation.

# For each user, load their tweets (ordered newest-to-oldest), and for
  # each Tweet, load associated Favorites.
  rels = (Load(User.tweets,
               Tweet.select().order_by(Tweet.timestamp.desc()))
          .then(Load(Tweet.favorites)))

  query = User.select().with_related(rels)

  # Avoids N+1 problem - tweets and favorites are efficiently loaded.
  for user in query:
      for tweet in user.tweets:
          print(user.username, tweet.content, len(tweet.favorites))

  # Prints (tweets newest-first, with each tweet's favorite count):
  # alice alice-3 2
  # alice alice-2 0
  # alice alice-1 1
  # bob bob-2 1
  # bob bob-1 0

query = User.select().paginate(1, 20).with_related(Load(User.tweets))

SELECT * FROM "tweet"
  WHERE "user_id" IN (
      SELECT "_limited"."id"
      FROM (SELECT "id" FROM "user" LIMIT 20 OFFSET 0) AS "_limited")

tweets = Load(User.tweets, strategy=PREFETCH_TYPE.JOIN)
  query = User.select().with_related(tweets)

SELECT DISTINCT "tweet".* FROM "tweet"
  INNER JOIN (SELECT "id" FROM "user") AS "u"
      ON ("u"."id" = "tweet"."user_id")

query = User.select().with_related(
      Load(User.tweets, strategy=PREFETCH_TYPE.MATERIALIZE))

-- The relation reuses the parent rows' ids as bound parameters:
  SELECT * FROM "tweet" WHERE "user_id" IN (1, 2, 3)

# Each user's two most-recent tweets:
  tweets = Tweet.select().order_by(Tweet.timestamp.desc())
  query = User.select().with_related(
      Load(User.tweets, tweets, per_parent=2))

  for user in query:
      print(user.username, [t.content for t in user.tweets])

  # Prints:
  # alice ['alice-3', 'alice-2']
  # bob ['bob-2', 'bob-1']
  # carol []

Add a source to the AliasManager's internal registry at the current
  scope. The alias will be automatically generated using the following
  scheme (where each level of indentation refers to a new scope):

  :param Source source: Make the manager aware of a new source. If the
      source has already been added, the call is a no-op.

Return the alias for the source in the current scope. If the source
  does not have an alias, it will be given the next available alias.

  :param Source source: The source whose alias should be retrieved.
  :return: The alias already assigned to the source, or the next
      available alias.
  :rtype: str

Manually set the alias for the source at the current scope.

  :param Source source: The source for which we set the alias.

Push a new scope onto the stack.

Pop scope from the stack.

Return the currently-active scope rules.

Return whether the current state is wrapped in parentheses.

Return whether the current state is the child of another query.

The default scope. Sources are referred to by alias, columns by
  dotted-path from the source.

Scope used when defining sources, e.g. in the column list and FROM
  clause of a SELECT query. This scope is used for defining the
  fully-qualified name of the source and assigning an alias.

Scope used for UPDATE, INSERT or DELETE queries, where instead of
  referencing a source by an alias, we refer to it directly. Similarly,
  since there is a single table, columns do not need to be referenced
  by dotted-path.

Scope used when generating the contents of a common-table-expression.
  Used after a WITH statement, when generating the definition for a CTE
  (as opposed to merely a reference to one).

Scope used when generating SQL for a column. Ensures that the column is
  rendered with its correct alias. Was needed because when referencing
  the inner projection of a sub-select, Peewee would render the full
  SELECT query as the "source" of the column (instead of the query's
  alias + . + column).  This scope allows us to avoid rendering the full
  query when we only need the alias.

Append a composable Node object, sub-context, or other object to the
  query AST. Python values, such as integers, strings, floats, etc. are
  treated as parameterized values.

  :return: The updated Context object.

Append a string-literal to the current query AST.

  :return: The updated Context object.

:param Node node: Instance of a Node subclass.
  :return: a 2-tuple consisting of (sql, parameters).

  Convert the given node to a SQL AST and return a 2-tuple consisting
  of the SQL query and the parameters.

:return: a 2-tuple consisting of (sql, parameters) for the context.

:param obj: Object to proxy to.

  Bind the proxy to the given object. Afterwards all attribute lookups
  and method calls on the proxy will be sent to the given object.

  Any callbacks that have been registered will be called.

:param callback: A function that accepts a single parameter, the bound
      object.
  :return: self

  Add a callback to be executed when the proxy is initialized.

db = DatabaseProxy()

  class BaseModel(Model):
      class Meta:
          database = db

  # ... some time later ...
  if app.config['DEBUG']:
      database = SqliteDatabase('local.db')
  elif app.config['TESTING']:
      database = SqliteDatabase(':memory:')
  else:
      database = PostgresqlDatabase('production')

  db.initialize(database)

it = range(10)  # An iterable that yields 0...9.

  # Break the iterable into chunks of length 4.
  for chunk in chunked(it, 4):
      print(', '.join(str(num) for num in chunk))

  # PRINTS:
  # 0, 1, 2, 3
  # 4, 5, 6, 7
  # 8, 9