From a695f18ddaf44584ebea0b1f79c6fb1dfec40121 Mon Sep 17 00:00:00 2001 From: Charles Leifer Date: Fri, 15 Nov 2019 12:50:11 -0600 Subject: [PATCH] Initial commit for crdb documentation updates. --- docs/crdb.png | Bin 2619 -> 2651 bytes docs/index.rst | 6 +++- docs/peewee/crdb.rst | 6 ++++ docs/peewee/database.rst | 67 ++++++++++++++++++++++++++++++++++++++ docs/peewee/playhouse.rst | 3 ++ 5 files changed, 81 insertions(+), 1 deletion(-) create mode 100644 docs/peewee/crdb.rst diff --git a/docs/crdb.png b/docs/crdb.png index f0b73ca9cef7f6826534ff596230785711546d40..8ca97b0c6c3fbddab284ffc9094abe18fcf2f852 100644 GIT binary patch delta 2588 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 SJldH60000` .. image:: postgresql.png @@ -28,6 +28,10 @@ it easy to learn and intuitive to use. :target: peewee/database.html#using-sqlite :alt: sqlite +.. image:: crdb.png + :target: peewee/database.html#using-crdb + :alt: cockroach + Peewee's source code hosted on `GitHub `_. New to peewee? These may help: diff --git a/docs/peewee/crdb.rst b/docs/peewee/crdb.rst new file mode 100644 index 000000000..a66983e4e --- /dev/null +++ b/docs/peewee/crdb.rst @@ -0,0 +1,6 @@ +.. _crdb: + +Cockroach Database +------------------ + +TODO diff --git a/docs/peewee/database.rst b/docs/peewee/database.rst index 2f820a74a..48a2d4591 100644 --- a/docs/peewee/database.rst +++ b/docs/peewee/database.rst @@ -94,6 +94,8 @@ Consult your database driver's documentation for the available parameters: * MySQL: `pymysql `_ * SQLite: `sqlite3 `_ +.. _using_postgresql: + Using Postgresql ---------------- @@ -169,6 +171,71 @@ parameter, using the symbolic constants in ``psycopg2.extensions``: conn.set_isolation_level(ISOLATION_LEVEL_SERIALIZABLE) +.. _using_crdb: + +Using CockroachDB +----------------- + +Connecting to CockroachDB (CRDB) is very similar to :ref:`using_postgresql` - +in fact, by simply specifying the correct host, port and other settings, the +:py:class:`PostgresqlDatabase` can typically be used. However, in order to make +the most of the features provided by CRDB, it is recommended to use the +:py:class:`CockroachDatabase` database class: + +.. code-block:: python + + from playhouse.cockroach import CockroachDatabase + + db = CockroachDatabase('my_app', user='root', port=26257, host='localhost') + + +The ``playhouse.cockroach`` module also contains a :py:func:`run_transaction` +helper for running a transaction with client-side retry logic: + +.. code-block:: python + + from playhouse.cockroach import run_transaction + + def transfer_funds(from_id, to_id, amt): + """ + Returns a 3-tuple of (success?, from balance, to balance). If there are + not sufficient funds, then the original balances are returned. + """ + def thunk(db_ref): + src, dest = (Account + .select() + .where(Account.id.in_([from_id, to_id]))) + if src.id != from_id: + src, dest = dest, src # Swap order. + + # Cannot perform transfer, insufficient funds! + if src.balance < amt: + return False, src.balance, dest.balance + + # Update each account, returning the new balance. + src, = (Account + .update(balance=Account.balance - amt) + .where(Account.id == from_id) + .returning(Account.balance) + .execute()) + dest, = (Account + .update(balance=Account.balance + amt) + .where(Account.id == to_id) + .returning(Account.balance) + .execute()) + return True, src.balance, dest.balance + + # Perform the queries that comprise a logical transaction. In the + # event the transaction fails due to contention, it will be auto- + # matically retried (up to 10 times). + return run_transaction(db, thunk, max_attempts=10) + +For more information, see: + +* :ref:`CRDB extension documentation ` +* :ref:`Arrays ` (postgres-specific, but applies to CRDB) +* :ref:`JSON ` (postgres-specific, but applies to CRDB) + .. _using_sqlite: Using SQLite diff --git a/docs/peewee/playhouse.rst b/docs/peewee/playhouse.rst index fc3af862d..7d32d7318 100644 --- a/docs/peewee/playhouse.rst +++ b/docs/peewee/playhouse.rst @@ -1587,6 +1587,9 @@ postgres_ext API notes results = Blog.select().where(Blog.search_content.match(terms)) +.. include:: crdb.rst + + .. _mysql_ext: MySQL Extensions