Skip to content

Add sample database page to getting started docs #444

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
EngCaioFonseca wants to merge 4 commits into
base: main
Choose a base branch
from
+33 −0
Open

Add sample database page to getting started docs #444

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
739703b
Add sample database page to getting started docs
EngCaioFonseca Jul 14, 2026
03caa0a
Apply suggestion from @MoralCode
EngCaioFonseca Jul 15, 2026
1dc3d75
removing notes from readme
EngCaioFonseca Jul 15, 2026
31dcd27
removing bits of info related to 8Knot to be able to transfer it to 8…
EngCaioFonseca Jul 15, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 32 additions & 0 deletions docs/source/getting-started/sample-database.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
Sample Database
===============

We have a ready-to-use PostgreSQL database that acts as a structurally-correct sample dataset. This is a postgres container image pre-loaded with data collected by CollectOSS that can be used to help you get started quickly with your downstream project that relies on CollectOSS data, whether thats running `8Knot <https://github.com/oss-aspen/8Knot>`_, using jupyter notebooks for research, or building your own dashboard.

Image: ``ghcr.io/oss-aspen/sample-collected-data:latest``

@MoralCode MoralCode Jul 16, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Using the image
---------------
The easiest way to use the image is to create a `docker-compose.yml` file in a new directory with the following contents:
```yaml
 services:
  sample-collected-data:
     image: ghcr.io/oss-aspen/sample-collected-data:latest
     ports:
       - "5433:5432"  # exposed on 5433 to avoid clashing with a local postgres
     environment:
       POSTGRES_DB: sample_collected_data
       POSTGRES_USER: sample_user
       POSTGRES_PASSWORD: sample_password
     healthcheck:
       test: ["CMD-SHELL", "pg_isready -U sample_user -d sample_collected_data"]
       interval: 5s
       timeout: 5s
       retries: 10
```
Once this file exists, running `docker compose up` from this directory will bring the database up and allow you to connect as explained in the next section.


Connecting directly (psql, DBeaver, notebooks)
----------------------------------------------

The database is also exposed on **host port 5433** (mapped from the container's

@MoralCode MoralCode Jul 16, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The database is also exposed on **host port 5433** (mapped from the container's
If you are using the compose file above, the database will be exposed on port 5433 on your machine (mapped from the container's

5432, so it won't clash with a local PostgreSQL):

======== =========================
Setting Value
======== =========================
Host ``localhost``
Port ``5433``
Database ``sample_collected_data``
User ``sample_user``
Password ``sample_password``
======== =========================

.. code:: shell

psql -h localhost -p 5433 -U sample_user -d sample_collected_data

Tables live in the ``data`` schema (the CollectOSS schema name), so qualify
queries — for example ``data.repo``, ``data.commits``, ``data.pull_requests``.


1 change: 1 addition & 0 deletions docs/source/getting-started/toc.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,5 +25,6 @@ Happy hacking!
:maxdepth: 1

database
sample-database
collecting-data
command-line-interface/toc
Loading