Support sample table data in DBML

dbml-homepage/docs/docs.md

@@ -35,6 +35,10 @@ outlines the full syntax documentations of DBML.
     - [TableGroup Notes](#tablegroup-notes-1)
     - [TableGroup Settings](#tablegroup-settings)
 - [TablePartial](#tablepartial)
+- [Data Sample](#data-sample)
+  - [Explicit Column List](#explicit-column-list)
+  - [Implicit Column List](#implicit-column-list)
+  - [Data Types](#data-types)
 - [Multi-line String](#multi-line-string)
 - [Comments](#comments)
 - [Syntax Consistency](#syntax-consistency)
@@ -658,6 +662,224 @@ When multiple partials define the same field, setting or index, DBML resolves co
 1. Local Table Definition: Fields, settings and indexes defined directly in the table override those from partials.
 2. Last Injected Partial: If a conflict exists between partials, the definition from the last-injected partial (in source order) takes precedence.
 
+## Data Sample
+
+`Records` allow you to define sample data for your tables directly in DBML. This is useful for documentation, testing, and providing example data for your database schema.
+
+Records can be defined either outside or inside a table definition.
+
+```text
+// Outside table definition
+Table users {
+  id int [pk]
+  name varchar
+  email varchar
+}
+
+records users(id, name, email) {
+  1, 'Alice', 'alice@example.com'
+  2, 'Bob', 'bob@example.com'
+}
+
+// Inside table definition
+Table posts {
+  id int [pk]
+  title varchar
+  published boolean
+
+  records (id, title, published) {
+    1, 'First Post', true
+    2, 'Second Post', false
+  }
+}
+```
+
+:::note
+Each table can have only one records block. You cannot define duplicate records block for the same table.
+:::
+
+### Explicit Column List
+
+You can specify which columns to populate by listing them in parentheses. This works for both inside and outside table records.
+
+```text
+Table users {
+  id int [pk]
+  name varchar
+  email varchar
+  created_at timestamp
+}
+
+// Only populate id and name, other columns will use default values or NULL
+records users(id, name) {
+  1, 'Alice'
+  2, 'Bob'
+  3, 'Charlie'
+}
+```
+
+### Implicit Column List
+
+When the column list is omitted, records will automatically use all table columns in their definition order. **Implicit column lists are only supported for records defined inside a table.**
+
+```text
+Table users {
+  id int [pk]
+  name varchar
+  active boolean
+
+  // Implicitly uses all columns in order: id, name, active
+  records {
+    1, 'Alice', true
+    2, 'Bob', false
+  }
+}
+```
+
+:::tip
+When using implicit columns with tables that inject partials using `~partial_name`, the column order follows the same precedence rules as [TablePartial](#tablepartial) injection.
+:::
+
+**Column Order with Table Partials**
+
+When a table injects partials, the final column order for implicit records is determined by:
+
+1. Fields from injected partials appear in their injection order
+2. Local table fields appear in their definition order
+3. Later partial injections override earlier ones for duplicate fields
+
+Example,
+
+```text
+TablePartial base_template {
+  id int [pk]
+  created_at timestamp
+}
+
+TablePartial metadata {
+  updated_at timestamp
+}
+
+Table users {
+  ~base_template  // id, created_at injected first
+  name varchar    // local field
+  email varchar   // local field
+  ~metadata       // updated_at injected last
+
+  // Implicit column order: id, created_at, name, email, updated_at
+  records {
+    1, '2024-01-15 10:00:00', 'Alice', 'alice@example.com', '2024-01-15 10:00:00'
+    2, '2024-01-16 11:00:00', 'Bob', 'bob@example.com', '2024-01-16 11:00:00'
+  }
+}
+```
+
+### Data Types
+
+Records use CSV-style syntax. Each value is interpreted and type-checked according to the target column's SQL type.
+
+**Strings**
+
+Wrapped in single quotes. Escape single quotes using `\'`.
+
+```text
+'Hello World'
+'Escape\'s sequence'
+```
+
+**Numbers**
+
+Integer or decimal values with or without quotes.
+
+```text
+42
+3.14
+-100
+1.5e10
+```
+
+**Booleans**
+
+Use `true` or `false` literals, or various boolean-like representations:
+
+```text
+true, false           // Boolean literals (case-insensitive)
+'Y', 'N'             // Yes/No (case-insensitive)
+'T', 'F'             // True/False (case-insensitive)
+'TRUE', 'FALSE'      // String forms (case-insensitive)
+1, 0                 // Numeric forms
+'1', '0'
+```
+
+**Null Values**
+
+Multiple ways to represent NULL:
+
+```text
+null                 // Explicit NULL literal
+''                   // Empty string (for non-string types)
+                     // Empty field between commas
+```
+
+Example,
+
+```text
+Table users {
+  id int
+  name varchar
+  age int
+}
+
+records users(id, name, age) {
+  1, 'Alice', null    // explicit NULL
+  2, 'Bob', ''        // empty string treated as NULL
+  3, , 25             // empty field treated as NULL
+}
+```
+
+**Timestamps/Dates**
+
+Wrapped in single quotes. Supports ISO 8601 and other sensible formats.
+
+```text
+'2024-01-15 10:30:00'
+'2024-01-15T10:30:00.000+07:00'
+'2024-01-15'
+'10:30:00'
+```
+
+**Enum Values**
+
+Reference enum members using the enum constant or string literal:
+
+```text
+enum Status {
+  active
+  inactive
+  pending
+}
+
+Table orders {
+  id int
+  status Status
+}
+
+records orders(id, status) {
+  1, Status.active    // Using enum constant
+  2, 'inactive'       // Using string literal
+}
+```
+
+**Expressions**
+
+Wrapped in backticks for database functions and expressions. When using expressions, static type checking is disabled for that value.
+
+```text
+`now()`
+`uuid_generate_v4()`
+`1 + 2 * 3`
+```
+
 ## Multi-line String
 
 Multiline string will be defined between triple single quote `'''`

packages/dbml-core/__tests__/examples/exporter/exporter.spec.ts

@@ -11,7 +11,8 @@ describe('@dbml/core - exporter', () => {
     const output = readFileSync(path.resolve(__dirname, `./${testDir}/output/${fileName}.out.${fileExtension}`), { encoding: 'utf8' });
     const res = exporter.export(input, format);
 
-    expect(res).toBe(output);
+    // Exclude meaningless spaces from failing the tests
+    expect(res.trim()).toBe(output.trim());
   };
 
   test.each(scanTestNames(__dirname, 'mysql_exporter/input'))('mysql_exporter/%s', (name) => {

packages/dbml-core/__tests__/examples/exporter/mssql_exporter/input/insert_records.in.dbml

@@ -0,0 +1,27 @@
+Table users {
+  id integer [pk]
+  name varchar
+  email varchar
+  active boolean
+  created_at timestamp
+}
+
+Table posts {
+  id integer [pk]
+  user_id integer
+  title varchar
+  content text
+}
+
+Ref: users.id < posts.user_id
+
+Records users(id, name, email, active, created_at) {
+  1, "Alice", "alice@example.com", true, "2024-01-15 10:30:00+07:00"
+  2, "Bob", "bob@example.com", false, "2024-01-16 14:20:00+07:00"
+  3, "Charlie", null, true, "2024-01-17 09:15:00+07:00"
+}
+
+Records posts(id, user_id, title, content) {
+  1, 1, "First Post", "Hello World"
+  2, 1, "Second Post", "It's a beautiful day"
+}

packages/dbml-core/__tests__/examples/exporter/mssql_exporter/output/insert_records.out.sql

@@ -0,0 +1,39 @@
+CREATE TABLE [users] (
+  [id] integer PRIMARY KEY,
+  [name] nvarchar(255),
+  [email] nvarchar(255),
+  [active] boolean,
+  [created_at] timestamp
+)
+GO
+
+CREATE TABLE [posts] (
+  [id] integer PRIMARY KEY,
+  [user_id] integer,
+  [title] nvarchar(255),
+  [content] text
+)
+GO
+
+ALTER TABLE [posts] ADD FOREIGN KEY ([user_id]) REFERENCES [users] ([id])
+GO
+
+-- Disable constraint checks for INSERT
+EXEC sp_MSforeachtable "ALTER TABLE ? NOCHECK CONSTRAINT all";
+GO
+
+INSERT INTO [users] ([id], [name], [email], [active], [created_at])
+VALUES
+  (1, 'Alice', 'alice@example.com', 1, '2024-01-15 10:30:00+07:00'),
+  (2, 'Bob', 'bob@example.com', 1, '2024-01-16 14:20:00+07:00'),
+  (3, 'Charlie', NULL, 1, '2024-01-17 09:15:00+07:00');
+GO
+INSERT INTO [posts] ([id], [user_id], [title], [content])
+VALUES
+  (1, 1, 'First Post', 'Hello World'),
+  (2, 1, 'Second Post', 'It''s a beautiful day');
+GO
+
+-- Re-enable constraint checks
+EXEC sp_MSforeachtable "ALTER TABLE ? WITH CHECK CHECK CONSTRAINT all";
+GO

packages/dbml-core/__tests__/examples/exporter/mysql_exporter/input/insert_records.in.dbml

@@ -0,0 +1,27 @@
+Table users {
+  id integer [pk]
+  name varchar
+  email varchar
+  active boolean
+  created_at timestamp
+}
+
+Table posts {
+  id integer [pk]
+  user_id integer
+  title varchar
+  content text
+}
+
+Ref: users.id < posts.user_id
+
+Records users(id, name, email, active, created_at) {
+  1, "Alice", "alice@example.com", true, "2024-01-15 10:30:00+07:00"
+  2, "Bob", "bob@example.com", false, "2024-01-16 14:20:00+07:00"
+  3, "Charlie", null, true, "2024-01-17 09:15:00+07:00"
+}
+
+Records posts(id, user_id, title, content) {
+  1, 1, "First Post", "Hello World"
+  2, 1, "Second Post", "It's a beautiful day"
+}

packages/dbml-core/__tests__/examples/exporter/mysql_exporter/input/sample_data_edge_cases.in.dbml

@@ -0,0 +1,20 @@
+Table edge_cases {
+  id integer [pk]
+  scientific_notation_pos float
+  scientific_notation_neg float
+  signed_positive integer
+  signed_negative integer
+  sql_function_default varchar
+  dbml_expr_default integer
+  datetime_value timestamp
+  string_with_newline text
+  string_with_backslash varchar
+  string_with_escape_seq varchar
+  string_with_quotes varchar
+  null_value varchar
+}
+
+Records edge_cases(id, scientific_notation_pos, scientific_notation_neg, signed_positive, signed_negative, sql_function_default, dbml_expr_default, datetime_value, string_with_newline, string_with_backslash, string_with_escape_seq, string_with_quotes, null_value) {
+  1, 1.23e5, -4.56e-3, +42, -100, `NOW()`, `1 + 2 * 3`, "2024-01-15 10:30:00.123456+07:00", "Line 1\nLine 2\nLine 3", "C:\\Users\\path\\file.txt", "Tab:\tNewline:\nCarriage return:\r", "She said \"Hello\" and 'Hi'", null
+  2, 9.99e10, -1.11e-10, +0, -0, `CURRENT_TIMESTAMP`, `LENGTH('test')`, "2023-12-31 23:59:59+07:00", "First line\n\nThird line", "Escaped backslash: \\\\", "Quote: \" Apostrophe: ' Backslash: \\", "O'Reilly's \"book\"", null
+}

packages/dbml-core/__tests__/examples/exporter/mysql_exporter/output/insert_records.out.sql

@@ -0,0 +1,32 @@
+CREATE TABLE `users` (
+  `id` integer PRIMARY KEY,
+  `name` varchar(255),
+  `email` varchar(255),
+  `active` boolean,
+  `created_at` timestamp
+);
+
+CREATE TABLE `posts` (
+  `id` integer PRIMARY KEY,
+  `user_id` integer,
+  `title` varchar(255),
+  `content` text
+);
+
+ALTER TABLE `posts` ADD FOREIGN KEY (`user_id`) REFERENCES `users` (`id`);
+
+-- Disable foreign key checks for INSERT
+SET FOREIGN_KEY_CHECKS = 0;
+
+INSERT INTO `users` (`id`, `name`, `email`, `active`, `created_at`)
+VALUES
+  (1, 'Alice', 'alice@example.com', TRUE, '2024-01-15 10:30:00+07:00'),
+  (2, 'Bob', 'bob@example.com', FALSE, '2024-01-16 14:20:00+07:00'),
+  (3, 'Charlie', NULL, TRUE, '2024-01-17 09:15:00+07:00');
+INSERT INTO `posts` (`id`, `user_id`, `title`, `content`)
+VALUES
+  (1, 1, 'First Post', 'Hello World'),
+  (2, 1, 'Second Post', 'It''s a beautiful day');
+
+-- Re-enable foreign key checks
+SET FOREIGN_KEY_CHECKS = 1;