| |
@@ -27,6 +27,75 @@
|
| |
do not have write privileges, this will be done for you
|
| |
|
| |
|
| |
+ .. _manipulating-database:
|
| |
+
|
| |
+ Viewing and manipulating the database
|
| |
+ =====================================
|
| |
+
|
| |
+ If you need to perform some changes to the database content or structure (e.g. when experimenting with new untested syncing code, or when writing Alembic scripts), there are several ways to proceed.
|
| |
+
|
| |
+ pg_dump
|
| |
+ -------
|
| |
+
|
| |
+ You can use ``pg_dump`` or ``pg_dumpall`` to back up the whole database, and ``pg_restore`` or ``psql -f`` to restore the database (see `this tutorial`__).
|
| |
+
|
| |
+ __ https://snapshooter.com/learn/postgresql/pg_dump_pg_restore
|
| |
+
|
| |
+ Here's an example of a backup and restore::
|
| |
+
|
| |
+ pg_dump --host=localhost --username=postgres --format=custom --file=blockerbugs.pgdump blockerbugs
|
| |
+ # the following will completely drop and recreate the blockerbugs db
|
| |
+ pg_restore --host=localhost --username=postgres --dbname=postgres --clean --create blockerbugs.pgdump
|
| |
+
|
| |
+
|
| |
+ podman commit
|
| |
+ -------------
|
| |
+
|
| |
+ Alternatively, you can also use ``podman commit`` to save the current container as a new image. If something goes wrong, you then remove the existing container and create a new one based on the saved image (with the backed-up database contents). For example::
|
| |
+
|
| |
+ podman stop blockerbugsdb
|
| |
+ podman commit blockerbugsdb localhost/blockerbugsdb-backup
|
| |
+ # You can now find the backup image in `podman images`.
|
| |
+ # You can remove it any time with `podman image rm`.
|
| |
+ # Feel free to continue development with your current database:
|
| |
+ podman start blockerbugsdb
|
| |
+
|
| |
+ # If you break your database, restore it from the backup:
|
| |
+ podman rm --force blockerbugsdb
|
| |
+ podman run --detach --name blockerbugsdb --publish 5432:5432 localhost/blockerbugsdb-backup
|
| |
+
|
| |
+ Please note that once you have a container based on your ``localhost/blockerbugsdb-backup`` image, you can't remove that image. If that bothers you, you can (after all is done) copy out the database files out of the current container, create a :ref:`new container from scratch <set-up-database>` based on the upstream image, and copy in those files::
|
| |
+
|
| |
+ podman stop blockerbugsdb
|
| |
+ mkdir pgdata
|
| |
+ # the /. is important in these commands
|
| |
+ podman container cp blockerbugsdb:/var/lib/postgresql/pgdata/. pgdata/
|
| |
+ # re-create the container now (see above), and stop it
|
| |
+ podman container cp pgdata/. blockerbugsdb:/var/lib/postgresql/pgdata/
|
| |
+
|
| |
+ Now you're free to remove your backup image.
|
| |
+
|
| |
+
|
| |
+ GUI
|
| |
+ ---
|
| |
+
|
| |
+ If you want to display and optionally edit/backup/restore the tables in a GUI client, there's `pgadmin3`_ in Fedora repositories, `Sequeler`_ on Flathub (viewing only), and `many other clients available`__.
|
| |
+
|
| |
+ .. _pgadmin3: https://src.fedoraproject.org/rpms/pgadmin3
|
| |
+ .. _Sequeler: https://flathub.org/apps/details/com.github.alecaddd.sequeler
|
| |
+ __ https://wiki.postgresql.org/wiki/PostgreSQL_Clients#Open_Source
|
| |
+
|
| |
+
|
| |
+ Resetting the database
|
| |
+ ----------------------
|
| |
+
|
| |
+ If you want to simply reset the *blockerbugs* database into the default empty state (i.e. no tables), instead of restoring from a backup, you can either a) remove the current container and create :ref:`a new one from scratch <set-up-database>`, or b) you can even faster drop the existing database and create a new empty one like this::
|
| |
+
|
| |
+ dropdb --host=localhost --username=postgres blockerbugs
|
| |
+ createdb --host=localhost --username=postgres blockerbugs
|
| |
+
|
| |
+ You can then continue with :ref:`initializing the environment <initializing_env>`.
|
| |
+
|
| |
Release Process
|
| |
===============
|
| |
|
| |
@@ -114,6 +183,9 @@
|
| |
|
| |
make kojibuild
|
| |
|
| |
+
|
| |
+ .. _using-alembic:
|
| |
+
|
| |
Using Alembic
|
| |
=============
|
| |
|
| |
@@ -121,6 +193,9 @@
|
| |
lightweight database migration tool for usage with the SQLAlchemy Database
|
| |
Toolkit for Python.' and used to manage the database schema used with the application.
|
| |
|
| |
+ .. warning::
|
| |
+ Always use a PostgreSQL database when creating and testing an Alembic script. That's the same database we use for :doc:`production <installation>`. The autogeneration code will differ when created on different databases, that's why PostgreSQL must be used. Certain operations also behave differently. In particular, an SQLite database will fail for most table altering operations (like changing or dropping a column).
|
| |
+
|
| |
To install alembic, use (inside the virtualenv)::
|
| |
|
| |
pip install alembic
|
| |
@@ -141,8 +216,8 @@
|
| |
|
| |
alembic revision -m "Create a table"
|
| |
|
| |
- This will create a file called, e.g., 42d71a06dd50_create_a_table.py in
|
| |
- alembic/versions. The file contains *upgrade* and *downgrade* methods that need
|
| |
+ This will create a file called, e.g., ``42d71a06dd50_create_a_table.py`` in
|
| |
+ ``alembic/versions/``. The file contains *upgrade* and *downgrade* methods that need
|
| |
to be adjusted to reflect desired migration.
|
| |
|
| |
In many cases, alembic is able to determine the steps needed for upgrade and
|
| |
jskladan commented 2 years ago
@frantisekz - I'm not sure about the build process now, don't we use requirements.txt to generate the specfile deps now? If so, how does it fare with the
psycopg2-binary?