From a79e9f97ee4cca35b4f479d14912a23019649b48 Mon Sep 17 00:00:00 2001 From: Itai Shirav Date: Thu, 11 May 2017 05:30:17 +0300 Subject: [PATCH] Documentation --- CHANGELOG.rst => CHANGELOG.md | 8 +++++ MIGRATIONS.rst | 65 ----------------------------------- docs/contributing.md | 17 ++++++++- docs/schema_migrations.md | 6 ++-- docs/toc.md | 2 ++ 5 files changed, 29 insertions(+), 69 deletions(-) rename CHANGELOG.rst => CHANGELOG.md (81%) delete mode 100644 MIGRATIONS.rst diff --git a/CHANGELOG.rst b/CHANGELOG.md similarity index 81% rename from CHANGELOG.rst rename to CHANGELOG.md index e933d06..e74a7e6 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.md @@ -1,6 +1,14 @@ Change Log ========== +Unreleased +---------- +- Major new feature: building model queries using QuerySets +- Refactor and expand the documentation +- Add support for FixedString fields +- Add support for more engine types: TinyLog, Log, Memory +- Bug fix: Do not send readonly=1 when connection is already in readonly mode + v0.8.2 ------ - Fix broken Python 3 support (M1hacka) diff --git a/MIGRATIONS.rst b/MIGRATIONS.rst deleted file mode 100644 index 0f0d5e2..0000000 --- a/MIGRATIONS.rst +++ /dev/null @@ -1,65 +0,0 @@ -Migrations -========== - -Over time, the ORM models in your application may change. Migrations provide a way to modify the database -tables according to the changes in your models, without writing raw SQL. - -The migrations that were applied to the database are recorded in the ``infi_clickhouse_orm_migrations`` table, -so migrating the database will only apply any missing migrations. - -Writing Migrations ------------------- - -To write migrations, create a Python package. Then create a python file for the initial migration. The migration -files must begin with a four-digit number, and will be applied in sequence. For example:: - - analytics - | - +-- analytics_migrations - | - +-- __init__.py - | - +-- 0001_initial.py - | - +-- 0002_add_user_agents_table.py - -Each migration file is expected to contain a list of ``operations``, for example:: - - from infi.clickhouse_orm import migrations - from analytics import models - - operations = [ - migrations.CreateTable(models.Visits), - migrations.CreateTable(models.Visitors) - ] - -The following operations are supported: - -**CreateTable** - -A migration operation that creates a table for a given model class. - -**DropTable** - -A migration operation that drops the table of a given model class. - -**AlterTable** - -A migration operation that compares the table of a given model class to -the model's fields, and alters the table to match the model. The operation can: - -- add new columns -- drop obsolete columns -- modify column types - -Default values are not altered by this operation. - -Running Migrations ------------------- - -To migrate a database, create a ``Database`` instance and call its ``migrate`` method with the package -name containing your migrations:: - - Database('analytics_db').migrate('analytics.analytics_migrations') - -Note that you may have more than one migrations package. \ No newline at end of file diff --git a/docs/contributing.md b/docs/contributing.md index 6268733..53af669 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -1,12 +1,27 @@ Contributing ============ +This project is hosted on GitHub - [https://github.com/Infinidat/infi.clickhouse_orm/](https://github.com/Infinidat/infi.clickhouse_orm/). + +Please open an issue there if you encounter a bug or want to request a feature. +Pull requests are also welcome. + +Building +-------- + After cloning the project, run the following commands: easy_install -U infi.projector cd infi.clickhouse_orm projector devenv build +A `setup.py` file will be generate, which you can use to install the development version of the package: + + python setup.py install + +Tests +----- + To run the tests, ensure that the ClickHouse server is running on (this is the default), and run: bin/nosetests @@ -18,4 +33,4 @@ To see test coverage information run: --- -[<< System Models](system_models.md) | [Table of Contents](toc.md) \ No newline at end of file +[<< System Models](system_models.md) | [Table of Contents](toc.md) | [Class Reference >>](class_reference.md) \ No newline at end of file diff --git a/docs/schema_migrations.md b/docs/schema_migrations.md index 2d67f8d..e4647bf 100644 --- a/docs/schema_migrations.md +++ b/docs/schema_migrations.md @@ -8,7 +8,7 @@ The migrations that were applied to the database are recorded in the `infi_click Writing Migrations ------------------ -To write migrations, create a Python package. Then create a python file for the initial migration. The migration files must begin with a four-digit number, and will be applied in sequence. For example:: +To write migrations, create a Python package. Then create a python file for the initial migration. The migration files must begin with a four-digit number, and will be applied in sequence. For example: analytics | @@ -20,7 +20,7 @@ To write migrations, create a Python package. Then create a python file for the | +-- 0002_add_user_agents_table.py -Each migration file is expected to contain a list of `operations`, for example:: +Each migration file is expected to contain a list of `operations`, for example: from infi.clickhouse_orm import migrations from analytics import models @@ -53,7 +53,7 @@ Default values are not altered by this operation. Running Migrations ------------------ -To migrate a database, create a `Database` instance and call its `migrate` method with the package name containing your migrations:: +To migrate a database, create a `Database` instance and call its `migrate` method with the package name containing your migrations: Database('analytics_db').migrate('analytics.analytics_migrations') diff --git a/docs/toc.md b/docs/toc.md index ae05203..4167e64 100644 --- a/docs/toc.md +++ b/docs/toc.md @@ -41,6 +41,8 @@ * [Partitions and Parts](system_models.md#partitions-and-parts) * [Contributing](contributing.md#contributing) + * [Building](contributing.md#building) + * [Tests](contributing.md#tests) * [Class Reference](class_reference.md#class-reference) * [infi.clickhouse_orm.database](class_reference.md#infi.clickhouse_orm.database)