# How to use the fishbook

## Requirements

* Python 3.5+ only, **no** python 2
* [datajoint](https://datajoint.io) to connect to the database and to map python objects to table entries.
* [nixio](https://github.com/g-node/nixpy) to read the relacs-flavored nix files during import or later during data retrieval.

## Installation

### 1) Clone the repository

  ```bash
  >> git clone https://whale.am28.uni-tuebingen.de/git/jgrewe/fishbook.git 
  ```

### 2) Installation

   When installing for development: install for the current user, install as "editable":
  
  ```bash
  >> cd fishbook
  >> pip3 install -e fishbook --user
  ```

  When installing for use:

  ```bash
  >> pip3 install fishbook --user
  # or, for system-wide installation
  >> sudo pip3 install fishbook
  ```


### 3) Installing a local database server

When you want to run *fishbook* locally you need to install a local database server (either mariaDB or mysql).

On Ubuntu or Linux mint use *apt* to install the server

```bash
sudo apt update
sudo apt install mariadb-server
sudo mysql_secure_installation
```

On Fedora use *dnf*

```bash
sudo dnf update
sudo dnf install mariadb-server
sudo mysql_secure_installation
```

On MacOS the most convenient way is to use [*homebrew*](https://brew.sh) see also [mariadb documentation](https://mariadb.com/kb/en/installing-mariadb-on-macos-using-homebrew/)

```bash
brew install mariadb
mysql.server start
brew services start mariadb  # to automatically start the server upon boot
```

On Windows you probably need to download an installer...

Upon installation you should be able to log into the database as root without a password. 

```bash
mysql -u root 
``` 

To allow *datajoint* to store stuff on the server you need to:
1. Create a database on the server.
2. Add a user and grant this user read and write access.

### Creating a database

At the moment *fishbook* assumes that your database is called **fish_book**. To create it log into the server 

```bash
mysql -u root -p
```

And and execute the following commands

```sql
MariaDB [(none)]> CREATE DATABASE fish_book CHARACTER SET = utf8;
MariaDB [(none)]> GRANT ALL ON fish_book.* TO 'foo'@'localhost' IDENTIFIED BY 'password';
MariaDB [(none)]> FLUSH PRIVILEGES;
```

The first command creates the empty database and sets the Character set to utf8. This is important at least when it comes to *fishbook*. The second row creates a user **foo** and grants that user all rights on all tables of **fish_book**. So far **foo** can only log in from the local machine. In order to grant access also from outsides you need to issue a second command:

```sql
MariaDB [(none)]> GRANT ALL ON fish_book.* TO 'foo'@'%' IDENTIFIED BY 'password';
MariaDB [(none)]> FLUSH PRIVILEGES;
```

From localhost you should now be able to log into the **fish_book** database by 

```bash
mysql fish_book -u foo -p
```

From outsides use

```shell
mysql fish_book -h yourhost.yourdomain -u foo -p
```

### Things to remember

* Database engine must be InnoDB, which is default in MariaDB
* **OperationalError: (1071, 'Specified key was too long; max key length is 3072 bytes')**
Caused by a wrong character set check that it is set to utf8:
```sql
ALTER DATABASE `fish_book` CHARACTER SET utf8;
```