{"id":32565838,"url":"https://github.com/stackql/stackql-provider-linode","last_synced_at":"2025-10-29T04:53:45.992Z","repository":{"id":314067479,"uuid":"1053761252","full_name":"stackql/stackql-provider-linode","owner":"stackql","description":"generate stackql provider for Linode from openapi specs","archived":false,"fork":false,"pushed_at":"2025-09-10T08:49:23.000Z","size":2002,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-10T12:10:53.498Z","etag":null,"topics":["linode","stackql","stackql-provider"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/stackql.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-09T22:32:19.000Z","updated_at":"2025-09-10T08:49:29.000Z","dependencies_parsed_at":"2025-09-10T12:21:51.578Z","dependency_job_id":null,"html_url":"https://github.com/stackql/stackql-provider-linode","commit_stats":null,"previous_names":["stackql/stackql-provider-linode"],"tags_count":null,"template":false,"template_full_name":"stackql/stackql-provider-TEMPLATE","purl":"pkg:github/stackql/stackql-provider-linode","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stackql%2Fstackql-provider-linode","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stackql%2Fstackql-provider-linode/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stackql%2Fstackql-provider-linode/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stackql%2Fstackql-provider-linode/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stackql","download_url":"https://codeload.github.com/stackql/stackql-provider-linode/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stackql%2Fstackql-provider-linode/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":281563798,"owners_count":26522704,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-29T02:00:06.901Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["linode","stackql","stackql-provider"],"created_at":"2025-10-29T04:53:40.636Z","updated_at":"2025-10-29T04:53:45.984Z","avatar_url":"https://github.com/stackql.png","language":"JavaScript","readme":"# `linode` provider for [`stackql`](https://github.com/stackql/stackql)\r\n\r\nThis repository is used to generate and document the `linode` provider for StackQL, allowing you to query and manipulate Linode resources using SQL-like syntax. The provider is built using the `@stackql/provider-utils` package, which provides tools for converting OpenAPI specifications into StackQL-compatible provider schemas.\r\n\r\n## Prerequisites\r\n\r\nTo use the Linode provider with StackQL, you'll need:\r\n\r\n1. A Linode account with appropriate API credentials\r\n2. A Linode API token with sufficient permissions for the resources you want to access\r\n3. StackQL CLI installed on your system (see [StackQL](https://github.com/stackql/stackql))\r\n\r\n## 1. Download the Open API Specification\r\n\r\nFirst, download the Linode API OpenAPI specification:\r\n\r\n```bash\r\nrm provider-dev/downloaded/*\r\ncurl -L https://github.com/linode/linode-api-docs/raw/refs/heads/development/openapi.json \\\r\n  -o provider-dev/downloaded/openapi.json\r\n\r\n# pre process the spec to remove the apiVersion path param\r\npython3 provider-dev/scripts/remove_api_version.py\r\n```\r\n\r\n## 2. Split into Service Specs\r\n\r\nNext, split the monolithic OpenAPI specification into service-specific files:\r\n\r\n```bash\r\nrm -rf provider-dev/source/*\r\nnpm run split -- \\\r\n  --provider-name linode \\\r\n  --api-doc provider-dev/downloaded/openapi_api_version_removed.json \\\r\n  --svc-discriminator path \\\r\n  --output-dir provider-dev/source \\\r\n  --overwrite \\\r\n  --svc-name-overrides \"$(cat \u003c\u003cEOF\r\n{\r\n  \"network_transfer\": \"networking\"\r\n}\r\nEOF\r\n)\"    \r\n```\r\n\r\n## 3. Generate Mappings\r\n\r\nGenerate the mapping configuration that connects OpenAPI operations to StackQL resources:\r\n\r\n```bash\r\nnpm run generate-mappings -- \\\r\n  --provider-name linode \\\r\n  --input-dir provider-dev/source \\\r\n  --output-dir provider-dev/config\r\n```\r\n\r\nUpdate the resultant `provider-dev/config/all_services.csv` to add the `stackql_resource_name`, `stackql_method_name`, `stackql_verb` values for each operation.\r\n\r\n## 4. Generate Provider\r\n\r\nThis step transforms the split OpenAPI service specs into a fully-functional StackQL provider by applying the resource and method mappings defined in your CSV file.\r\n\r\n```bash\r\nrm -rf provider-dev/openapi/*\r\nnpm run generate-provider -- \\\r\n  --provider-name linode \\\r\n  --input-dir provider-dev/source \\\r\n  --output-dir provider-dev/openapi/src/linode \\\r\n  --config-path provider-dev/config/all_services.csv \\\r\n  --servers '[{\"url\": \"https://api.linode.com/v4\"}]' \\\r\n  --provider-config '{\"auth\": {\"credentialsenvvar\": \"LINODE_TOKEN\",\"type\": \"bearer\"}}' \\\r\n  --overwrite\r\n```\r\n\r\nMake necessary updates to the output docs:\r\n\r\n```bash\r\npython3 provider-dev/scripts/update_linode_interfaces.py\r\npython3 provider-dev/scripts/update_managed_stats.py\r\n```\r\n\r\n## 5. Test Provider\r\n\r\n### Starting the StackQL Server\r\n\r\nBefore running tests, start a StackQL server with your provider:\r\n\r\n```bash\r\nPROVIDER_REGISTRY_ROOT_DIR=\"$(pwd)/provider-dev/openapi\"\r\nnpm run start-server -- --provider linode --registry $PROVIDER_REGISTRY_ROOT_DIR\r\n```\r\n\r\n### Test Meta Routes\r\n\r\nTest all metadata routes (services, resources, methods) in the provider:\r\n\r\n```bash\r\nnpm run test-meta-routes -- linode --verbose\r\n```\r\n\r\nWhen you're done testing, stop the StackQL server:\r\n\r\n```bash\r\nnpm run stop-server\r\n```\r\n\r\nUse this command to view the server status:\r\n\r\n```bash\r\nnpm run server-status\r\n```\r\n\r\n### Run test queries\r\n\r\nRun some test queries against the provider using the `stackql shell`:\r\n\r\n```bash\r\nPROVIDER_REGISTRY_ROOT_DIR=\"$(pwd)/provider-dev/openapi\"\r\nREG_STR='{\"url\": \"file://'${PROVIDER_REGISTRY_ROOT_DIR}'\", \"localDocRoot\": \"'${PROVIDER_REGISTRY_ROOT_DIR}'\", \"verifyConfig\": {\"nopVerify\": true}}'\r\n./stackql shell --registry=\"${REG_STR}\"\r\n```\r\n\r\nExample queries to try:\r\n\r\n```sql\r\n-- Get account information\r\nSELECT \r\ncompany,\r\ncountry,\r\nbalance,\r\nbalance_uninvoiced,\r\nactive_since\r\nFROM linode.account.account;\r\n\r\n--- List Database Engines\r\nSELECT\r\nid,\r\nengine,\r\nversion\r\nFROM linode.databases.engines;\r\n\r\n-- Show Region Availability\r\nSELECT\r\navailable,\r\nplan,\r\nregion\r\nFROM linode.regions.availability;\r\n\r\n-- List all Linode instances\r\nSELECT\r\nid,\r\ncreated,\r\ndisk_encryption,\r\ngroup,\r\nhas_user_data,\r\nhypervisor,\r\nipv4,\r\nipv6,\r\nlabel,\r\nregion,\r\nstatus,\r\ntags,\r\ntype,\r\nupdated,\r\nwatchdog_enabled\r\nFROM linode.linode.instances;\r\n```\r\n\r\n## 6. Publish the provider\r\n\r\nTo publish the provider push the `linode` dir to `providers/src` in a feature branch of the [`stackql-provider-registry`](https://github.com/stackql/stackql-provider-registry). Follow the [registry release flow](https://github.com/stackql/stackql-provider-registry/blob/dev/docs/build-and-deployment.md).  \r\n\r\nLaunch the StackQL shell:\r\n\r\n```bash\r\nexport DEV_REG=\"{ \\\"url\\\": \\\"https://registry-dev.stackql.app/providers\\\" }\"\r\n./stackql --registry=\"${DEV_REG}\" shell\r\n```\r\n\r\npull the latest dev `linode` provider:\r\n\r\n```sql\r\nregistry pull linode;\r\n```\r\n\r\nRun some test queries to verify the provider works as expected.\r\n\r\n## 7. Generate web docs\r\n\r\nProvider doc microsites are built using Docusaurus and published using GitHub Pages.  \r\n\r\na. Update `headerContent1.txt` and `headerContent2.txt` accordingly in `provider-dev/docgen/provider-data/`  \r\n\r\nb. Update the following in `website/docusaurus.config.js`:  \r\n\r\n```js\r\n// Provider configuration - change these for different providers\r\nconst providerName = \"linode\";\r\nconst providerTitle = \"Linode Provider\";\r\n```\r\n\r\nc. Then generate docs using...\r\n\r\n```bash\r\nnpm run generate-docs -- \\\r\n  --provider-name linode \\\r\n  --provider-dir ./provider-dev/openapi/src/linode/v00.00.00000 \\\r\n  --output-dir ./website \\\r\n  --provider-data-dir ./provider-dev/docgen/provider-data\r\n```  \r\n\r\n## 8. Test web docs locally\r\n\r\n```bash\r\ncd website\r\n# test build\r\nyarn build\r\n\r\n# run local dev server\r\nyarn start\r\n```\r\n\r\n## 9. Publish web docs to GitHub Pages\r\n\r\nUnder __Pages__ in the repository, in the __Build and deployment__ section select __GitHub Actions__ as the __Source__. In Netlify DNS create the following records:\r\n\r\n| Source Domain | Record Type  | Target |\r\n|---------------|--------------|--------|\r\n| linode-provider.stackql.io | CNAME | stackql.github.io. |\r\n\r\n## License\r\n\r\nMIT\r\n\r\n## Contributing\r\n\r\nContributions are welcome! Please feel free to submit a Pull Request.","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstackql%2Fstackql-provider-linode","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstackql%2Fstackql-provider-linode","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstackql%2Fstackql-provider-linode/lists"}