{"id":19989919,"url":"https://github.com/saracen/kubeql","last_synced_at":"2026-01-12T01:57:32.931Z","repository":{"id":57527458,"uuid":"107827330","full_name":"saracen/kubeql","owner":"saracen","description":"Kubeql is a SQL-like query language for Kubernetes.","archived":false,"fork":false,"pushed_at":"2017-10-24T23:41:52.000Z","size":24,"stargazers_count":58,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-05-04T09:37:33.579Z","etag":null,"topics":["kubernetes","sql"],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/saracen.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-10-22T00:57:41.000Z","updated_at":"2025-01-15T05:32:34.000Z","dependencies_parsed_at":"2022-09-07T05:31:05.080Z","dependency_job_id":null,"html_url":"https://github.com/saracen/kubeql","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/saracen/kubeql","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/saracen%2Fkubeql","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/saracen%2Fkubeql/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/saracen%2Fkubeql/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/saracen%2Fkubeql/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/saracen","download_url":"https://codeload.github.com/saracen/kubeql/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/saracen%2Fkubeql/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28331401,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-12T00:36:25.062Z","status":"ssl_error","status_checked_at":"2026-01-12T00:36:15.229Z","response_time":60,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["kubernetes","sql"],"created_at":"2024-11-13T04:50:47.669Z","updated_at":"2026-01-12T01:57:32.915Z","avatar_url":"https://github.com/saracen.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"# kubeql\r\n\r\nKubeql, pronounced \"cubicle\", is a SQL-like query language for Kubernetes\r\nresources.\r\n\r\nIt *might* be handy for simple queries, but at the moment, it is very much a toy\r\nproject for me to learn about parsers, lexers and evaluators.\r\n\r\nThings you can do:\r\n\r\n### Simple selections\r\n\r\n`-\u003e` is currently used over dot-notation, as dot notation is commonly used in\r\nJSONPath and \"jq\" like expressions. In contrast, `-\u003e` access is simple, and only\r\nsupports direct-\u003epath-\u003eaccess. It supports map and array access (`array-\u003e0-\u003eitem`).\r\n\r\n```\r\n$ ./kubeql -execute \"select pods-\u003emetadata-\u003elabels as labels from pods\"\r\n\r\nlabels\r\n------\r\n{\"app\":\"redmine-test-2-mariadb\",\"pod-template-hash\":\"384399387\"}\r\n{\"app\":\"redmine-test-2-redmine\",\"pod-template-hash\":\"411540601\"}\r\n{\"app\":\"redmine-test-2-redmine\",\"pod-template-hash\":\"411540601\"}\r\n{\"k8s-app\":\"event-exporter\",\"pod-template-hash\":\"1421584133\",\"version\":\"v0.1.5\"}\r\n...\r\n```\r\n\r\nThe same `-\u003e` path expressions can be used for filtering.\r\n\r\n```\r\n$ ./kubeql -execute \"select pods-\u003emetadata-\u003elabels as labels from pods where pods-\u003emetadata-\u003elabels-\u003eapp\"\r\n\r\nlabels\r\n------\r\n{\"app\":\"redmine-test-2-mariadb\",\"pod-template-hash\":\"384399387\"}\r\n{\"app\":\"redmine-test-2-redmine\",\"pod-template-hash\":\"411540601\"}\r\n{\"app\":\"redmine-test-2-redmine\",\"pod-template-hash\":\"411540601\"}\r\n{\"app\":\"helm\",\"name\":\"tiller\",\"pod-template-hash\":\"1936853538\"}\r\n```\r\n```\r\n$ ./kubeql -execute \"select pods-\u003emetadata-\u003elabels as labels from pods where pods-\u003emetadata-\u003elabels-\u003eapp = 'helm'\"\r\n\r\nlabels\r\n------\r\n{\"app\":\"helm\",\"name\":\"tiller\",\"pod-template-hash\":\"1936853538\"}\r\n```\r\n\r\n```\r\n$ ./kubeql -execute \"select pods-\u003espec-\u003econtainers-\u003e0-\u003ename as names from pods\"\r\n\r\nnames\r\n-----\r\n\"redmine-test-2-mariadb\"\r\n\"redmine-test-2-redmine\"\r\n\"redmine-test-2-redmine\"\r\n\"event-exporter\"\r\n...\r\n```\r\n\r\n### Resource access\r\n\r\nKubeql can access non-core v1 resources by a fully qualified name\r\n(eg: `apps/v1beta1/deployments`), and core v1 resources by their short-name\r\n(pods, endpoints, services, configmaps, secrets, persistentvolumeclaims, events\r\netc).\r\n\r\n\r\n```\r\n$ ./kubeql -execute \"select deployments-\u003emetadata-\u003ename as deployment_name FROM apps/v1beta1/deployments\"\r\n\r\ndeployment_name\r\n---------------\r\n\"redmine-test-2-mariadb\"\r\n\"redmine-test-2-redmine\"\r\n\"event-exporter\"\r\n\"heapster-v1.4.2\"\r\n...\r\n```\r\n\r\n### Indexes\r\n\r\nKubeql **does not yet** fetch efficiently from the backend. In the future, I\r\nhope I can use the label/field selector to fetch fewer results than required so\r\nthat there's less to be processed by the client.\r\n\r\n### Namespaces\r\n\r\nUsing the `NAMESPACE` keyword will only fetch resources from the specified namespace.\r\n\r\n`select deployments FROM apps/v1beta1/deployments NAMESPACE default`\r\n\r\n### Joins\r\n\r\nKubectl at the moment only supports SQL ANSI-89 JOIN functionality, by selecting\r\nfrom multiple tables.\r\n\r\n```\r\n$ ./kubeql -execute \"select deployments-\u003emetadata-\u003ename as deployment_name, pods-\u003emetadata-\u003ename as pod_name FROM apps/v1beta1/deployments, pods where pods-\u003emetadata-\u003elabels-\u003eapp = deployments-\u003emetadata-\u003elabels-\u003eapp\"\r\n\r\ndeployment_name          pod_name\r\n---------------          --------\r\n\"redmine-test-2-mariadb\" \"redmine-test-2-mariadb-384399387-dz3xq\"\r\n\"redmine-test-2-redmine\" \"redmine-test-2-redmine-411540601-320ws\"\r\n\"redmine-test-2-redmine\" \"redmine-test-2-redmine-411540601-938tq\"\r\n\"tiller-deploy\"          \"tiller-deploy-1936853538-hvjnm\"\r\n```\r\n\r\n### JSONPath\r\n\r\nKubeql supports kubernetes' implementation of JSONPath templating.\r\n\r\n```\r\n$ ./kubeql -execute \"select jsonpath(pods-\u003emetadata, '{.labels}') as labels from pods\"\r\n\r\nlabels\r\n------\r\n[{\"app\":\"redmine-test-2-mariadb\",\"pod-template-hash\":\"384399387\"}]\r\n[{\"app\":\"redmine-test-2-redmine\",\"pod-template-hash\":\"411540601\"}]\r\n[{\"app\":\"redmine-test-2-redmine\",\"pod-template-hash\":\"411540601\"}]\r\n[{\"k8s-app\":\"event-exporter\",\"pod-template-hash\":\"1421584133\",\"version\":\"v0.1.5\"}]\r\n[{\"controller-revision-hash\":\"1419153066\",\"k8s-app\":\"fluentd-gcp\",\"kubernetes.io/cluster-service\":\"true\",\"pod-template-generation\":\"1\",\"version\":\"v2.0\"}]\r\n...\r\n```\r\n\r\n### JQ\r\n\r\nKubeql supports JQ-style selecting/filtering.\r\n\r\n```\r\n$ ./kubeql -execute \"select jq(deployments-\u003emetadata, '.labels.app') as deployment_name FROM apps/v1beta1/deployments\"\r\n\r\ndeployment_name\r\n---------------\r\n[\"redmine-test-2-mariadb\"]\r\n[\"redmine-test-2-redmine\"]\r\n[null]\r\n[null]\r\n[\"helm\"]\r\n```\r\n\r\nBecause `jsonpath` and `jq` return arrays, you can always combine this with\r\nKubeql's `-\u003e` path expressions to return a single result:\r\n\r\n```\r\n$ ./kubeql -execute \"select jq(deployments-\u003emetadata, '.labels.app')-\u003e0 as deployment_name FROM apps/v1beta1/deployments\"\r\n\r\ndeployment_name\r\n---------------\r\n\"redmine-test-2-mariadb\"\r\n\"redmine-test-2-redmine\"\r\nnull\r\nnull\r\n\"helm\"\r\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsaracen%2Fkubeql","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsaracen%2Fkubeql","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsaracen%2Fkubeql/lists"}