Skip to content

Commit

Permalink
Documentation: Improve guidance about migrating to sqlalchemy-cratedb
Browse files Browse the repository at this point in the history
Mention the switchover both on the project's README, and the index page
of the documentation, in order to give users who might be running into
relevant flaws a better chance to discover the solution.

Co-authored-by: Marios Trivyzas <[email protected]>
  • Loading branch information
amotl and matriv committed Jul 1, 2024
1 parent a928d96 commit 7314e37
Show file tree
Hide file tree
Showing 2 changed files with 32 additions and 6 deletions.
18 changes: 15 additions & 3 deletions README.rst
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,18 @@ To install the most recent driver version, run::
$ pip install --upgrade crate


Documentation and help
Migration Notes
===============

If you are migrating from previous versions of ``crate[sqlalchemy]<1.0.0``, you
will find that the newer releases ``crate>=1.0.0`` no longer include the
SQLAlchemy dialect for CrateDB.

See `migrate to sqlalchemy-cratedb`_ for relevant guidelines about how to
successfully migrate to the `sqlalchemy-cratedb`_ package.


Documentation and Help
======================

- `CrateDB Python Client documentation`_
Expand All @@ -68,8 +79,8 @@ Documentation and help
- Other `support channels`_


Contributing
============
Contributions
=============

The CrateDB Python client library is an open source project, and is `managed on
GitHub`_. We appreciate contributions of any kind.
Expand All @@ -84,6 +95,7 @@ GitHub`_. We appreciate contributions of any kind.
.. _DB API 2.0: https://peps.python.org/pep-0249/
.. _Developer documentation: DEVELOP.rst
.. _managed on GitHub: https://github.com/crate/crate-python
.. _migrate to sqlalchemy-cratedb: https://cratedb.com/docs/sqlalchemy-cratedb/migrate-from-crate-client.html
.. _PyPI: https://pypi.org/
.. _SQLAlchemy: https://www.sqlalchemy.org/
.. _sqlalchemy-cratedb: https://github.com/crate/sqlalchemy-cratedb
Expand Down
20 changes: 17 additions & 3 deletions docs/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -27,9 +27,6 @@ it has also been tested successfully with `PyPy`_.
Please make sure to also visit the section about :ref:`other-options`, using
the :ref:`crate-reference:interface-postgresql` interface of `CrateDB`_.

The :ref:`CrateDB dialect <using-sqlalchemy>` for `SQLAlchemy`_ is provided
by the ``sqlalchemy-cratedb`` package.


*************
Documentation
Expand Down Expand Up @@ -98,6 +95,21 @@ please consult the :ref:`data-types` documentation page.

data-types


Migration Notes
===============

The :ref:`CrateDB dialect <using-sqlalchemy>` for `SQLAlchemy`_ is provided
by the `sqlalchemy-cratedb`_ package.

If you are migrating from previous versions of ``crate[sqlalchemy]<1.0.0``, you
will find that the newer releases ``crate>=1.0.0`` no longer include the
SQLAlchemy dialect for CrateDB.

See `migrate to sqlalchemy-cratedb`_ for relevant guidelines about how to
successfully migrate to the `sqlalchemy-cratedb`_ package.


Examples
========

Expand Down Expand Up @@ -168,10 +180,12 @@ The project is licensed under the terms of the Apache 2.0 license, like
.. _GeoJSON geometry objects: https://tools.ietf.org/html/rfc7946#section-3.1
.. _LICENSE: https://github.com/crate/crate-python/blob/master/LICENSE
.. _managed on GitHub: https://github.com/crate/crate-python
.. _migrate to sqlalchemy-cratedb: https://cratedb.com/docs/sqlalchemy-cratedb/migrate-from-crate-client.html
.. _pandas: https://en.wikipedia.org/wiki/Pandas_(software)
.. _PEP 249: https://peps.python.org/pep-0249/
.. _PyPy: https://www.pypy.org/
.. _sample application: https://github.com/crate/crate-sample-apps/tree/main/python-flask
.. _sample application documentation: https://github.com/crate/crate-sample-apps/blob/main/python-flask/documentation.md
.. _SQLAlchemy: https://en.wikipedia.org/wiki/Sqlalchemy
.. _sqlalchemy-cratedb: https://github.com/crate/sqlalchemy-cratedb
.. _Use CrateDB with pandas: https://github.com/crate/crate-qa/pull/246

0 comments on commit 7314e37

Please sign in to comment.