jgrewe/fishbook
2
1
Fork 1
Code Issues 3 Pull Requests Releases Wiki Activity

[docs] info on db server configurations

Browse Source
This commit is contained in:
Jan Grewe 2020-07-31 18:01:59 +02:00
parent fcb4a48500
commit 67c0b06052
1 changed files with 65 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

74
docs/index.md
View File

@ -1,4 +1,4 @@
# How to use the fish book # How to use the fishbook
## Requirements ## Requirements
@ -31,32 +31,88 @@
>> sudo pip3 install fishbook >> sudo pip3 install fishbook
``` ```
### 3) Connecting to the database
#### Installing a local database ### 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). 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 On Ubuntu or Linux mint use *apt* to install the server
```bash ```bash
sudo apt install mysql sudo apt update
sudo apt install mariadb-server
sudo mysql_secure_installation
``` ```
On Fedora use *dnf* On Fedora use *dnf*
```bash ```bash
sudo dnf install mysql 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) 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 ```bash
brew install mysql 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... On Windows you probably need to download an installer...
#### Database connection 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;
```
Suppose that you intend to work on a project named `foo` use the terminal to navigate to the project directory: `cd foo`