{"id":20564392,"url":"https://github.com/tarantool/ddl","last_synced_at":"2025-08-11T18:08:47.359Z","repository":{"id":37430889,"uuid":"213449445","full_name":"tarantool/ddl","owner":"tarantool","description":"The DDL module enables you to describe data schema in a declarative YAML-based format.","archived":false,"fork":false,"pushed_at":"2025-04-08T09:22:02.000Z","size":219,"stargazers_count":12,"open_issues_count":21,"forks_count":5,"subscribers_count":25,"default_branch":"master","last_synced_at":"2025-04-14T15:13:00.949Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tarantool.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":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2019-10-07T17:49:32.000Z","updated_at":"2025-04-08T09:22:05.000Z","dependencies_parsed_at":"2023-01-31T08:30:54.920Z","dependency_job_id":"376f5e57-18a6-4999-92ed-704425800dd8","html_url":"https://github.com/tarantool/ddl","commit_stats":null,"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/tarantool/ddl","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tarantool%2Fddl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tarantool%2Fddl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tarantool%2Fddl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tarantool%2Fddl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tarantool","download_url":"https://codeload.github.com/tarantool/ddl/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tarantool%2Fddl/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269931473,"owners_count":24498722,"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-08-11T02:00:10.019Z","response_time":75,"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":[],"created_at":"2024-11-16T04:26:08.203Z","updated_at":"2025-08-11T18:08:47.332Z","avatar_url":"https://github.com/tarantool.png","language":"Lua","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ca href=\"https://github.com/tarantool/ddl/actions?query=workflow%3ATest\"\u003e\n\u003cimg src=\"https://github.com/tarantool/ddl/workflows/Test/badge.svg\"\u003e\n\u003c/a\u003e\n\u003ca href='https://coveralls.io/github/tarantool/ddl?branch=master'\u003e\n\u003cimg src='https://coveralls.io/repos/github/tarantool/ddl/badge.svg?branch=master' alt='Coverage Status' /\u003e\n\u003c/a\u003e\n\n# DDL\n\nDDL module for Tarantool 1.10+\n\nThe DDL module enables you to describe data schema in a declarative YAML-based format.\nIt is a simpler alternative to describing data schema in Lua and doesn't require having a deep knowledge of Lua.\nDDL is a built-in Cartridge module. See more details about Tarantool's data mode\nin [documementation](https://www.tarantool.io/en/doc/latest/book/box/data_model/#data-schema-description-using-the-ddl-module).\n\n## Contents\n\n- [API](#api)\n  - [Set spaces format](#set-spaces-format)\n  - [Check compatibility](#check-compatibility)\n  - [Get spaces format](#get-spaces-format)\n- [Input data format](#input-data-format)\n- [Building and testing](#building-and-testing)\n\n## API\n\n### Set spaces format\n    `ddl.set_schema(schema)`\n    - If no spaces existed before, create them.\n    - If a space exists, check the space's format and indexes.\n    - If the format/indexes are different from those in the database,\n      return an error.\n    - The module doesn't drop or alter any indexes.\n    - Spaces omitted in the DDL are ignored, the module doesn't check them.\n\n    Return values: `true` if no error, otherwise return `nil, err`\n\nCall of function `ddl.set_schema(schema)` creates a space `_ddl_sharding_key` with two\nfields: `space_name` with type `string` and `sharding_key` with type `array`.\n\nSimilarly for `sharding_func`: call of function `ddl.set_schema(schema)` creates\na space `_ddl_sharding_func` with three fields: `space_name`, `sharding_func_name` and\n`sharding_func_body` with type string.\n\nIf you want to use sharding function from some module, you need to require\nand set to `_G` the module with sharding function first. For example:\nto use sharding functions like\n[vshard.router.bucket_id_strcrc32](https://www.tarantool.io/doc/latest/reference/reference_rock/vshard/vshard_api/#router-api-bucket-id-strcrc32)\nand\n[vshard.router.bucket_id_mpcrc32](https://www.tarantool.io/doc/latest/reference/reference_rock/vshard/vshard_api/#router-api-bucket-id-mpcrc32)\nfrom `vshard` module you need to require `vshard` module.\n\nAlso, you can pass your own sharding function by defining the function name in `_G`\nor by specifying lua code directly in `body` field:\n```lua\nsharding_func = {\n  body = 'function(key) return \u003c...\u003e end'\n}\n```\n\nYour defined sharding function in `_G` should have type `function`\nor `table` | `cdata` | `userdata` with `__call` metamethod.\n\nDefined function must have a prototype according to the following rules:\n\n**Parameters**\n\nkey (number | table | string | boolean) – a sharding key.\n\n**Return value**\n\nbucket identifier (number)\n\n### Check compatibility\n    `ddl.check_schema(schema)`\n    - Check that a `set_schema()` call will raise no error.\n\n    Return values: `true` if no error, otherwise return `nil, err`\n\n### Get spaces format\n    `ddl.get_schema()`\n    - Scan spaces and return the database schema.\n\n    Return values: table with space's schemas (see \"Schema example\")\n\n### Get bucket id\n    `ddl.bucket_id(space_name, sharding_key)`\n    - Calculate bucket id for a specified space and sharding key.\n    Method uses sharding function specified in DDL schema.\n\n    Method is not transactional in the sense that it catches up\n    `_ddl_sharding_func` changes immediatelly: it may see changes that're\n    not committed yet and may see a state from another transaction,\n    which should not be visible in the current transaction.\n\n    Return values: bucket_id if no error, otherwise return `nil, err`\n\n## Input data format\n\n```lua\nformat = {\n    spaces = {\n        [space_name] = {\n            engine = 'vinyl' | 'memtx',\n            is_local = true | false,\n            temporary = true | false,\n            format = {\n                {\n                    name = '...',\n                    is_nullable = true | false,\n                    type = 'unsigned' | 'string' | 'varbinary' |\n                            'integer' | 'number' | 'boolean' |\n                            'array' | 'scalar' | 'any' | 'map' |\n                            'decimal' | 'double' | 'uuid' | 'datetime' |\n                            'interval'\n                },\n                ...\n            },\n            indexes = {\n                -- array of index parameters\n                -- integer keys are used as index.id\n                -- index parameters depend on the index type\n                {\n                    type = 'TREE'|'HASH',\n                    name = '...',\n                    unique = true|false, -- hash index is always unique\n                    parts = {\n                        -- array of part parameters\n                        {\n                            path = field_name.jsonpath,\n                            -- may be multipath if '[*]' is used,\n                            type = 'unsigned' | 'string' | 'varbinary' |\n                                'integer' | 'number' | 'boolean' | 'scalar' |\n                                'decimal' | 'double' | 'uuid' | 'datetime',\n                            is_nullable = true | false,\n                            collation = nil | 'none' |\n                                'unicode' | 'unicode_ci' | '...',\n                            -- collation must be set, if and only if\n                            -- type == 'string'.\n                            -- to see full list of collations\n                            -- just run box.space._collation:select()\n                        }\n                    },\n                    sequence = '...', -- sequence_name\n                    function = '...', -- function_name\n                }, {\n                    type = 'RTREE',\n                    name = '...',\n                    unique = false, -- rtree can't be unique\n                    parts = {\n                        -- array with only one part parameter\n                        {\n                            path = field_name.jsonpath,\n                            type = 'array',\n                            -- rtree index must use array field\n                            is_nullable = true|false,\n                        }\n                    },\n                    dimension = number,\n                    distance = 'euclid'|'manhattan',\n                }, {\n                    type = BITSET,\n                    name = '...',\n                    unique = false, -- bitset index can't be unique\n                    parts = {\n                        -- array with only one part parameter\n                        {\n                            path = field_name.jsonpath,\n                            type = 'unsigned' | 'string',\n                            -- bitset index doesn't support any other\n                            -- field types\n                            is_nullable = true|false,\n                        }\n                    },\n                },\n                ...\n            },\n            sharding_key = nil | {\n                -- array of strings (field_names)\n                --\n                -- sharded space must have:\n                -- field: {name = 'bucket_id', is_nullable = false, type = 'unsigned'}\n                -- index: {\n                --     name = 'bucket_id',\n                --     type = 'TREE',\n                --     unique = false,\n                --     parts = {{path = 'bucket_id', is_nullable = false, type = 'unsigned'}}\n                -- }\n                --\n                -- unsharded spaces must NOT have\n                -- field and index named 'bucket_id'\n            },\n            sharding_func = 'dot.notation' | 'sharding_func_name_defined_in_G'\n                            {body = 'function(key) return \u003c...\u003e end'},\n        },\n        ...\n    },\n    functions = { -- Not implemented yet\n        [function_name] = {\n            body = '...',\n            is_deterministic = true|false,\n            is_sandboxed = true|false,\n            is_multikey = true|false,\n        },\n        ...\n    },\n    sequences = {\n        [sequence_name] = {\n            start = start,\n            min = min,\n            max = max,\n            cycle = cycle,\n            cache = cache,\n            step = step,\n        },\n    },\n}\n```\n\n## Schema example\n\n```lua\nlocal schema = {\n    spaces = {\n        customer = {\n            engine = 'memtx',\n            is_local = false,\n            temporary = false,\n            format = {\n                {name = 'customer_id', is_nullable = false, type = 'unsigned'},\n                {name = 'bucket_id', is_nullable = false, type = 'unsigned'},\n                {name = 'fullname', is_nullable = false, type = 'string'},\n            },\n            indexes = {{\n                name = 'customer_id',\n                type = 'TREE',\n                unique = true,\n                parts = {\n                    {path = 'customer_id', is_nullable = false, type = 'unsigned'}\n                }\n            }, {\n                name = 'bucket_id',\n                type = 'TREE',\n                unique = false,\n                parts = {\n                    {path = 'bucket_id', is_nullable = false, type = 'unsigned'}\n                }\n            }, {\n                name = 'fullname',\n                type = 'TREE',\n                unique = true,\n                parts = {\n                    {path = 'fullname', is_nullable = false, type = 'string'}\n                }\n            }},\n            sharding_key = {'customer_id'},\n        },\n        account = {\n            engine = 'memtx',\n            is_local = false,\n            temporary = false,\n            format = {\n                {name = 'account_id', is_nullable = false, type = 'unsigned'},\n                {name = 'customer_id', is_nullable = false, type = 'unsigned'},\n                {name = 'bucket_id', is_nullable = false, type = 'unsigned'},\n                {name = 'balance', is_nullable = false, type = 'string'},\n                {name = 'name', is_nullable = false, type = 'string'},\n            },\n            indexes = {{\n                name = 'account_id',\n                type = 'TREE',\n                unique = true,\n                parts = {\n                    {path = 'account_id', is_nullable = false, type = 'unsigned'}\n                }\n            }, {\n                name = 'customer_id',\n                type = 'TREE',\n                unique = false,\n                parts = {\n                    {path = 'customer_id', is_nullable = false, type = 'unsigned'}\n                }\n            }, {\n                name = 'bucket_id',\n                type = 'TREE',\n                unique = false,\n                parts = {\n                    {path = 'bucket_id', is_nullable = false, type = 'unsigned'}\n                }\n            }},\n            sharding_key = {'customer_id'},\n            sharding_func = 'vshard.router.bucket_id_mpcrc32',\n        },\n        tickets = {\n            engine = 'memtx',\n            is_local = false,\n            temporary = false,\n            format = {\n                {name = 'ticket_id', is_nullable = false, type = 'unsigned'},\n                {name = 'customer_id', is_nullable = false, type = 'unsigned'},\n                {name = 'bucket_id', is_nullable = false, type = 'unsigned'},\n                {name = 'contents', is_nullable = false, type = 'string'},\n            },\n            indexes = {{\n                name = 'ticket_id',\n                type = 'TREE',\n                unique = true,\n                parts = {\n                    {path = 'ticket_id', is_nullable = false, type = 'unsigned'}\n                },\n                sequence = 'ticket_seq',\n            }, {,\n                name = 'customer_id',\n                type = 'TREE',\n                unique = false,\n                parts = {\n                    {path = 'customer_id', is_nullable = false, type = 'unsigned'}\n                }\n            }, {\n                name = 'bucket_id',\n                type = 'TREE',\n                unique = false,\n                parts = {\n                    {path = 'bucket_id', is_nullable = false, type = 'unsigned'}\n                }\n            }},\n            sharding_key = {'customer_id'},\n            sharding_func = 'vshard.router.bucket_id_mpcrc32',\n        },\n    },\n    sequences = {\n        ticket_seq = {\n            start = 1,\n            min = 1,\n            max = 10000,\n            cycle = false,\n        },\n    },\n}\n```\n\n## Building and testing\n\n```bash\ntt rocks make\n```\n\n```bash\ntt rocks install luatest 0.5.7\ntt rocks install luacheck 0.25.0\ntt rocks install cartridge\nmake test -C build.luarocks ARGS=\"-V\"\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftarantool%2Fddl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftarantool%2Fddl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftarantool%2Fddl/lists"}