# Django PostgreSQL Copy
The package `django-pg-copy` provides Django management commands for backing up and restoring PostgreSQL databases. These were developed for copying production databases to development, to allow developers to share images with one another, or bring local development databases up to date. It can also be handy for creating different local databases for different branches, and for only creating one migration after tweaking models to get them the way they need to be.
We also use it with Jenkins to automatically back up production, and restore to a staging database environment, so we can test new migrations repeatedly to ensure they'll work when we run them in production.
## Installation
`pip install django-pg-copy`
Then add `'pg_copy',` to your `INSTALLED_APPS` list. It is recommended that it is used in all environments (development, production) so that you can use it against different instances of your database.
## Settings
`PG_COPY_BACKUP_PATH = 'db_backup'`
By default, PostgreSQL file backups will be stored in a directory called `db_backup` where you run the command. This setting will override that location.
It is also recommended to add this path to your `.gitignore` file, if the path falls under your version control repository.
## Parameters
* `--database`: The database defined in the DATABASES settings to backup from or restore to.
* `--db-override`: A value to override the db argument sent to psql.
* `--host-override`: A value to override the host argument sent to psql.
* `--pg-home`: The path to the PostgreSQL installation, if it is not on your path.
* `--file`, `-f`: The filename to backup to, or restore from.
* `--jobs`, `-j`: The number of parallel jobs to run. This can *drastically* increase the speed of the backup and restore. When backing up, this must use the `--directory` option. *Be careful!* This will also create multiple database connections and can slow your database down.
* `--directory`, `-d`: Restore from a directory. Overrides `--file` when used.
### Backup Only Parameters for `pg_backup`
* `--ignore-table`, `-i`: Excludes the table completely during the backup process. Can pass multiple tables: `-i bigtable1 -i bigtable2`
* `--exclude-table-data`, `-e`: Excludes the table data during the backup process. Can pass multiple tables: `-e bigtable1 -e bigtable2`
### Restore Only Parameters for `pg_restore`
* `--no-drop`: Restores the database without performing a `DROP OWNED BY`.
* `--no-confirm`: Restores the database without confirmation: be careful! DON'T OVERWRITE YOUR PROD DATABASE! (Ask me how I know.)
## Example Commands
`python manage.py pg_backup`
Creates a backup file in the directory `./db_backup/` (or the directory you specified with `PG_COPY_BACKUP_PATH`) called `[timestamp].sqlc` using the `default` settings from `DATABASES` using the default Django settings file resolved by `manage.py`.
`python manage.py pg_backup --directory=/tmp/pg_backup --jobs=8`
This command will create a backup directory at `/tmp/backup` using 8 parallel jobs and database connections. This is typically *much* faster.
`python manage.py pg_backup --settings=config.settings.production --database=default --filename=my_backup.sqlc`
This command will create a backup in the same directory as `manage.py` called `my_backup.sqlc` using the `default` settings from `DATABASES` using the Django settings file located at `config/settings/production.py`.
`python manage.py pg_backup -i bigtable1 -i bigtable2`
This will do the same as the previous command, but omit the tables named `bigtable1` and `bigtable2`.
`python manage.py pg_backup -e bigtable1 -e bigtable2`
This will do the same as the previous command, but include the table structure without any data for the tables named `bigtable1` and `bigtable2`.
`python manage.py pg_restore`
This command will provide a list of backup files in `PG_COPY_BACKUP_PATH` that can be restored. After selecting a backup file, it will confirm that the user wants to overwrite the destination database by showing which server and database will be overwritten from the settings. Here's what it will look like:
```bash
(venv) [django-project]$ ./manage.py pg_restore
There are 8 backup files in '/var/dev/username/django-project/db_backup'. Which would you like to restore?
1: 2020-05-27-13-33-38.sqlc
2: 2020-05-10-09-07-45.sqlc
3: 2020-05-11-13-05-49.sqlc
4: 2020-07-14-15-21-22.sqlc
5: 2020-05-15-08-31-59.sqlc
6: 2020-06-11-13-11-00.sqlc
7: 2020-06-02-13-28-09.sqlc
8: 2020-05-27-14-54-15.sqlc
Enter number of the file to restore: 4
About to restore 'django_project_db' on host 'localhost' from the file:
'/var/dev/username/django-project/db_backup/2020-07-14-15-21-22.sqlc'.
THIS WILL OVERWRITE THE DATABASE.
Type "yes" to start the restore [no]: yes
```
`python manage.py pg_restore --filename=my_file.sqlc --no-confirm`
This command will read the file `my_file.sqlc` and **skip confirmation** that the user wants to overwrite the destination database.
`python manage.py pg_restore --directory=/tmp/pg_backup --jobs=8`
This command will restore from the directory `/tmp/pg_backup` using 8 parallel jobs and database connections.
## Known Issues
#### Errors Displayed During `pg_restore`
When restoring, PostgreSQL's `pg_restore` command may output some warnings and erorrs. I haven't figured out a command line option to make these warnings disappear, but they can likely be ignored if you read them. Here is an example of what these errors may look like:
```bash
pg_restore: [archiver (db)] Error while PROCESSING TOC:
pg_restore: [archiver (db)] Error from TOC entry 1; 3079 13792 EXTENSION plpgsql
pg_restore: [archiver (db)] could not execute query: ERROR: must be owner of extension plpgsql
Command was: DROP EXTENSION IF EXISTS plpgsql;
pg_restore: [archiver (db)] Error from TOC entry 6; 2615 2200 SCHEMA public postgres
pg_restore: [archiver (db)] could not execute query: ERROR: must be owner of schema public
Command was: DROP SCHEMA IF EXISTS public;
pg_restore: [archiver (db)] could not execute query: ERROR: schema "public" already exists
Command was: CREATE SCHEMA public;
```
These may be errors from extensions that aren't used, or warnings about default schemata that already exist.
## Release Notes
[Release notes are available on GitHub](https://github.com/FlipperPA/django-pg-copy/releases).
## Maintainer and Contributors
* [Our Wonderful Contributors on GitHub](https://github.com/FlipperPA/django-pg-copy/graphs/contributors)
* Maintainer: [Timothy Allen](https://github.com/FlipperPA) at [The Wharton School](https://github.com/wharton)
This package is maintained by the staff of [Wharton Research Data Services](https://wrds.wharton.upenn.edu/). We are thrilled that [The Wharton School](https://www.wharton.upenn.edu/) allows us to contribute to open-source projects. We add features as they are necessary for our projects, and try to keep up with Issues and Pull Requests as best we can. Due to constraints of time (our full time jobs!), Feature Requests without a Pull Request may not be implemented, but we are always open to new ideas and grateful for both contributors and users.
Raw data
{
"_id": null,
"home_page": null,
"name": "django-pg-copy",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "postgres, postgresql, backup, restore, database",
"author": null,
"author_email": "Tim Allen <tallen@wharton.upenn.edu>",
"download_url": "https://files.pythonhosted.org/packages/aa/42/22ecc6aa06ca3b92d62dbaa1ccfe74264ed8a1b0c055fffa7a80d984cdd2/django_pg_copy-1.2.0.tar.gz",
"platform": null,
"description": "# Django PostgreSQL Copy\n\nThe package `django-pg-copy` provides Django management commands for backing up and restoring PostgreSQL databases. These were developed for copying production databases to development, to allow developers to share images with one another, or bring local development databases up to date. It can also be handy for creating different local databases for different branches, and for only creating one migration after tweaking models to get them the way they need to be.\n\nWe also use it with Jenkins to automatically back up production, and restore to a staging database environment, so we can test new migrations repeatedly to ensure they'll work when we run them in production.\n\n## Installation\n\n`pip install django-pg-copy`\n\nThen add `'pg_copy',` to your `INSTALLED_APPS` list. It is recommended that it is used in all environments (development, production) so that you can use it against different instances of your database.\n\n## Settings\n\n`PG_COPY_BACKUP_PATH = 'db_backup'`\n\nBy default, PostgreSQL file backups will be stored in a directory called `db_backup` where you run the command. This setting will override that location.\n\nIt is also recommended to add this path to your `.gitignore` file, if the path falls under your version control repository.\n\n## Parameters\n\n* `--database`: The database defined in the DATABASES settings to backup from or restore to.\n* `--db-override`: A value to override the db argument sent to psql.\n* `--host-override`: A value to override the host argument sent to psql.\n* `--pg-home`: The path to the PostgreSQL installation, if it is not on your path.\n* `--file`, `-f`: The filename to backup to, or restore from.\n* `--jobs`, `-j`: The number of parallel jobs to run. This can *drastically* increase the speed of the backup and restore. When backing up, this must use the `--directory` option. *Be careful!* This will also create multiple database connections and can slow your database down.\n* `--directory`, `-d`: Restore from a directory. Overrides `--file` when used.\n\n### Backup Only Parameters for `pg_backup`\n\n* `--ignore-table`, `-i`: Excludes the table completely during the backup process. Can pass multiple tables: `-i bigtable1 -i bigtable2`\n* `--exclude-table-data`, `-e`: Excludes the table data during the backup process. Can pass multiple tables: `-e bigtable1 -e bigtable2`\n\n### Restore Only Parameters for `pg_restore`\n\n* `--no-drop`: Restores the database without performing a `DROP OWNED BY`.\n* `--no-confirm`: Restores the database without confirmation: be careful! DON'T OVERWRITE YOUR PROD DATABASE! (Ask me how I know.)\n\n## Example Commands\n\n`python manage.py pg_backup`\n\nCreates a backup file in the directory `./db_backup/` (or the directory you specified with `PG_COPY_BACKUP_PATH`) called `[timestamp].sqlc` using the `default` settings from `DATABASES` using the default Django settings file resolved by `manage.py`.\n\n`python manage.py pg_backup --directory=/tmp/pg_backup --jobs=8`\n\nThis command will create a backup directory at `/tmp/backup` using 8 parallel jobs and database connections. This is typically *much* faster.\n\n`python manage.py pg_backup --settings=config.settings.production --database=default --filename=my_backup.sqlc`\n\nThis command will create a backup in the same directory as `manage.py` called `my_backup.sqlc` using the `default` settings from `DATABASES` using the Django settings file located at `config/settings/production.py`.\n\n`python manage.py pg_backup -i bigtable1 -i bigtable2`\n\nThis will do the same as the previous command, but omit the tables named `bigtable1` and `bigtable2`.\n\n`python manage.py pg_backup -e bigtable1 -e bigtable2`\n\nThis will do the same as the previous command, but include the table structure without any data for the tables named `bigtable1` and `bigtable2`.\n\n`python manage.py pg_restore`\n\nThis command will provide a list of backup files in `PG_COPY_BACKUP_PATH` that can be restored. After selecting a backup file, it will confirm that the user wants to overwrite the destination database by showing which server and database will be overwritten from the settings. Here's what it will look like:\n\n```bash\n(venv) [django-project]$ ./manage.py pg_restore\nThere are 8 backup files in '/var/dev/username/django-project/db_backup'. Which would you like to restore?\n1: 2020-05-27-13-33-38.sqlc\n2: 2020-05-10-09-07-45.sqlc\n3: 2020-05-11-13-05-49.sqlc\n4: 2020-07-14-15-21-22.sqlc\n5: 2020-05-15-08-31-59.sqlc\n6: 2020-06-11-13-11-00.sqlc\n7: 2020-06-02-13-28-09.sqlc\n8: 2020-05-27-14-54-15.sqlc\nEnter number of the file to restore: 4\nAbout to restore 'django_project_db' on host 'localhost' from the file:\n'/var/dev/username/django-project/db_backup/2020-07-14-15-21-22.sqlc'.\nTHIS WILL OVERWRITE THE DATABASE.\nType \"yes\" to start the restore [no]: yes\n```\n\n`python manage.py pg_restore --filename=my_file.sqlc --no-confirm`\n\nThis command will read the file `my_file.sqlc` and **skip confirmation** that the user wants to overwrite the destination database.\n\n`python manage.py pg_restore --directory=/tmp/pg_backup --jobs=8`\n\nThis command will restore from the directory `/tmp/pg_backup` using 8 parallel jobs and database connections.\n\n## Known Issues\n\n#### Errors Displayed During `pg_restore`\n\nWhen restoring, PostgreSQL's `pg_restore` command may output some warnings and erorrs. I haven't figured out a command line option to make these warnings disappear, but they can likely be ignored if you read them. Here is an example of what these errors may look like:\n\n```bash\npg_restore: [archiver (db)] Error while PROCESSING TOC:\npg_restore: [archiver (db)] Error from TOC entry 1; 3079 13792 EXTENSION plpgsql\npg_restore: [archiver (db)] could not execute query: ERROR: must be owner of extension plpgsql\n Command was: DROP EXTENSION IF EXISTS plpgsql;\n\npg_restore: [archiver (db)] Error from TOC entry 6; 2615 2200 SCHEMA public postgres\npg_restore: [archiver (db)] could not execute query: ERROR: must be owner of schema public\n Command was: DROP SCHEMA IF EXISTS public;\n\npg_restore: [archiver (db)] could not execute query: ERROR: schema \"public\" already exists\n Command was: CREATE SCHEMA public;\n```\n\nThese may be errors from extensions that aren't used, or warnings about default schemata that already exist.\n\n## Release Notes\n\n[Release notes are available on GitHub](https://github.com/FlipperPA/django-pg-copy/releases).\n\n## Maintainer and Contributors\n\n* [Our Wonderful Contributors on GitHub](https://github.com/FlipperPA/django-pg-copy/graphs/contributors)\n* Maintainer: [Timothy Allen](https://github.com/FlipperPA) at [The Wharton School](https://github.com/wharton)\n\nThis package is maintained by the staff of [Wharton Research Data Services](https://wrds.wharton.upenn.edu/). We are thrilled that [The Wharton School](https://www.wharton.upenn.edu/) allows us to contribute to open-source projects. We add features as they are necessary for our projects, and try to keep up with Issues and Pull Requests as best we can. Due to constraints of time (our full time jobs!), Feature Requests without a Pull Request may not be implemented, but we are always open to new ideas and grateful for both contributors and users.\n",
"bugtrack_url": null,
"license": "BSD-3-Clause",
"summary": "Django management command to backup and restore PostgreSQL databases using the DATABASES settings.",
"version": "1.2.0",
"project_urls": {
"Documentation": "https://github.com/FlipperPA/django-pg-copy",
"Homepage": "https://github.com/FlipperPA/django-pg-copy",
"Repository": "https://github.com/FlipperPA/django-pg-copy"
},
"split_keywords": [
"postgres",
" postgresql",
" backup",
" restore",
" database"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e8d4d3d8b19452e474e55591a074ceda86df22ff61777cbb87bdfd9897bfa98e",
"md5": "dc1d4c97f71b9b750e56fdf099e48870",
"sha256": "26cda04892eccd6bb0dea73eca2b02d1870e6f1147ec1bba5c580c784ce66316"
},
"downloads": -1,
"filename": "django_pg_copy-1.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "dc1d4c97f71b9b750e56fdf099e48870",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 9793,
"upload_time": "2024-07-22T14:44:58",
"upload_time_iso_8601": "2024-07-22T14:44:58.423080Z",
"url": "https://files.pythonhosted.org/packages/e8/d4/d3d8b19452e474e55591a074ceda86df22ff61777cbb87bdfd9897bfa98e/django_pg_copy-1.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "aa4222ecc6aa06ca3b92d62dbaa1ccfe74264ed8a1b0c055fffa7a80d984cdd2",
"md5": "108b2d5b3e5c491061b3b56a917f2201",
"sha256": "aab7895c054f1fe36c24e1b763ce4482615cffd9ab0e6e8d56a25afd6504d1c8"
},
"downloads": -1,
"filename": "django_pg_copy-1.2.0.tar.gz",
"has_sig": false,
"md5_digest": "108b2d5b3e5c491061b3b56a917f2201",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 8987,
"upload_time": "2024-07-22T14:45:01",
"upload_time_iso_8601": "2024-07-22T14:45:01.392465Z",
"url": "https://files.pythonhosted.org/packages/aa/42/22ecc6aa06ca3b92d62dbaa1ccfe74264ed8a1b0c055fffa7a80d984cdd2/django_pg_copy-1.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-22 14:45:01",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "FlipperPA",
"github_project": "django-pg-copy",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "django-pg-copy"
}
JSON
