Skip to content

Commit

Permalink
Reduce prominence of cockroachdb in docs.
Browse files Browse the repository at this point in the history
They recently announced that they are abandoning their core open-source
offering and switching to fully-proprietary licensing.

[skip ci]
  • Loading branch information
coleifer committed Oct 15, 2024
1 parent 7805ba9 commit 155e724
Show file tree
Hide file tree
Showing 3 changed files with 3 additions and 77 deletions.
2 changes: 1 addition & 1 deletion README.rst
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ Peewee is a simple and small ORM. It has few (but expressive) concepts, making i

* a small, expressive ORM
* python 2.7+ and 3.4+
* supports sqlite, mysql, mariadb, postgresql and cockroachdb
* supports sqlite, mysql, mariadb, postgresql
* tons of `extensions <http://docs.peewee-orm.com/en/latest/peewee/playhouse.html>`_

New to peewee? These may help:
Expand Down
6 changes: 1 addition & 5 deletions docs/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ it easy to learn and intuitive to use.

* a small, expressive ORM
* python 2.7+ and 3.4+
* supports sqlite, mysql, mariadb, postgresql and cockroachdb
* supports sqlite, mysql, mariadb, postgresql.
* :ref:`tons of extensions <playhouse>`

.. image:: postgresql.png
Expand All @@ -32,10 +32,6 @@ 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: cockroachdb

Peewee's source code hosted on `GitHub <https://github.com/coleifer/peewee>`_.

New to peewee? These may help:
Expand Down
72 changes: 1 addition & 71 deletions docs/peewee/database.rst
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ database class provides some basic, database-specific configuration options.
pg_db = PostgresqlDatabase('my_app', user='postgres', password='secret',
host='10.1.0.9', port=5432)
Peewee provides advanced support for SQLite, Postgres and CockroachDB via
Peewee provides advanced support for SQLite, Postgres and others via
database-specific extension modules. To use the extended-functionality, import
the appropriate database-specific module and use the database class provided:

Expand All @@ -51,20 +51,10 @@ the appropriate database-specific module and use the database class provided:
db = PostgresqlExtDatabase('my_app', user='postgres', register_hstore=True)
from playhouse.cockroachdb import CockroachDatabase
# Use CockroachDB.
db = CockroachDatabase('my_app', user='root', port=26257, host='10.1.0.8')
# CockroachDB connections may require a number of parameters, which can
# alternatively be specified using a connection-string.
db = CockroachDatabase('postgresql://...')
For more information on database extensions, see:

* :ref:`postgres_ext`
* :ref:`sqlite_ext`
* :ref:`crdb`
* :ref:`sqlcipher_ext` (encrypted SQLite database).
* :ref:`apsw`
* :ref:`sqliteq`
Expand Down Expand Up @@ -104,7 +94,6 @@ Consult your database driver's documentation for the available parameters:
* MySQL: `pymysql <https://github.com/PyMySQL/PyMySQL/blob/f08f01fe8a59e8acfb5f5add4a8fe874bec2a196/pymysql/connections.py#L494-L513>`_
* MySQL: `mysqlclient <https://github.com/PyMySQL/mysqlclient>`_
* SQLite: `sqlite3 <https://docs.python.org/2/library/sqlite3.html#sqlite3.connect>`_
* CockroachDB: see `psycopg2 <https://www.psycopg.org/docs/module.html#psycopg2.connect>`_

.. _using_postgresql:

Expand Down Expand Up @@ -183,65 +172,6 @@ parameter, using the symbolic constants in ``psycopg2.extensions``:
conn.set_isolation_level(ISOLATION_LEVEL_SERIALIZABLE)
.. _using_crdb:

Using CockroachDB
-----------------

Connect to CockroachDB (CRDB) using the :py:class:`CockroachDatabase` database
class, defined in ``playhouse.cockroachdb``:

.. code-block:: python
from playhouse.cockroachdb import CockroachDatabase
db = CockroachDatabase('my_app', user='root', port=26257, host='localhost')
If you are using `Cockroach Cloud <https://cockroachlabs.cloud/>`_, you may
find it easier to specify the connection parameters using a connection-string:

.. code-block:: python
db = CockroachDatabase('postgresql://root:secret@host:26257/defaultdb...')
.. note:: CockroachDB requires the ``psycopg2`` (postgres) Python driver.

.. note::
CockroachDB installation and getting-started guide can be
found here: https://www.cockroachlabs.com/docs/stable/install-cockroachdb.html

CRDB provides client-side transaction retries, which are available using a
special :py:meth:`CockroachDatabase.run_transaction` helper-method. This method
accepts a callable, which is responsible for executing any transactional
statements that may need to be retried.

Simplest possible example of :py:meth:`~CockroachDatabase.run_transaction`:

.. code-block:: python
def create_user(email):
# Callable that accepts a single argument (the database instance) and
# which is responsible for executing the transactional SQL.
def callback(db_ref):
return User.create(email=email)
return db.run_transaction(callback, max_attempts=10)
huey = create_user('[email protected]')
.. note::
The ``cockroachdb.ExceededMaxAttempts`` exception will be raised if the
transaction cannot be committed after the given number of attempts. If the
SQL is mal-formed, violates a constraint, etc., then the function will
raise the exception to the caller.

For more information, see:

* :ref:`CRDB extension documentation <crdb>`
* :ref:`SSL configuration with CockroachDB <crdb_ssl>`
* :ref:`Arrays <pgarrays>` (postgres-specific, but applies to CRDB)
* :ref:`JSON <pgjson>` (postgres-specific, but applies to CRDB)

.. _using_sqlite:

Using SQLite
Expand Down

0 comments on commit 155e724

Please sign in to comment.