From b6b6805658e48b982475d707f7238ffa3bd08ffd Mon Sep 17 00:00:00 2001 From: Patrick DeVivo Date: Mon, 2 Aug 2021 16:52:23 -0400 Subject: [PATCH 1/5] start documenting the GitHub tables --- README.md | 126 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 126 insertions(+) diff --git a/README.md b/README.md index 9e753378..346f20cd 100644 --- a/README.md +++ b/README.md @@ -371,6 +371,132 @@ SELECT enry_is_vendor('vendor/file.go') ``` + +#### GitHub API + +You can use `askgit` to query the GitHub API (v4). +Constraints in your SQL are pushed out to the GitHub API as much as possible. +For instance, if your query includes an `ORDER BY` and if items can be ordered by the GitHub API on the specified column, your query can avoid doing a full table scan and rely on the ordering done by the GitHub API. + +You must provide an authentication token in order to use the GitHub API tables. +You can create a personal access token [following these instructions](https://docs.github.com/en/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token). +`askgit` will look for a `GITHUB_TOKEN` environment variable when executing, to use for authentication. +This is also true if running as a runtime loadable extension. + +##### `github_stargazers` + +Table-valued-function that returns a list of users who have starred a repository. + +| Column | Type | +|------------|------| +| login | TEXT | +| email | TEXT | +| name | TEXT | +| bio | TEXT | +| company | TEXT | +| avatar_url | TEXT | +| created_at | TEXT | +| updated_at | TEXT | +| twitter | TEXT | +| website | TEXT | +| location | TEXT | +| starred_at | TEXT | + +Params: + 1. `fullNameOrOwner` - either the full repo name `askgitdev/askgit` or just the owner `askgit` (which would require the second argument) + 2. `name` - optional if the first argument is a "full" name, otherwise required - the name of the repo + +```sql +SELECT * FROM github_stargazers('askgitdev', 'askgit'); +SELECT * FROM github_stargazers('askgitdev/askgit'); -- both are equivalent +``` + +##### `github_starred_repos` + +Table-valued-function that returns a list of repositories a user has starred. + +| Column | Type | +|-----------------|------| +| name | TEXT | +| url | TEXT | +| description | TEXT | +| created_at | TEXT | +| pushed_at | TEXT | +| updated_at | TEXT | +| stargazer_count | INT | +| name_with_owner | TEXT | + +Params: + 1. `login` - the `login` of a GitHub user + +```sql +SELECT * FROM github_starred_repos('patrickdevivo') +``` + +##### `github_stargazer_count` + +Scalar function that returns the number of stars a GitHub repository has. + +Params: + 1. `fullNameOrOwner` - either the full repo name `askgitdev/askgit` or just the owner `askgit` (which would require the second argument) + 2. `name` - optional if the first argument is a "full" name, otherwise required - the name of the repo + +```sql +SELECT github_stargazer_count('askgitdev', 'askgit'); +SELECT github_stargazer_count('askgitdev/askgit'); -- both are equivalent +``` + +##### `github_repo_issues` + +Table-valued-function that returns all the issues of a GitHub repository. + +| Column | Type | +|-----------------------|-------| +| owner | TEXT | +| reponame | TEXT | +| author_login | TEXT | +| author_url | TEXT | +| body | TEXT | +| body_text | TEXT | +| closed | INT | +| closed_at | TEXT | +| comment_count | INT | +| created_at | TEXT | +| created_via_email | INT | +| database_id | TEXT | +| editor_login | TEXT | +| editor_url | TEXT | +| includes_created_edit | INT | +| is_read_by_viewer | INT | +| label_count | INT | +| last_edited_at | TEXT | +| locked | INT | +| milestone_count | INT | +| milestone_progress | FLOAT | +| issue_number | INT | +| participant_count | INT | +| published_at | TEXT | +| reaction_count | INT | +| state | TEXT | +| title | TEXT | +| updated_at | TEXT | +| url | TEXT | +| user_edits_count | INT | +| viewer_can_react | INT | +| viewer_can_subscribe | INT | +| viewer_can_update | INT | +| viewer_did_author | INT | +| viewer_subscription | TEXT | + +Params: + 1. `fullNameOrOwner` - either the full repo name `askgitdev/askgit` or just the owner `askgit` (which would require the second argument) + 2. `name` - optional if the first argument is a "full" name, otherwise required - the name of the repo + +```sql +SELECT * FROM github_repo_issues('askgitdev/askgit'); +SELECT * FROM github_repo_issues('askgitdev', 'askgit'); -- both are equivalent +``` + ### Example Queries This will return all commits in the history of the currently checked out branch/commit of the repo. From 1c16c54e01f97111a17e621b3dbe2d702fbcd143 Mon Sep 17 00:00:00 2001 From: Patrick DeVivo Date: Mon, 2 Aug 2021 17:16:08 -0400 Subject: [PATCH 2/5] wording tweaks --- README.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 346f20cd..6b503447 100644 --- a/README.md +++ b/README.md @@ -374,9 +374,11 @@ SELECT enry_is_vendor('vendor/file.go') #### GitHub API -You can use `askgit` to query the GitHub API (v4). -Constraints in your SQL are pushed out to the GitHub API as much as possible. -For instance, if your query includes an `ORDER BY` and if items can be ordered by the GitHub API on the specified column, your query can avoid doing a full table scan and rely on the ordering done by the GitHub API. +You can use `askgit` to query the [GitHub API (v4)](https://docs.github.com/en/graphql). +Constraints in your SQL query are pushed to the GitHub API as much as possible. +For instance, if your query includes an `ORDER BY` clause and if items can be ordered in the GitHub API repose (on the specified column), your query can avoid doing a full table scan and rely on the ordering returned by the API. + +##### Authenticating You must provide an authentication token in order to use the GitHub API tables. You can create a personal access token [following these instructions](https://docs.github.com/en/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token). From eedc3779b8da17203b184915014a2d421b1547fb Mon Sep 17 00:00:00 2001 From: Patrick DeVivo Date: Mon, 2 Aug 2021 17:16:46 -0400 Subject: [PATCH 3/5] typo fix --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 6b503447..0322e4e3 100644 --- a/README.md +++ b/README.md @@ -376,7 +376,7 @@ SELECT enry_is_vendor('vendor/file.go') You can use `askgit` to query the [GitHub API (v4)](https://docs.github.com/en/graphql). Constraints in your SQL query are pushed to the GitHub API as much as possible. -For instance, if your query includes an `ORDER BY` clause and if items can be ordered in the GitHub API repose (on the specified column), your query can avoid doing a full table scan and rely on the ordering returned by the API. +For instance, if your query includes an `ORDER BY` clause and if items can be ordered in the GitHub API response (on the specified column), your query can avoid doing a full table scan and rely on the ordering returned by the API. ##### Authenticating From 96ff9236a70fd8a24ae2d7364e3ab09938a6af8e Mon Sep 17 00:00:00 2001 From: Patrick DeVivo Date: Tue, 3 Aug 2021 12:32:54 -0400 Subject: [PATCH 4/5] add `starred_at` column to `github_starred_repos` doc --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index 0322e4e3..23345968 100644 --- a/README.md +++ b/README.md @@ -427,6 +427,7 @@ Table-valued-function that returns a list of repositories a user has starred. | updated_at | TEXT | | stargazer_count | INT | | name_with_owner | TEXT | +| starred_at | TEXT | Params: 1. `login` - the `login` of a GitHub user From 53c9bb139dcc366301ecf8f9471603fabb07fb85 Mon Sep 17 00:00:00 2001 From: Patrick DeVivo Date: Tue, 3 Aug 2021 21:52:20 -0400 Subject: [PATCH 5/5] add docs for `github_user_repos` and `github_org_repos` --- README.md | 44 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) diff --git a/README.md b/README.md index d94a4baa..534bed77 100644 --- a/README.md +++ b/README.md @@ -450,6 +450,50 @@ SELECT github_stargazer_count('askgitdev', 'askgit'); SELECT github_stargazer_count('askgitdev/askgit'); -- both are equivalent ``` +##### `github_user_repos` and `github_org_repos` + +Table-valued function that returns all the repositories belonging to a user or an organization. + +| Column | Type | +|-----------------------------|------| +| created_at | TEXT | +| database_id | INT | +| default_branch_ref_name | TEXT | +| default_branch_ref_prefix | TEXT | +| description | TEXT | +| disk_usage | INT | +| fork_count | INT | +| homepage_url | TEXT | +| is_archived | INT | +| is_disabled | INT | +| is_fork | INT | +| is_mirror | INT | +| is_private | INT | +| issue_count | INT | +| latest_release_author | TEXT | +| latest_release_created_at | TEXT | +| latest_release_name | TEXT | +| latest_release_published_at | TEXT | +| license_key | TEXT | +| license_name | TEXT | +| name | TEXT | +| open_graph_image_url | TEXT | +| primary_language | TEXT | +| pull_request_count | INT | +| pushed_at | TEXT | +| release_count | INT | +| stargazer_count | TEXT | +| updated_at | TEXT | +| watcher_count | INT | + +Params: + 1. `login` - the `login` of a GitHub user or organization + +```sql +SELECT * FROM github_user_repos('patrickdevivo') +SELECT * FROM github_org_repos('askgitdev') +``` + ##### `github_repo_issues` Table-valued-function that returns all the issues of a GitHub repository.