How dark-athena/plsqlrewrite4gaussdb-web works
1. Repository shape
- This is a three-layer product: a standalone PL/SQL conversion engine, a Spring Boot web backend, and a Vue 3 frontend.
- The root Maven setup and scripts suggest the same converter is reused both for CLI/batch use and for the web UI.
2. Core conversion engine (src/)
- The heart of the repo is com.plsqlrewriter.core.PlSqlRewriter.
- It uses ANTLR4-generated PL/SQL parsing (src/main/resources/antlr4, parser base classes in src/main/java/com/plsqlrewriter/parser/antlr) to read Oracle PL/SQL and rewrite it for GaussDB.
- Supporting utilities include batch processing, custom parse error handling, and tree viewing/debugging.
3. Rule/config-driven transformation layer
- Conversion behavior is heavily driven by external files in config/.
- These include datatype, token, exception, identifier, function, query-block, and regex-based mappings.
- The architecture is intentionally configurable: the parser produces structure, then rule files determine how nodes and tokens are rewritten.
4. CLI and offline conversion boundary
- The root scripts (convert.sh, batch_convert.sh, build_core_offline.sh, etc.) show the core can run without the web stack.
- That makes the converter a reusable library/CLI tool for single-file and directory batch conversion.
5. Web backend (webapp/)
- The backend is a separate Spring Boot 3 application exposing REST endpoints.
- Controllers are split by domain: auth, users, groups, projects, parameter templates, and SQL rewrite.
- SpaForwardController indicates the backend also serves the frontend SPA entrypoint.
6. Backend service and persistence model
- Business logic lives in service/, with repositories in repository/ and domain entities in model/.
- The main persisted concepts are User, UserGroup, Project, and ParamTemplate.
- This is the management layer for organizing conversion jobs and reusable conversion settings.
7. Security and bootstrap flow
- Authentication is handled by Spring Security via MySecurityConfig and UserDetailsServiceImpl.
- DataInitializer seeds initial data, including the default admin account referenced in the README.
- So the web app has a clear login-first boundary before project and conversion operations.
8. File/package handling for project conversion
- The backend includes TarUtil and ZipUtil, which indicates projects can ingest compressed input sets.
- Project-level conversion likely flows from uploaded archive/files → unpacking → rewrite engine → stored results for comparison or download.
9. Frontend SPA (frontend/)
- The UI is a Vue 3 + Vite single-page app.
- It talks to the backend through API modules in src/api/ and uses route-based views for login, project list/create, group/user management, and SQL rewrite.
- The frontend is a client-only layer; the backend serves data and handles all rewrite operations.
10. Tests, samples, and release/deployment
- Core rewrite correctness is validated under src/test/resources/sql_tests with input/expected/output fixtures and comparison scripts.
- Web controllers also have dedicated tests in webapp/src/test.
- Release artifacts are packaged via Maven, Docker, and GitHub Actions workflows, so deployment is supported both as a containerized web app and as offline conversion bundles.
Main entry points: WebappApplication.java Spring Boot app · PlSqlRewriter.java PL/SQL Rewriter · request.js API client · ProjectController.java Project API
Components 24
Core Engine
Standalone PL/SQL rewrite engine, parser, and rule-driven transformation layer.
- PL/SQL Rewriter · Main conversion engine that rewrites Oracle PL/SQL toward GaussDB.
src/main/java/com/plsqlrewriter/core/PlSqlRewriter.java - ANTLR parser · Generated lexer/parser base classes and grammar-backed parsing support.
src/main/resources/antlr4/PlSqlParser.g4 - Rule configs · External mappings and patterns that drive token, datatype, function, and query rewrites.
config/config.properties - Batch tools · Directory/file batch processing for offline conversion runs.
src/main/java/com/plsqlrewriter/util/BatchProcessor.java - Error handling · Custom parse error listener for recovery and diagnostics.
src/main/java/com/plsqlrewriter/util/CustomErrorListener.java - Tree viewer · Parse-tree inspection and debugging support for conversion development.
src/main/java/com/plsqlrewriter/util/PlSqlTreeViewer.java
Web Backend
Spring Boot API, security, persistence, and project orchestration.
- Spring Boot app · Backend application that exposes rewrite and management APIs.
webapp/src/main/java/com/plsqlrewriter/webapp/WebappApplication.java - Security · Spring Security configuration and user-details integration.
webapp/src/main/java/com/plsqlrewriter/webapp/security/MySecurityConfig.java - Auth API · Login and authentication endpoints.
webapp/src/main/java/com/plsqlrewriter/webapp/controller/AuthController.java - Project API · Project lifecycle and conversion job endpoints.
webapp/src/main/java/com/plsqlrewriter/webapp/controller/ProjectController.java - SQL rewrite API · Direct SQL rewrite endpoint backed by the shared engine.
webapp/src/main/java/com/plsqlrewriter/webapp/controller/SqlRewriteController.java - User API · User management endpoints.
webapp/src/main/java/com/plsqlrewriter/webapp/controller/UserController.java - Group API · User-group management endpoints.
webapp/src/main/java/com/plsqlrewriter/webapp/controller/UserGroupController.java - Template API · Parameter template management endpoints.
webapp/src/main/java/com/plsqlrewriter/webapp/controller/ParamTemplateController.java - Domain model · Persisted users, groups, projects, and parameter templates.
webapp/src/main/java/com/plsqlrewriter/webapp/model/Project.java - Repositories · Spring Data repositories for backend entities.
webapp/src/main/java/com/plsqlrewriter/webapp/repository/ProjectRepository.java - Services · Backend service layer coordinating persistence and conversion flows.
webapp/src/main/java/com/plsqlrewriter/webapp/service/ProjectService.java - Archive utils · Tar and zip extraction for project input sets.
webapp/src/main/java/com/plsqlrewriter/webapp/util/ZipUtil.java - Data init · Seeds default application data, including initial admin setup.
webapp/src/main/java/com/plsqlrewriter/webapp/DataInitializer.java
Frontend
Vue 3 single-page application that consumes backend APIs.
- Vue SPA · Vue 3 + Vite single-page frontend.
frontend/src/main.js - API client · Browser-side request modules for auth, users, groups, projects, and SQL rewrite.
frontend/src/api/request.js - Route views · Login, project, user, group, and rewrite screens.
frontend/src/views/Login.vue
Other components
- Maven build · Top-level Maven packaging for the shared engine and web app.
pom.xml - CLI scripts · Shell/batch entrypoints for standalone conversion and server startup.
convert.sh
Connections 27
- Maven build → PL/SQL Rewriter: builds · Root build packages the shared conversion engine.
- Maven build → Spring Boot app: builds · Root build also packages the web application.
- CLI scripts → PL/SQL Rewriter: runs · Offline scripts invoke the standalone converter.
- CLI scripts → Batch tools: batch · Batch scripts drive directory-scale conversions.
- PL/SQL Rewriter → ANTLR parser: parses via · The rewrite engine consumes ANTLR grammar output.
- PL/SQL Rewriter → Rule configs: applies · Transformation behavior is driven by external mapping files.
- PL/SQL Rewriter → Error handling: reports · Parsing and rewrite failures go through custom listeners.
- PL/SQL Rewriter → Tree viewer: inspects · Tree viewer supports debugging and analysis of parse trees.
- Batch tools → PL/SQL Rewriter: orchestrates · Batch processing coordinates repeated rewrite runs.
- Spring Boot app → Security: protects · Backend application is guarded by Spring Security.
- Spring Boot app → Auth API: hosts · Application exposes authentication endpoints.
- Spring Boot app → Project API: hosts · Application exposes project and conversion endpoints.
- Spring Boot app → SQL rewrite API: hosts · Application exposes direct rewrite endpoints.
- Spring Boot app → User API: hosts · Application exposes user-management endpoints.
- Spring Boot app → Group API: hosts · Application exposes group-management endpoints.
- Spring Boot app → Template API: hosts · Application exposes template-management endpoints.
- Project API → Services: delegates · Controllers delegate business logic to services.
- SQL rewrite API → PL/SQL Rewriter: uses · SQL rewrite API reuses the shared conversion engine.
- Services → Repositories: persists via · Service layer talks to repositories for domain state.
- Repositories → Domain model: stores · Repositories map the persisted entities.
- Project API → Archive utils: ingests · Project flows can unpack tar/zip inputs before rewrite.
- Data init → Domain model: seeds · Bootstrap data populates core entities and defaults.
- Vue SPA → API client: calls · Frontend screens use browser API modules.
- API client → Auth API: requests · Client sends authentication requests to backend.
- API client → Project API: requests · Client manages project operations through the API.
- API client → SQL rewrite API: requests · Client submits rewrite jobs through the API.
- Route views → Vue SPA: rendered in · Views compose the main SPA routes and screens.