How oracle/sql-developer-vscode works
This repository is not the SQL Developer application itself; it is a support repo for the Oracle SQL Developer Extension for VS Code. Its main purpose is to publish the extension API as an NPM package and provide example extensions that show how to use it.
1. Core product boundary
The repo centers on the VS Code extension ecosystem. The public-facing contract is the Oracle SQL Developer extension API, while the actual database tooling lives in the separate Marketplace extension and Oracle documentation site.
2. Primary package: extension-api
This is the main deliverable in the repo. It is an NPM package that exposes TypeScript declaration files (dist/index.d.ts) for the extension API. That means it defines the shape of the API without shipping a full runtime implementation in this repo.
3. API consumption model
Downstream VS Code extensions or sample projects import these type definitions to build against the SQL Developer extension APIs in a type-safe way. The package acts as a compatibility layer and reference contract for extension authors.
4. Samples subsystem
The samples/ directory contains standalone VS Code extensions that demonstrate how to use the API. Architecturally, these are example consumers of extension-api, not part of the package itself. They help validate usage patterns and serve as reference integrations.
5. Build/publish flow
The presence of .github/workflows/npm-publish.yml indicates an automated release path for publishing the extension-api package to NPM. The repo therefore has a lightweight CI/CD concern focused on packaging and distribution rather than running an application backend.
6. Repository layout and responsibilities
• extension-api/: published package, type declarations, package metadata, changelog, and release/security docs
• samples/: example VS Code extensions
• root docs: repository-level guidance, contribution, security, and licensing
This separation keeps the API contract isolated from examples and release automation.
7. Runtime and technology surface
The relevant runtime here is the VS Code extension host, not a standalone server. The key technology is TypeScript type declarations packaged for NPM. The repo’s architecture is therefore client-side/extension-side, with no database, API server, or persistent service in this codebase.
8. External integration boundary
The API ultimately targets Oracle Database workflows through the Oracle SQL Developer VS Code extension. The documentation link in the README points to Oracle-hosted product docs, which are the authoritative source for behavior and supported features.
9. Governance and release metadata
CHANGELOG.md, LICENSE.txt, SECURITY.md, and CONTRIBUTING.md indicate this repo is managed as a distributable developer-facing package with formal release, legal, and vulnerability-disclosure processes.
10. Implication for an architecture diagram
A good diagram would show:
• Oracle SQL Developer VS Code extension as the consumer of Oracle database features
• extension-api as the published TypeScript contract/package
• samples as reference consumer extensions
• NPM/GitHub Actions as the distribution path for the API package
• Oracle documentation/support as the external knowledge source
There is no separate backend service in this repository’s architecture.
Main entry points: package.json extension-api · README.md Repo docs · .gitkeep Example usage · npm-publish.yml Publish flow
Components 15
Repository
Files and packages maintained in this support repo
- Repo docs · Root repository guidance and policies
README.md - Governance · Contribution, security, and license documents
- Publish flow · Automated npm publishing pipeline
.github/workflows/npm-publish.yml - extension-api · Published package that exposes the public extension contract
extension-api/package.json - API types · Distributed type definitions for the extension API
extension-api/dist/index.d.ts - API docs · Package-level documentation and release notes
extension-api/README.md - Changelog · Version history for the published API package
extension-api/CHANGELOG.md - API security · Security guidance for the extension-api package
extension-api/SECURITY.md - Samples · Standalone example VS Code extensions using the API
- Example usage · Representative consumer showing how to use the API
samples/.gitkeep
External
Consumers and services outside this repository
- VS Code host · Extension host runtime where downstream consumers execute
- Consumer extension · Third-party extension built against the published API
- SQL Developer · Oracle SQL Developer extension for VS Code that consumes Oracle database features
- npm · Distribution target for the published extension-api package
- Oracle docs · External documentation and support source for the product and API behavior
Connections 18
- Repo docs → extension-api: describes · Repository root points to the package as the main deliverable
- Repo docs → Samples: contains · Repository root includes example consumer extensions
- Repo docs → Oracle docs: references · Root documentation links to Oracle-hosted product guidance
- Governance → extension-api: governs · Repository policies apply to the published package
- Publish flow → extension-api: publishes · GitHub Actions workflow releases the package to npm
- extension-api → API types: exports · Package ships TypeScript declaration files
- API docs → extension-api: documents · Package README explains the contract and usage
- Changelog → extension-api: tracks · Version history for the API package
- API security → extension-api: secures · Package-specific vulnerability disclosure guidance
- Samples → Example usage: contains · Samples directory holds example extensions
- Example usage → extension-api: consumes · Example extensions build against the published API contract
- Consumer extension → extension-api: consumes · Downstream extensions import the API types
- extension-api → npm: publishes to · Package distribution target is the npm registry
- Consumer extension → VS Code host: runs in · Downstream extensions execute in the VS Code extension host
- SQL Developer → VS Code host: runs in · Oracle extension executes inside the VS Code extension host
- SQL Developer → Oracle docs: supported by · Oracle-hosted documentation is the authoritative behavior source
- Example usage → VS Code host: runs in · Samples are standalone VS Code extensions
- Publish flow → npm: delivers · Automated release path ends at npm