Skip to content
This repository has been archived by the owner on Feb 6, 2023. It is now read-only.

Add documents about database option #169

Merged
merged 1 commit into from
Oct 5, 2018
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
84 changes: 84 additions & 0 deletions docs/source/external_db.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,84 @@
.. _use_external_db:

Use external database
=====================

ChainerUI provides ``--db`` option and supports ``CHAINERUI_DB_URL`` variable to use external database instead of ChainerUI's default database. Sub-commands, ``db``, ``project`` and ``server`` look up a value of the database URL in the following order.

1. command option: ``--db``
2. environment variable: ``CHAINERUI_DB_URL``
3. default database


In the below commands, for example, ChainerUI use ``ANOTHER_DB``::

$ export CHAINERUI_DB_URL=YOUR_DB
$ chainerui --db ANOTHER_DB server
$ # the server will run with ANOTHER_DB, not use YOUR_DB


.. note::

On default, ChainerUI uses SQLite. The database file is placed at ``~/.chainerui/db``.


.. note::

If use external database, ``chainerui db create`` is not required for setup.



Supported database types depend on SQLAlchemy, please see `Dialect <http://docs.sqlalchemy.org/en/latest/dialects/index.html>`__ section and setup appropriate driver for the database. The following sections are examples to setup database and connect with them.


.. note::

``--db`` option value have to be set on each ``db``, ``project`` and ``server`` sub-commands when use external database::

$ chainerui --db YOUR_DB db upgrade

$ # chainerui project create -d PROJECT_DIR # <- *NOT* use YOUR_DB
$ chainerui --db YOUR_DB project create -d PROJECT_DIR

$ # chainerui server # <- *NOT* use YOUR_DB
$ chainerui --db YOUR_DB server

On the other hand, once ``CHAINERUI_DB_URL`` is set as environment variable, the database URL is shared between other sub-commands.


Example: SQLite
---------------

When use SQLite with an original database file placed at ``/path/to/original.db``, database URL is ``sqlite:////path/to/original.db``::

$ export CHAINERUI_DB_URL=sqlite:////path/to/original.db
$ chainerui db upgrade
$ chainerui server


Example: PostgreSQL
-------------------

The below example uses ``psycopg2`` and ``postgres:10.5`` docker image::

$ docker pull postgres:10.5
$ docker run --name postgresql -p 5432:5432 -e POSTGRES_USER=user -e POSTGRES_PASSWORD=pass -d postgres:10.5

$ pip install psycopg2-binary
$ export CHAINERUI_DB_URL=postgresql://user:pass@localhost:5432
$ chainerui db upgrade
$ chainerui server


Example: MySQL
--------------

The below example uses ``mysqlclient`` and ``mysql:8.0.12`` docker image::

$ docker pull mysql:8.0.12
$ docker run --name mysql -p 3306:3306 -e MYSQL_ROOT_PASSWORD=root_pass -e MYSQL_USER=user -e MYSQL_PASSWORD=pass -e MYSQL_DATABASE=chainerui -d mysql:8.0.12

$ pip install mysqlclient
$ export CHAINERUI_DB_URL=mysql+mysqldb://user:pass@127.0.0.1:3306/chainerui
$ chainerui db upgrade
$ chainerui server
12 changes: 7 additions & 5 deletions docs/source/index.rst
Original file line number Diff line number Diff line change
@@ -1,18 +1,20 @@
=====================================
ChainerUI: User interface for Chainer
=====================================
=======================================
ChainerUI -- User interface for Chainer
=======================================

.. toctree::
:maxdepth: 2
:caption: Getting Started:
:caption: ChainerUI Documents

install
getstart
docker
external_db


.. toctree::
:maxdepth: 1
:caption: Reference:
:caption: Reference

reference/ui
reference/cmd
Expand Down
2 changes: 1 addition & 1 deletion docs/source/install.rst
Original file line number Diff line number Diff line change
Expand Up @@ -65,7 +65,7 @@ For more detailed usage, see :ref:`getstart`.
Docker start
------------

Get Docker container from `DockerHub <https://hub.docker.com/r/chainer/chainerui/`__ and start ChainerUI server. The container has installed ChainerUI module, setup a DB and a command to start the server::
Get Docker container from `DockerHub <https://hub.docker.com/r/chainer/chainerui/>`__ and start ChainerUI server. The container has installed ChainerUI module, setup a DB and a command to start the server::

$ git clone https://github.com/chainer/chainerui.git
$ cd chainerui
Expand Down
18 changes: 18 additions & 0 deletions docs/source/reference/cmd.rst
Original file line number Diff line number Diff line change
Expand Up @@ -50,3 +50,21 @@ ChainerUI manages multiple projects and each project manages multiple training l

* ``-d``: (required) target path
* ``-n``: (optional) name of project. use directory name on default.


Common option
-------------

.. _cmd_common_option_db:

``--db``
~~~~~~~~

When use external database, set ``--db`` option to use it. For example, when use SQLite with an original database file placed at ``/path/to/original.db``, initialize commands are::


$ chaiherui --db sqlite:////path/to/original.db db upgrade
$ chaiherui --db sqlite:////path/to/original.db server


This ``--db`` option is given priority over environment variable ``CHAINERUI_DB_URL``. More detail, see :ref:`Use external database <use_external_db>`