# `swoop-db`
The swoop database schema is managed via
[`dbami`](https://github.com/element84/dbami), and uses `dbami` to implement a
custom cli and python library for managing databases for
[swoop](https://github.com/element84/swoop).
## Installing `swoop-db`
`swoop-db` can be `pip` installed:
```shell
pip install swoop.db
```
If wanting to install locally for development purposes, see
[`CONTRIBUTING.md`](./CONTRIBUTING.md) for further instructions.
## Postgres Extensions
`swoop-db` makes use of two postgres extensions:
* `pg_partman`: an automated table partition manager
* `pgTap`: a postgres-native testing framework
`pgTap` is only used for testing, and is not installed into the schema except
when testing.
## Database testing with docker
[`./Dockerfile`](./Dockerfile) defines the build steps for a database test
container. The container includes the requsite postgres extensions. As the
Dockerfile builds an image with all the database dependencies with fixed
versions, using docker with that image is strongly recommended for all testing
to help guarantee consistency between developers (running postgres in another
way is fine if desired, but does require that the necessary extensions and
utilities are installed, and that the connection information is correctly
configured for tooling).
To make using the docker container more convenient, a `docker-compose.yml` file
is provided in the project root. The repo contents are mounted as `/swoop/db/`
inside the container to help facilitate database operations and testing using
the included utilities. For example, to bring up the database and run the
tests:
```shell
# load the .env vars
source .env
# bring up the database container in the background
# --build forces rebuild of the container in case changes have been made
# -V recreates any volumes instead of reusing data
# -d run the composed images in daemon mode rather than in the foreground
docker compose up --build -V -d
# create the database and apply all migrations
swoop-db up
# connect to the database with psql
docker compose exec postgres psql -U postgres swoop
# create the database and load the schema.sql with a custom database name
swoop-db create --database swoop-custom
swoop-db load-schema --database swoop-custom
```
To verify the schema and migrations match:
```shell
# run the verification; any diff indicates schema/migrations out-of-sync
swoop-db verify
```
To drop a database:
```shell
# we'll drop the custom one we made earlier
swoop-db drop --database swoop-custom
```
To stop the postgres container:
```shell
docker compose down
```
The `swoop-db` cli is intended to be discoverable. When in doubt, try checking
the help.
Raw data
{
"_id": null,
"home_page": "",
"name": "swoop.db",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "",
"keywords": "postgresql,sql,stac,workflow,geospatial",
"author": "",
"author_email": "Jarrett Keifer <jkeifer@element84.com>",
"download_url": "https://files.pythonhosted.org/packages/58/c0/7eac03444b1c0be995a9dd606ef71484fca198874cb4cdbc345d917c6703/swoop.db-8.0.3.tar.gz",
"platform": null,
"description": "# `swoop-db`\n\nThe swoop database schema is managed via\n[`dbami`](https://github.com/element84/dbami), and uses `dbami` to implement a\ncustom cli and python library for managing databases for\n[swoop](https://github.com/element84/swoop).\n\n## Installing `swoop-db`\n\n`swoop-db` can be `pip` installed:\n\n```shell\npip install swoop.db\n```\n\nIf wanting to install locally for development purposes, see\n[`CONTRIBUTING.md`](./CONTRIBUTING.md) for further instructions.\n\n## Postgres Extensions\n\n`swoop-db` makes use of two postgres extensions:\n\n* `pg_partman`: an automated table partition manager\n* `pgTap`: a postgres-native testing framework\n\n`pgTap` is only used for testing, and is not installed into the schema except\nwhen testing.\n\n## Database testing with docker\n\n[`./Dockerfile`](./Dockerfile) defines the build steps for a database test\ncontainer. The container includes the requsite postgres extensions. As the\nDockerfile builds an image with all the database dependencies with fixed\nversions, using docker with that image is strongly recommended for all testing\nto help guarantee consistency between developers (running postgres in another\nway is fine if desired, but does require that the necessary extensions and\nutilities are installed, and that the connection information is correctly\nconfigured for tooling).\n\nTo make using the docker container more convenient, a `docker-compose.yml` file\nis provided in the project root. The repo contents are mounted as `/swoop/db/`\ninside the container to help facilitate database operations and testing using\nthe included utilities. For example, to bring up the database and run the\ntests:\n\n```shell\n# load the .env vars\nsource .env\n\n# bring up the database container in the background\n# --build forces rebuild of the container in case changes have been made\n# -V recreates any volumes instead of reusing data\n# -d run the composed images in daemon mode rather than in the foreground\ndocker compose up --build -V -d\n\n# create the database and apply all migrations\nswoop-db up\n\n# connect to the database with psql\ndocker compose exec postgres psql -U postgres swoop\n\n# create the database and load the schema.sql with a custom database name\nswoop-db create --database swoop-custom\nswoop-db load-schema --database swoop-custom\n```\n\nTo verify the schema and migrations match:\n\n```shell\n# run the verification; any diff indicates schema/migrations out-of-sync\nswoop-db verify\n```\n\nTo drop a database:\n\n```shell\n# we'll drop the custom one we made earlier\nswoop-db drop --database swoop-custom\n```\n\nTo stop the postgres container:\n\n```shell\ndocker compose down\n```\n\nThe `swoop-db` cli is intended to be discoverable. When in doubt, try checking\nthe help.\n",
"bugtrack_url": null,
"license": "Apache License 2.0",
"summary": "Database for STAC Workflow Open Orchestration Framework",
"version": "8.0.3",
"project_urls": null,
"split_keywords": [
"postgresql",
"sql",
"stac",
"workflow",
"geospatial"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0dcad47c5fc758c81969da87113d3c144c51dd23e940d3c366d9ad3b2ee3c2c6",
"md5": "ed4cd8b493bb737a33feeb33d929850d",
"sha256": "a018d2dfb850131370171fa2972b391d7c35f6e8dabbd738aa7263ae70b95625"
},
"downloads": -1,
"filename": "swoop.db-8.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ed4cd8b493bb737a33feeb33d929850d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 21160,
"upload_time": "2023-08-23T01:53:22",
"upload_time_iso_8601": "2023-08-23T01:53:22.198959Z",
"url": "https://files.pythonhosted.org/packages/0d/ca/d47c5fc758c81969da87113d3c144c51dd23e940d3c366d9ad3b2ee3c2c6/swoop.db-8.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "58c07eac03444b1c0be995a9dd606ef71484fca198874cb4cdbc345d917c6703",
"md5": "712bf83b1e68cdfebd5a7ab5ba556110",
"sha256": "fa9bc05dad0591af804162daaa80f4f6a7e5584b925f686f164906beea2d132e"
},
"downloads": -1,
"filename": "swoop.db-8.0.3.tar.gz",
"has_sig": false,
"md5_digest": "712bf83b1e68cdfebd5a7ab5ba556110",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 33499,
"upload_time": "2023-08-23T01:53:23",
"upload_time_iso_8601": "2023-08-23T01:53:23.749760Z",
"url": "https://files.pythonhosted.org/packages/58/c0/7eac03444b1c0be995a9dd606ef71484fca198874cb4cdbc345d917c6703/swoop.db-8.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-23 01:53:23",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "swoop.db"
}
JSON