{"id":32565827,"url":"https://github.com/stackql/stackql-provider-digitalocean","last_synced_at":"2025-10-29T04:53:37.629Z","repository":{"id":313427694,"uuid":"1050934287","full_name":"stackql/stackql-provider-digitalocean","owner":"stackql","description":"generate stackql provider for DigitalOcean from openapi specs","archived":false,"fork":false,"pushed_at":"2025-09-06T00:07:44.000Z","size":1303,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-06T01:18:53.325Z","etag":null,"topics":["digitalocean","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-05T07:12:49.000Z","updated_at":"2025-09-06T00:07:48.000Z","dependencies_parsed_at":"2025-09-06T01:28:59.052Z","dependency_job_id":null,"html_url":"https://github.com/stackql/stackql-provider-digitalocean","commit_stats":null,"previous_names":["stackql/stackql-provider-digitalocean"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/stackql/stackql-provider-digitalocean","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stackql%2Fstackql-provider-digitalocean","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stackql%2Fstackql-provider-digitalocean/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stackql%2Fstackql-provider-digitalocean/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stackql%2Fstackql-provider-digitalocean/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stackql","download_url":"https://codeload.github.com/stackql/stackql-provider-digitalocean/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stackql%2Fstackql-provider-digitalocean/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":["digitalocean","stackql","stackql-provider"],"created_at":"2025-10-29T04:53:36.730Z","updated_at":"2025-10-29T04:53:37.615Z","avatar_url":"https://github.com/stackql.png","language":"JavaScript","readme":"## `digitalocean` provider for [`stackql`](https://github.com/stackql/stackql)\r\n\r\nThis repository is used to generate and document the `digitalocean` provider for StackQL, allowing you to query and manipulate DigitalOcean 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\nThe `@stackql/provider-utils` package offers several utilities that this provider uses:\r\n- `split` - Divides a large OpenAPI spec into smaller service-specific files\r\n- `analyze` - Examines OpenAPI specs and generates mapping configuration files\r\n- `generate` - Creates StackQL provider extensions from OpenAPI specs and mappings\r\n- `docgen` - Builds documentation for the provider\r\n\r\n### Prerequisites\r\n\r\nTo use the DigitalOcean provider with StackQL, you'll need:\r\n\r\n1. A DigitalOcean account with appropriate API credentials\r\n2. A DigitalOcean personal access 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 DigitalOcean API OpenAPI specification:\r\n\r\n```bash\r\ncurl -L https://api-engineering.nyc3.digitaloceanspaces.com/spec-ci/DigitalOcean-public.v2.yaml \\\r\n  -o provider-dev/downloaded/digitalocean-public.v2.yaml\r\n```\r\n\r\nThis downloads the official DigitalOcean API specification, which defines all available API endpoints, request parameters, and response schemas.\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\nnpm run split -- \\\r\n  --provider-name digitalocean \\\r\n  --api-doc provider-dev/downloaded/digitalocean-public.v2.yaml \\\r\n  --svc-discriminator tag \\\r\n  --output-dir provider-dev/source \\\r\n  --overwrite \\\r\n  --svc-name-overrides \"$(cat \u003c\u003cEOF\r\n{\r\n  \"1_click_applications\": \"oneclick\",\r\n  \"actions\": \"account\",\r\n  \"gradientai_platform\": \"genai\",\r\n  \"byoip_prefixes\": \"network\",\r\n  \"partner_network_connect\": \"network\",\r\n  \"project_resources\": \"projects\",\r\n  \"vpc_peerings\": \"vpcs\",\r\n  \"spaces_keys\": \"spaces\",\r\n  \"uptime\": \"monitoring\",\r\n  \"droplets\": \"compute\",\r\n  \"droplet_actions\": \"compute\",\r\n  \"droplet_autoscale_pools\": \"compute\",\r\n  \"cdn_endpoints\": \"compute\",\r\n  \"certificates\": \"compute\",\r\n  \"domains\": \"compute\",\r\n  \"domain_records\": \"compute\",\r\n  \"firewalls\": \"compute\",\r\n  \"images\": \"compute\",\r\n  \"image_actions\": \"compute\",                  \r\n  \"load_balancers\": \"compute\",\r\n  \"regions\": \"compute\",\r\n  \"reserved_ips\": \"compute\",\r\n  \"reserved_ip_actions\": \"compute\",\r\n  \"[public_preview]_reserved_ipv6\": \"compute\",\r\n  \"[public_preview]_reserved_ipv6_actions\": \"compute\",\r\n  \"sizes\": \"compute\",\r\n  \"ssh_keys\": \"compute\",  \r\n  \"tags\": \"compute\",  \r\n  \"block_storage\": \"compute\", \r\n  \"block_storage_actions\": \"compute\", \r\n  \"[public_preview]_vpc_nat_gateways\": \"compute\",   \r\n  \"snapshots\": \"compute\",\r\n  \"functions\": \"serverless\",\r\n  \"floating_ips\": \"network\",\r\n  \"floating_ip_actions\": \"network\",      \r\n  \"container_registries\": \"container_registry\",\r\n  \"container_registry\": \"container_registry\"\r\n}\r\nEOF\r\n)\"\r\n```\r\n\r\nThis step breaks down the large DigitalOcean API specification into smaller, more manageable service files. The `--svc-discriminator tag` option tells the tool to use the OpenAPI tags to determine which API endpoints belong to which service. For DigitalOcean, this creates separate files for different functional areas like droplets, volumes, load balancers, etc.\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 digitalocean \\\r\n  --input-dir provider-dev/source \\\r\n  --output-dir provider-dev/config\r\n```\r\n\r\nThis step analyzes the service specs and creates a CSV mapping file that defines how OpenAPI operations translate to StackQL resources, methods, and SQL verbs. The mapping process handles two scenarios:\r\n\r\n1. **New Provider Development**: If no mapping file exists yet, this creates a new `all_services.csv` file with all operations from the OpenAPI spec. You'll need to edit this file to assign appropriate resource names, method names, and SQL verbs.\r\n\r\n2. **Updating Existing Mappings**: If a mapping file already exists, the tool will:\r\n   - Load the existing mappings\r\n   - Identify new operations that aren't yet mapped\r\n   - Flag operations with incomplete mappings (missing resource, method, or SQL verb)\r\n   - Skip operations that are already fully mapped\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\nnpm run generate-provider -- \\\r\n  --provider-name digitalocean \\\r\n  --input-dir provider-dev/source \\\r\n  --output-dir provider-dev/openapi/src/digitalocean \\\r\n  --config-path provider-dev/config/all_services.csv \\\r\n  --servers '[{\"url\": \"https://api.digitalocean.com\"}]' \\\r\n  --provider-config '{\"auth\": {\"credentialsenvvar\": \"DIGITALOCEAN_TOKEN\",\"type\": \"bearer\"}}' \\\r\n  --overwrite\r\n```\r\n\r\nMake necessary updates to the output docs:\r\n\r\n```bash\r\nnode provider-dev/scripts/flatten_allOf.cjs\r\nsh provider-dev/scripts/fix_broken_links.sh\r\n```\r\n\r\nThe `--servers` parameter defines the base URL for API requests. For DigitalOcean, this sets the API endpoint to the v2 API.\r\n\r\nThe `--provider-config` parameter sets up the authentication method. For DigitalOcean, this configures a bearer token authentication scheme that:\r\n- Looks for the API token in the `DIGITALOCEAN_TOKEN` environment variable\r\n- Uses the token as a bearer token in the Authorization header\r\n\r\nThe generated provider will be structured according to the StackQL conventions, with properly organized resources and methods that map to the underlying API operations.\r\n\r\nAfter running this command, you'll have a complete provider structure in the `provider-dev/openapi/src` directory, ready for testing or packaging.\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 digitalocean --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 -- digitalocean --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-- List all droplets\r\nSELECT\r\nid,\r\nname,\r\nstatus,\r\nsize_slug,\r\nJSON_EXTRACT(size, '$.vcpus') as vcpus,\r\nJSON_EXTRACT(size, '$.memory') as memory,\r\nJSON_EXTRACT(size, '$.disk') as disk_size_gb,\r\nJSON_EXTRACT(size, '$.price_hourly') as price_hourly,\r\nJSON_EXTRACT(size, '$.price_monthly') as price_monthly\r\nFROM digitalocean.compute.droplets;\r\n\r\n-- List all Kubernetes clusters\r\nSELECT \r\n  id,\r\n  name,\r\n  cluster_subnet,\r\n  region,\r\n  JSON_EXTRACT(status, '$.state') as state\r\nFROM \r\n  digitalocean.kubernetes.clusters;\r\n```\r\n\r\n### 6. Publish the provider\r\n\r\nTo publish the provider push the `digitalocean` 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 `digitalocean` provider:\r\n\r\n```sql\r\nregistry pull digitalocean;\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\n```bash\r\nnpm run generate-docs -- \\\r\n  --provider-name digitalocean \\\r\n  --provider-dir ./provider-dev/openapi/src/digitalocean/v00.00.00000 \\\r\n  --output-dir ./website \\\r\n  --provider-data-dir ./provider-dev/docgen/provider-data\r\n```  \r\n\r\nMake sure to create the provider data directory with appropriate header files:\r\n\r\n```bash\r\nmkdir -p ./provider-dev/docgen/provider-data\r\n```\r\n\r\nCreate `headerContent1.txt`:\r\n```\r\n---\r\ntitle: digitalocean\r\nhide_title: false\r\nhide_table_of_contents: false\r\nkeywords:\r\n  - digitalocean\r\n  - stackql\r\n  - infrastructure-as-code\r\n  - configuration-as-data\r\ndescription: Query and manage DigitalOcean resources using SQL\r\n---\r\n\r\n# DigitalOcean Provider\r\n\r\nThe DigitalOcean provider for StackQL allows you to query, deploy, and manage DigitalOcean resources using SQL. This provider supports droplets, volumes, Kubernetes clusters, load balancers, and more.\r\n```\r\n\r\nCreate `headerContent2.txt`:\r\n```\r\n## Authentication\r\n\r\nDigitalOcean requires a personal access token for authentication. You can create one in the DigitalOcean control panel under API \u003e Tokens/Keys.\r\n\r\nSet your token as an environment variable:\r\n\r\n```bash\r\nexport DIGITALOCEAN_TOKEN=\"your_token_here\"\r\n```\r\n\r\nFor more information, see the [DigitalOcean API documentation](https://docs.digitalocean.com/reference/api/).\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| digitalocean-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 to the DigitalOcean provider 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-digitalocean","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstackql%2Fstackql-provider-digitalocean","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstackql%2Fstackql-provider-digitalocean/lists"}