Included Apps¶
Just as you can modularise your own code using apps, Piccolo itself ships with several builtin apps, which provide a lot of its functionality.
Auto includes¶
The following are registered with your AppRegistry automatically.
Hint
To find out more about each of these commands you can use the
--help
flag on the command line. For example piccolo app new --help
.
app¶
Lets you create new Piccolo apps. See Piccolo Apps.
piccolo app new
asgi¶
Lets you scaffold an ASGI web app. See ASGI.
piccolo asgi new
fixtures¶
Fixtures are used when you want to seed your database with essential data (for example, country names).
Once you have created a fixture, it can be used by your colleagues when setting up an application on their local machines, or when deploying to a new environment.
Databases such as Postgres have built-in ways of dumping and restoring data
(via pg_dump
and pg_restore
). Some reasons to use the fixtures app
instead:
When you want the data to be loadable in a range of database types and versions.
Fixtures are stored in JSON, which are a bit friendlier for source control.
dump¶
To dump the data into a new fixture file:
piccolo fixtures dump > fixtures.json
By default, the fixture contains data from all apps and tables. You can specify a subset of apps and tables instead, for example:
piccolo fixtures dump --apps=blog --tables=Post > fixtures.json
Or for multiple apps / tables:
piccolo fixtures dump --apps=blog,shop --tables=Post,Product > fixtures.json
load¶
To load the fixture:
piccolo fixtures load fixtures.json
If you load the fixture again, you will get primary key errors because the rows
already exist in the database. But what if we need to run it again, because we
had a typo in our fixture, or were missing some data? We can upsert the data
using --on_conflict
.
There are two options:
DO NOTHING
- if any of the rows already exist in the database, just leave them as they are, and don’t raise an exception.DO UPDATE
- if any of the rows already exist in the database, override them with the latest data in the fixture file.
# DO NOTHING
piccolo fixtures load fixtures.json --on_conflict='DO NOTHING'
# DO UPDATE
piccolo fixtures load fixtures.json --on_conflict='DO UPDATE'
And finally, if you’re loading a really large fixture, you can specify the
chunk_size
. By default, Piccolo inserts up to 1,000 rows at a time, as
the database adapter will complain if a single insert query is too large. So
if your fixture containts 10,000 rows, this will mean 10 insert queries.
You can tune this number higher or lower if you want (lower if the table has a lot of columns, or higher if the table has few columns).
piccolo fixtures load fixtures.json --chunk_size=500
meta¶
Tells you which version of Piccolo is installed.
piccolo meta version
migrations¶
Lets you create and run migrations. See Migrations.
playground¶
Lets you learn the Piccolo query syntax, using an example schema. See Playground.
piccolo playground run
project¶
Lets you create a new piccolo_conf.py
file. See Piccolo Projects.
piccolo project new
schema¶
generate¶
Lets you auto generate Piccolo Table
classes from an existing database.
Make sure the credentials in piccolo_conf.py
are for the database you’re
interested in, then run the following:
piccolo schema generate > tables.py
Warning
This feature is still a work in progress. However, even in it’s current form it will save you a lot of time. Make sure you check the generated code to make sure it’s correct.
graph¶
A basic schema visualisation tool. It prints out the contents of a GraphViz dot file representing your schema.
piccolo schema graph
You can pipe the output to your clipboard (piccolo schema graph | pbcopy
on a Mac), then paste it into a website like this
to turn it into an image file.
Or if you have Graphviz installed on your machine, you can do this to create an image file:
piccolo schema graph | dot -Tpdf -o graph.pdf
Here’s an example of a generated image:
Note
There is a video tutorial on YouTube.
shell¶
Launches an iPython shell, and automatically imports all of your registered
Table
classes. It’s great for running adhoc database queries using Piccolo.
piccolo shell run
Note
There is a video tutorial on YouTube.
sql_shell¶
Launches a SQL shell (psql
or sqlite3
depending on the engine), using
the connection settings defined in piccolo_conf.py
. It’s convenient if you
need to run raw SQL queries on your database.
piccolo sql_shell run
For it to work, the underlying command needs to be on the path (i.e. psql
or sqlite3
depending on which you’re using).
Note
There is a video tutorial on YouTube.
tester¶
Launches pytest , which runs your unit test suite. The
advantage of using this rather than running pytest
directly, is the
PICCOLO_CONF
environment variable will automatically be set before the
testing starts, and will be restored to it’s initial value once the tests
finish.
piccolo tester run
Setting the PICCOLO_CONF environment variable means your code will use the database engine specified in that file for the duration of the testing.
By default piccolo tester run
sets PICCOLO_CONF
to
'piccolo_conf_test'
, meaning that a file called piccolo_conf_test.py
will be imported.
Within the piccolo_conf_test.py
file, override the database settings, so it
uses a test database:
from piccolo_conf import *
DB = PostgresEngine(
config={
"database": "my_app_test"
}
)
If you prefer, you can set a custom PICCOLO_CONF
value:
piccolo tester run --piccolo_conf=my_custom_piccolo_conf
You can also pass arguments to pytest:
piccolo tester run --pytest_args="-s foo"
Optional includes¶
These need to be explicitly registered with your AppRegistry.
user¶
Provides a user table, and commands for creating / managing users. See Authentication.