Update constraints and foreign keys docs (#3583)

Resolves #3043, #3360, #3361, #3429 

Co-authored-by: Andrey Aksenov <[email protected]>

Author: p7nov

doc/code_snippets/test/constraints/constraint_test.lua

@@ -0,0 +1,66 @@
+local fio = require('fio')
+local server = require('luatest.server')
+local t = require('luatest')
+local g = t.group()
+g.before_each(function(cg)
+    cg.server = server:new {
+        box_cfg = {},
+        workdir = fio.cwd() .. '/tmp'
+    }
+    cg.server:start()
+end)
+
+g.after_each(function(cg)
+    cg.server:stop()
+    cg.server:drop()
+end)
+
+g.test_constraints = function(cg)
+    cg.server:exec(function()
+
+        -- Define a tuple constraint function --
+        box.schema.func.create('check_person', {
+            language = 'LUA',
+            is_deterministic = true,
+            body = 'function(t, c) return (t.age >= 0 and #(t.name) > 3) end'
+        })
+
+        -- Create a space with a tuple constraint --
+        customers = box.schema.space.create('customers', {constraint = 'check_person'})
+
+        -- Define a field constraint function --
+        box.schema.func.create('check_age', {
+            language = 'LUA',
+            is_deterministic = true,
+            body = 'function(f, c) return (f >= 0 and f < 150) end'
+        })
+
+        -- Specify format with a field constraint --
+        box.space.customers:format({
+            {name = 'id', type = 'number'},
+            {name = 'name', type = 'string'},
+            {name = 'age',  type = 'number', constraint = 'check_age'},
+        })
+
+        box.space.customers:create_index('primary', { parts = { 1 } })
+
+        box.space.customers:insert{1, "Alice", 30}
+
+        -- Tests --
+        t.assert_equals(customers:count(), 1)
+        t.assert_equals(customers:get(1), {1, "Alice", 30})
+
+        -- Failed contstraint --
+        t.assert_error_msg_contains("Check constraint 'check_person' failed for tuple",
+                function() customers:insert{2, "Bob", 230} end)
+
+        -- Create one more tuple constraint --
+        box.schema.func.create('another_constraint',
+            {language = 'LUA', is_deterministic = true, body = 'function(t, c) return true end'})
+
+        -- Set two constraints with optional names --
+        box.space.customers:alter{
+            constraint = { check1 = 'check_person', check2 = 'another_constraint'}
+        }
+    end)
+end

doc/code_snippets/test/foreign_keys/field_foreign_key_test.lua

@@ -0,0 +1,56 @@
+local fio = require('fio')
+local server = require('luatest.server')
+local t = require('luatest')
+local g = t.group()
+g.before_each(function(cg)
+    cg.server = server:new {
+        box_cfg = {},
+        workdir = fio.cwd() .. '/tmp'
+    }
+    cg.server:start()
+end)
+
+g.after_each(function(cg)
+    cg.server:stop()
+    cg.server:drop()
+end)
+
+g.test_foreign_keys = function(cg)
+    cg.server:exec(function()
+
+        -- Parent space --
+        customers = box.schema.space.create('customers')
+        customers:format{
+            {name = 'id', type = 'number'},
+            {name = 'name', type = 'string'}
+        }
+
+        customers:create_index('primary', { parts = { 1 } })
+        customers:create_index('name', { parts = { 2 } })
+        customers:create_index('id_name', { parts = { 1, 2 } })
+
+        customers:insert({1, 'Alice'})
+
+        -- Create a space with a field foreign key --
+        box.schema.space.create('orders')
+
+        box.space.orders:format({
+            {name = 'id',   type = 'number'},
+            {name = 'customer_id', foreign_key = {space = 'customers', field = 'id'}},
+            {name = 'price_total', type = 'number'},
+        })
+
+        orders = box.space.orders
+        orders:create_index('primary', { parts = { 1 } })
+
+        orders:insert({1, 1, 100})
+
+        t.assert_equals(orders:count(), 1)
+        t.assert_equals(orders:get(1), {1, 1, 100})
+
+        -- Failed foreign key check --
+        t.assert_error_msg_contains("Foreign key constraint 'customers' failed for field '2 (customer_id)': foreign tuple was not found",
+                function() orders:insert{2, 10, 200} end)
+
+    end)
+end

doc/code_snippets/test/foreign_keys/tuple_foreign_key_test.lua

@@ -0,0 +1,98 @@
+local fio = require('fio')
+local server = require('luatest.server')
+local t = require('luatest')
+local g = t.group()
+g.before_each(function(cg)
+    cg.server = server:new {
+        box_cfg = {},
+        workdir = fio.cwd() .. '/tmp'
+    }
+    cg.server:start()
+end)
+
+g.after_each(function(cg)
+    cg.server:stop()
+    cg.server:drop()
+end)
+
+g.test_foreign_keys = function(cg)
+    cg.server:exec(function()
+
+        -- Parent space --
+        customers = box.schema.space.create('customers')
+        customers:format{
+            {name = 'id', type = 'number'},
+            {name = 'name', type = 'string'}
+        }
+
+        customers:create_index('primary', { parts = { 1 } })
+        customers:create_index('name', { parts = { 2 } })
+        customers:create_index('id_name', { parts = { 1, 2 } })
+
+        customers:insert({1, 'Alice'})
+
+        -- Create a space with a tuple foreign key --
+        box.schema.space.create("orders", {
+            foreign_key = {
+                space = 'customers',
+                field = {customer_id = 'id', customer_name = 'name'}
+            }
+        })
+
+        box.space.orders:format({
+            {name = "id", type = "number"},
+            {name = "customer_id" },
+            {name = "customer_name"},
+            {name = "price_total", type = "number"},
+        })
+
+        orders = box.space.orders
+        orders:create_index('primary', { parts = { 1 } })
+
+        orders:insert({1, 1, 'Alice', 100})
+
+        t.assert_equals(orders:count(), 1)
+        t.assert_equals(orders:get(1), {1, 1, 'Alice', 100})
+
+        -- Failed foreign key check --
+        t.assert_error_msg_contains("Foreign key constraint 'customers' failed: foreign tuple was not found",
+                function() orders:insert{2, 10, 'Bob', 200} end)
+
+        -- Set a foreign key with an optional name --
+        box.space.orders:alter{
+            foreign_key = {
+                customer = {
+                    space = 'customers',
+                    field = { customer_id = 'id', customer_name = 'name'}
+                }
+            }
+        }
+
+        items = box.schema.space.create('items')
+        items:format{{name = 'id', type = 'number'}}
+        items:create_index('primary', { parts = { 1 } })
+
+        orders:delete{1}
+        orders:format({
+            {name = "id", type = "number"},
+            {name = "customer_id" },
+            {name = "customer_name"},
+            {name = "item_id", type = "number"},
+            {name = "price_total", type = "number"},
+        })
+
+        -- Set two foreign keys: names are mandatory --
+        box.space.orders:alter{
+            foreign_key = {
+                customer = {
+                    space = 'customers',
+                    field = {customer_id = 'id', customer_name = 'name'}
+                },
+                item = {
+                    space = 'items',
+                    field = {item_id = 'id'}
+                }
+            }
+        }
+    end)
+end