{"id":14070272,"url":"https://github.com/duartealexf/sql-ddl-to-json-schema","last_synced_at":"2025-12-30T00:04:22.858Z","repository":{"id":37579995,"uuid":"118932214","full_name":"duartealexf/sql-ddl-to-json-schema","owner":"duartealexf","description":"SQL DDL to JSON Schema Converter","archived":false,"fork":false,"pushed_at":"2024-03-14T13:40:33.000Z","size":3335,"stargazers_count":203,"open_issues_count":0,"forks_count":39,"subscribers_count":9,"default_branch":"master","last_synced_at":"2024-04-24T02:23:14.118Z","etag":null,"topics":["grammar","json-schema","nearley","sql-parser"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/duartealexf.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-01-25T15:40:33.000Z","updated_at":"2024-06-16T22:47:13.096Z","dependencies_parsed_at":"2024-06-16T22:46:59.944Z","dependency_job_id":"91041d0b-d550-4dde-a89a-463d15542bbc","html_url":"https://github.com/duartealexf/sql-ddl-to-json-schema","commit_stats":null,"previous_names":[],"tags_count":31,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/duartealexf%2Fsql-ddl-to-json-schema","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/duartealexf%2Fsql-ddl-to-json-schema/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/duartealexf%2Fsql-ddl-to-json-schema/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/duartealexf%2Fsql-ddl-to-json-schema/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/duartealexf","download_url":"https://codeload.github.com/duartealexf/sql-ddl-to-json-schema/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228102667,"owners_count":17869899,"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","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":["grammar","json-schema","nearley","sql-parser"],"created_at":"2024-08-13T07:07:37.136Z","updated_at":"2025-12-30T00:04:22.846Z","avatar_url":"https://github.com/duartealexf.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"# SQL DDL to JSON Schema converter\n\n[![Tests](https://github.com/duartealexf/sql-ddl-to-json-schema/actions/workflows/run-tests.yaml/badge.svg)](https://github.com/duartealexf/sql-ddl-to-json-schema/actions/workflows/run-tests.yaml)\n[![npm](https://img.shields.io/npm/v/sql-ddl-to-json-schema.svg)](https://img.shields.io/npm/v/sql-ddl-to-json-schema.svg)\n[![node](https://img.shields.io/node/v/sql-ddl-to-json-schema.svg)](https://img.shields.io/node/v/sql-ddl-to-json-schema.svg)\n[![license](https://img.shields.io/npm/l/sql-ddl-to-json-schema.svg)](https://img.shields.io/npm/l/sql-ddl-to-json-schema.svg)\n\nTransforms SQL DDL statements into JSON format (JSON Schema and a compact format).\n\n- [SQL DDL to JSON Schema converter](#sql-ddl-to-json-schema-converter)\n  - [Overview](#overview)\n  - [Installation](#installation)\n  - [Usage](#usage)\n    - [Shorthand](#shorthand)\n    - [Step by step](#step-by-step)\n  - [Options for JSON Schema output](#options-for-json-schema-output)\n    - [`useRef`](#useref)\n  - [Version compatibility table](#version-compatibility-table)\n  - [What it is, what it is not](#what-it-is-what-it-is-not)\n  - [About](#about)\n  - [Contributing](#contributing)\n    - [Commiting](#commiting)\n    - [Understanding the internals](#understanding-the-internals)\n    - [Scripts at hand](#scripts-at-hand)\n      - [Visual Studio Code](#visual-studio-code)\n  - [Links](#links)\n\n## Overview\n\nTaking the following SQL:\n\n```sql\nCREATE TABLE users (\n  id INT(11) NOT NULL AUTO_INCREMENT,\n  nickname VARCHAR(255) NOT NULL,\n  deleted_at TIMESTAMP NULL,\n  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP NOT NULL,\n  updated_at TIMESTAMP,\n  PRIMARY KEY (id)\n) ENGINE MyISAM COMMENT 'All system users';\n\nALTER TABLE users ADD UNIQUE KEY unq_nick (nickname);\n```\n\nIt parses and delivers an **array of JSON Schema documents** (one for each parsed table):\n\n```json\n[\n  {\n    \"$schema\": \"http://json-schema.org/draft-07/schema\",\n    \"$comment\": \"JSON Schema for users table\",\n    \"$id\": \"users\",\n    \"title\": \"users\",\n    \"description\": \"All system users\",\n    \"type\": \"object\",\n    \"required\": [\n      \"id\",\n      \"nickname\",\n      \"created_at\"\n    ],\n    \"definitions\": {\n      \"id\": {\n        \"$comment\": \"primary key\",\n        \"type\": \"integer\",\n        \"minimum\": 1,\n        \"maximum\": 2147483647\n      },\n      \"nickname\": {\n        \"type\": \"string\",\n        \"maxLength\": 255\n      },\n      \"deleted_at\": {\n        \"type\": \"string\"\n      },\n      \"created_at\": {\n        \"type\": \"string\",\n        \"default\": \"CURRENT_TIMESTAMP\"\n      },\n      \"updated_at\": {\n        \"type\": \"string\"\n      }\n    },\n    \"properties\": {\n      \"id\": {\n        \"$ref\": \"#/definitions/id\"\n      },\n      \"nickname\": {\n        \"$ref\": \"#/definitions/nickname\"\n      },\n      \"deleted_at\": {\n        \"$ref\": \"#/definitions/deleted_at\"\n      },\n      \"created_at\": {\n        \"$ref\": \"#/definitions/created_at\"\n      },\n      \"updated_at\": {\n        \"$ref\": \"#/definitions/updated_at\"\n      }\n    }\n  }\n]\n```\n\nAnd an array of tables in a compact JSON format:\n\n```json\n[\n  {\n    \"name\": \"users\",\n    \"columns\": [\n      {\n        \"name\": \"id\",\n        \"type\": {\n          \"datatype\": \"int\",\n          \"displayWidth\": 11\n        },\n        \"options\": {\n          \"nullable\": false,\n          \"autoincrement\": true\n        }\n      },\n      {\n        \"name\": \"nickname\",\n        \"type\": {\n          \"datatype\": \"varchar\",\n          \"length\": 255\n        },\n        \"options\": {\n          \"nullable\": false\n        }\n      },\n      {\n        \"name\": \"deleted_at\",\n        \"type\": {\n          \"datatype\": \"timestamp\",\n          \"fractional\": 0\n        },\n        \"options\": {\n          \"nullable\": true\n        }\n      },\n      {\n        \"name\": \"created_at\",\n        \"type\": {\n          \"datatype\": \"timestamp\",\n          \"fractional\": 0\n        },\n        \"options\": {\n          \"nullable\": false,\n          \"default\": \"CURRENT_TIMESTAMP\"\n        }\n      },\n      {\n        \"name\": \"updated_at\",\n        \"type\": {\n          \"datatype\": \"timestamp\",\n          \"fractional\": 0\n        },\n        \"options\": {\n          \"nullable\": true\n        }\n      }\n    ],\n    \"primaryKey\": {\n      \"columns\": [\n        {\n          \"column\": \"id\"\n        }\n      ]\n    },\n    \"uniqueKeys\": [\n      {\n        \"columns\": [\n          {\n            \"column\": \"nickname\",\n            \"length\": 255\n          }\n        ]\n      }\n    ],\n    \"options\": {\n      \"comment\": \"All system users\",\n      \"engine\": \"MyISAM\"\n    }\n  }\n]\n```\n\n_Currently only DDL statements of MySQL and MariaDB dialects are supported._ - [Check out the roadmap](https://github.com/duartealexf/sql-ddl-to-json-schema/blob/master/ROADMAP.md)\n\n## Installation\n\n```sh\nyarn add sql-ddl-to-json-schema\nnpm i sql-ddl-to-json-schema\n```\n\n## Usage\n\n### Shorthand\n\n```ts\nconst { Parser } = require('sql-ddl-to-json-schema');\n// or:\nimport { Parser } from 'sql-ddl-to-json-schema';\n\nconst parser = new Parser('mysql');\n\nconst sql = `\nCREATE TABLE users (\n  id INT(11) NOT NULL AUTO_INCREMENT,\n  nickname VARCHAR(255) NOT NULL,\n  deleted_at TIMESTAMP NULL,\n  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP NOT NULL,\n  updated_at TIMESTAMP,\n  PRIMARY KEY (id)\n) ENGINE MyISAM COMMENT 'All system users';\n\nALTER TABLE users ADD UNIQUE KEY unq_nick (nickname);\n`;\n\n/**\n * Read on for available options.\n */\nconst options = {};\n\n/**\n * Explore the compact JSON format...\n */\nconst compactJsonTablesArray = parser.feed(sql).toCompactJson(parser.results);\n\n/**\n * Or get the JSON Schema if you need to modify it...\n */\nconst jsonSchemaDocuments = parser.feed(sql).toJsonSchemaArray(options, compactJsonTablesArray);\n```\n\n### Step by step\n\n```ts\n/**\n * Read on for available options.\n */\nconst options = { useRef: true };\n\n/**\n * Feed the parser with the SQL DDL statements...\n */\nparser.feed(sql);\n\n/**\n * You can get the parsed results in JSON format...\n */\nconst parsedJsonFormat = parser.results;\n\n/**\n * And pass it to be formatted in a compact JSON format...\n */\nconst compactJsonTablesArray = parser.toCompactJson(parsedJsonFormat);\n\n/**\n * Finally pass it to format to an array of JSON Schema items. One for each table...\n */\nconst jsonSchemaDocuments = parser.toJsonSchemaArray(options, compactJsonTablesArray);\n```\n\n## Options for JSON Schema output\n\nThere are a few options when it comes to formatting the JSON Schema output:\n\n### `useRef`\n\nWhether to add all properties to `definitions` and in `properties` only use \\$ref.\n\nDefault value: `true`.\n\n## Version compatibility table\n\n| This lib version range | NodeJS version range | Angular support | Other browser-based JS support |\n| ---------------------- | -------------------- | --------------- | ------------------------------ |\n| \u003c= 3.x                 | \u003e= 6.x               | No              | Yes                            |\n| \u003e= 4                   | \u003e= 8.6               | Yes             | Yes                            |\n\n## What it is, what it is not\n\n**It is** a SQL DDL parser for Javascript, based on [nearley](https://nearley.js.org). It will parse DDL statements only, converting it to JSON. No DML is supported.\n\n**It is not** a SQL DBMS, nor a SQL Server, nor SQL client.\n\n## About\n\n**No SQL server, client or DBMS is required.**\n\nTo see which DDL statements / SQL dialects are supported, [check out the roadmap](https://github.com/duartealexf/sql-ddl-to-json-schema/blob/master/ROADMAP.md).\n\nThis project is a grammar and stream-friendly SQL parser based on [nearley](https://nearley.js.org).\n\n## Contributing\n\nYou are welcome to contribute!\n\nPreferably use `npm`, as all scripts in `package.json` are run through npm.\n\n- Clone this repo\n- Install dependencies: `npm i`\n\n### Commiting\n\nPrefer using the latest version of NodeJS.\n\nTo commit, use commitizen: `git cz` (you will need to have installed devDependencies: `npm i`).\n\n### Understanding the internals\n\nFolder structure:\n\n```md\n|- lib/ Compiled library folder, product of this project.\n|\n|- src/\n| |- typings/ Types used throughout project.\n| |- shared/ Shared files used by dialects, parsers and formatters.\n| |- mysql/\n| |- formatter/ Formats the parsed JSON (output of parser) to other format.\n| |- compact/ Formatter for compact JSON format.\n| |- json-schema/ Formatter for JSON Schema format.\n| |- language/\n| |- dictionary/ TS files with array of keywords and symbols used in lexer.ne.\n| |- rules/ Nearley files with grammar rules.\n| |- lexer.ne Entrypoint and first lines of the grammar.\n|\n|- tasks/\n| |- mysql/\n| |- assembly.ts Script that concatenates all .ne files to grammar.ne to lib folder.\n| |- formatters.ts Script that sends a copy of formatters to lib folder.\n|\n|- test/ Tests.\n```\n\n- There are naming rules for tokens in ne files, as stated in `lexer.ne`. They are prepended with:\n\n```txt\n\nK_ -\u003e Keywords\nP_ -\u003e Phrase (aka statements)\nO_ -\u003e Options (one of several keywords or phrases)\nS_ -\u003e Symbol (not a keyword, but chars and other matches by RegExp's)\n\n```\n\n1. The `dictionary/keywords.ts` file contains keywords, but they are prepended with K\\_ when used in .ne files. Take a look to make sure you understand how it is exported.\n\n2. The compiled `grammar.ne` file comprises an assembly (concatenation) of `lexer.ne` and files in `language` folder. So don't worry about importing .ne files in other .ne files. This prevents circular dependency and grammar rules in `lexer.ne` are scoped to all files (thus not having to repeat them in every file).\n\n### Scripts at hand\n\nValid to all SQL dialects:\n\n- Assemble `grammar.ne` and compile to `grammar.ts`: `npm run build`\n- Same as above, but watch for changes: `npm run build:watch`\n- Run tests: `npm run test`\n- Test and watch for changes: `npm run test:watch`\n\n#### Visual Studio Code\n\nDebug launch config is versioned in this repository.\n\n## Links\n\n- [Grammar List](http://www.antlr3.org/grammar/list.html)\n- [moo](https://github.com/no-context/moo)\n- [nearley](https://github.com/kach/nearley)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fduartealexf%2Fsql-ddl-to-json-schema","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fduartealexf%2Fsql-ddl-to-json-schema","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fduartealexf%2Fsql-ddl-to-json-schema/lists"}