diff --git a/README.md b/README.md index 5eabd92..f2ca6e7 100644 --- a/README.md +++ b/README.md @@ -1,23 +1,41 @@ # sql-playground -📚 Learning and exploring SQL (and Postgres in particular). +📚 Learning and exploring SQL (Postgres in particular). --- -## Instructions - -Requires: Docker - -1. Start a Postgres instance using Docker Compose - * Execute `docker-compose up --detach` -1. Explore the database! - * Enter a session on the command line with `psql --username postgres --host localhost` -1. Define some test tables and test data - * Apply the DDL and DML files - * `psql --username postgres --host localhost -f observations/observations-schema.ddl` - * `psql --username postgres --host localhost -f observations/observations-data.sql` -1. Stop the Postgres Docker container - * Execute `docker-compose down` +## Standalone sub-projects + +This repository illustrates different concepts, patterns and examples via standalone sub-projects. Each sub-project is +completely independent of the others and do not depend on the root project. This _standalone sub-project constraint_ +forces the sub-projects to be complete and maximizes the reader's chances of successfully running, understanding, and +re-using the code. + +The sub-projects include: + +### `arrays/` + +Showcasing the `array` SQL data type. + +See the README in [arrays/](arrays/). + +### `lag/` + +Showcasing the `lag` Postgres function which is a part of Postgres' windowing support. + +See the README in [lag/](lag/). + +### `docker/` + +Run Postgres in a Docker container using Docker Compose. + +See the README in [docker/](docker/). + +### `administration/` + +Exploring how to administrate Postgres via its many tools like `pg_ctl`. + +See the README in [administration/](administration/). ## WishList diff --git a/postgres-administration/postgres-administration.md b/administration/administration.md similarity index 98% rename from postgres-administration/postgres-administration.md rename to administration/administration.md index f2cb84a..d6f0394 100644 --- a/postgres-administration/postgres-administration.md +++ b/administration/administration.md @@ -1,4 +1,4 @@ -# postgres-administration +# administration Exploring how to administrate Postgres via its many tools like `pg_ctl`. diff --git a/arrays/arrays.md b/arrays/arrays.md new file mode 100644 index 0000000..0c93d98 --- /dev/null +++ b/arrays/arrays.md @@ -0,0 +1,13 @@ +# arrays + +Showcasing the `array` SQL data type. + +A dataset of "observations" is used to explore the `array` data type. + +## Instructions + +* Apply the schema: + * `psql --username postgres --host localhost -f observations-schema.ddl` +* Insert test data: + * `psql --username postgres --host localhost -f observations-data.sql` +* Try out the queries in `observations-explore.sql` and learn about SQL arrays! diff --git a/observations/observations-ad-hoc-query.sh b/arrays/observations-ad-hoc-query.sh similarity index 100% rename from observations/observations-ad-hoc-query.sh rename to arrays/observations-ad-hoc-query.sh diff --git a/observations/observations-data.sql b/arrays/observations-data.sql similarity index 100% rename from observations/observations-data.sql rename to arrays/observations-data.sql diff --git a/observations/observations-explore.sql b/arrays/observations-explore.sql similarity index 100% rename from observations/observations-explore.sql rename to arrays/observations-explore.sql diff --git a/observations/observations-export.sh b/arrays/observations-export.sh similarity index 100% rename from observations/observations-export.sh rename to arrays/observations-export.sh diff --git a/observations/observations-schema.ddl b/arrays/observations-schema.ddl similarity index 100% rename from observations/observations-schema.ddl rename to arrays/observations-schema.ddl diff --git a/docker/README.md b/docker/README.md new file mode 100644 index 0000000..9a14691 --- /dev/null +++ b/docker/README.md @@ -0,0 +1,16 @@ +# docker + +Run Postgres in a Docker container using Docker Compose. + +## Instructions + +1. Start a Postgres instance using Docker Compose: + * `docker-compose up --detach` +1. Explore the database! Enter a session on the command line: + * `psql --username postgres --host localhost` +1. Stop the Postgres Docker container: + * `docker-compose down` + +## Referenced Material + +* [Docker Compose](https://docs.docker.com/compose/) diff --git a/docker-compose.yml b/docker/docker-compose.yml similarity index 100% rename from docker-compose.yml rename to docker/docker-compose.yml diff --git a/lag/lag.md b/lag/lag.md new file mode 100644 index 0000000..b49376c --- /dev/null +++ b/lag/lag.md @@ -0,0 +1,18 @@ +# lag + +Showcasing the `lag` Postgres function which is a part of Postgres' windowing support. + +Specifically, I wanted to illustrate a query where each row needs to be compared to the row preceding it. + +## Instructions + +* Apply the schema: + * `psql --username postgres --host localhost -f snapshots-schema.ddl` +* Insert test data: + * `psql --username postgres --host localhost -f snapshots-data.sql` +* Try out the queries `snapshots-explore.sql` and learn about `lag`! + +## Referenced Material + +* [Postgres official docs: "Window Functions" tutorial](https://www.postgresql.org/docs/13/tutorial-window.html) +* [Postgres official docs: "Window Functions" reference](https://www.postgresql.org/docs/13/functions-window.html) diff --git a/snapshots/snapshots-data.sql b/lag/snapshots-data.sql similarity index 100% rename from snapshots/snapshots-data.sql rename to lag/snapshots-data.sql diff --git a/snapshots/snapshots-explore.sql b/lag/snapshots-explore.sql similarity index 100% rename from snapshots/snapshots-explore.sql rename to lag/snapshots-explore.sql diff --git a/snapshots/snapshots-schema.ddl b/lag/snapshots-schema.ddl similarity index 100% rename from snapshots/snapshots-schema.ddl rename to lag/snapshots-schema.ddl diff --git a/observations/observations.md b/observations/observations.md deleted file mode 100644 index 57f0f04..0000000 --- a/observations/observations.md +++ /dev/null @@ -1,7 +0,0 @@ -# observations - -* Schema file: `observations-schema.ddl` -* Data file: `observations-data.sql` -* Exploratory SQL statements: `observations-explore.sql` - -The `observations` table and its accompanying exploratory SQL queries showcase *SQL arrays*. \ No newline at end of file diff --git a/snapshots/snapshots.md b/snapshots/snapshots.md deleted file mode 100644 index 17954c1..0000000 --- a/snapshots/snapshots.md +++ /dev/null @@ -1,16 +0,0 @@ -# snapshots - -Showcasing the `lag` Postgres function which is a part of Postgres' windowing support. Specifically, I wanted to -illustrate a query where each row needs to be compared to the row preceding it. - -### Instructions - -``` -psql --username postgres --host localhost -f snapshots/snapshots-schema.ddl -psql --username postgres --host localhost -f snapshots/snapshots-data.sql -``` - -### Referenced Material - -* [Postgres official docs: "Window Functions" tutorial](https://www.postgresql.org/docs/13/tutorial-window.html) -* [Postgres official docs: "Window Functions" reference](https://www.postgresql.org/docs/13/functions-window.html) \ No newline at end of file