README.md 2.18 KB
Newer Older
Felix Hummel's avatar
Felix Hummel committed
1
# Prerequisites
Felix Hummel's avatar
RDD    
Felix Hummel committed
2
3
- Python 3.8 (a virtual environment is recommended)
- PostgreSQL
Felix Hummel's avatar
Felix Hummel committed
4
5


Felix Hummel's avatar
Felix Hummel committed
6
7
8
9
10
11
12
# Usage
Easily create PostgreSQL schemas! In the following example, we create a schema
called `foo` and remember its URL, which contains the credentials of a role that
was specifically created for this schema. We then run a simple query.
```
puddl db create foo
foourl=$(puddl db url foo)
Felix Hummel's avatar
Felix Hummel committed
13
14
15
16
17
18
19
psql $foourl -c 'SELECT 42 as answer'
```

List schemas and delete them:
```
puddl db ls
puddl db rm foo
Felix Hummel's avatar
Felix Hummel committed
20
21
22
```


Felix Hummel's avatar
RDD    
Felix Hummel committed
23
# Installation from Source
24
```
Felix Hummel's avatar
RDD    
Felix Hummel committed
25
26
27
mkdir ~/puddl
git clone https://gitlab.com/puddl/puddl.git
cd ~/puddl/puddl/
Felix Hummel's avatar
Felix Hummel committed
28
pip install -e .[dev]
Felix Hummel's avatar
Felix Hummel committed
29
30
31
32
33
34
35
36
37
38
39
```

Install completion for bash (for other shells please refer to [the click
documentation][click-completion]):
```
mkdir -p ~/.bash/
_PUDDL_COMPLETE=source_bash puddl > ~/.bash/puddl

cat <<'EOF' >> ~/.bashrc
[[ -f ~/.bash/puddl ]] && source ~/.bash/puddl
EOF
Felix Hummel's avatar
Felix Hummel committed
40

Felix Hummel's avatar
Felix Hummel committed
41
exec $SHELL
42
```
Felix Hummel's avatar
Felix Hummel committed
43
[click-completion]: https://click.palletsprojects.com/en/7.x/bashcomplete/#activation-script
44

Felix Hummel's avatar
Felix Hummel committed
45
46
Initialize the database. The command `puddl config init` will consume the `.env`
file if present in the current working directory.
Felix Hummel's avatar
Felix Hummel committed
47
```
Felix Hummel's avatar
RDD    
Felix Hummel committed
48
cd ~/puddl/puddl/
Felix Hummel's avatar
Felix Hummel committed
49
50

# generate environment variables suitable for development
Felix Hummel's avatar
Felix Hummel committed
51
./env/dev/generate_env_file.sh > .env
Felix Hummel's avatar
Felix Hummel committed
52
53

# write initdb script and start postgres
Felix Hummel's avatar
Felix Hummel committed
54
./env/dev/create_database.sh
Felix Hummel's avatar
RDD    
Felix Hummel committed
55

Felix Hummel's avatar
Felix Hummel committed
56
# based on the environment, write ~/.puddlrc
Felix Hummel's avatar
Felix Hummel committed
57
puddl config init
Felix Hummel's avatar
Felix Hummel committed
58
59

# make sure initialization was successful
Felix Hummel's avatar
Felix Hummel committed
60
puddl db health
Felix Hummel's avatar
Felix Hummel committed
61
62
63

# apply library sql functions as "puddl" user in "public" schema
cat puddl/db/init_sql/*.sql | puddl db shell
Felix Hummel's avatar
Felix Hummel committed
64
65
```

Felix Hummel's avatar
Felix Hummel committed
66
67
Try it:
```
Felix Hummel's avatar
Felix Hummel committed
68
69
cd puddl/felix/exif/
cat README.md
Felix Hummel's avatar
oops    
Felix Hummel committed
70

Felix Hummel's avatar
Felix Hummel committed
71
puddl db shell
Felix Hummel's avatar
Felix Hummel committed
72
```
Felix Hummel's avatar
Felix Hummel committed
73
74


Felix Hummel's avatar
Felix Hummel committed
75
76
77
78
79
80
81
82
83
# Writing an App
The following creates a schema `foo` and binds an engine to it:
```
from puddl.db.alchemy import App
app = App('foo')
app.engine
```


Felix Hummel's avatar
Felix Hummel committed
84
# Development
Felix Hummel's avatar
Felix Hummel committed
85
86
Run flake8 before committing
```
Felix Hummel's avatar
Felix Hummel committed
87
ln -s $(readlink -m env/dev/git-hooks/pre-commit) .git/hooks/pre-commit
Felix Hummel's avatar
Felix Hummel committed
88
89
```

Felix Hummel's avatar
Felix Hummel committed
90
91
92
93
94
95
Basic development workflow:
```
# hack, hack
make
```

Felix Hummel's avatar
Felix Hummel committed
96
97
Got `psql` installed?
```
Felix Hummel's avatar
Felix Hummel committed
98
99
source <(puddl db env)
echo "SELECT path, stat->>'st_uid' as uid FROM file.file" | psql
Felix Hummel's avatar
Felix Hummel committed
100
```
101
102
103
104
105
106
107
108


# Rsync Service
```
cat ~/.ssh/id_*.pub > $PUDDL_HOME/rsync_authorized_keys
ln -s env/dev/docker-compose.override.yml
docker-compose build && docker-compose up -d
```