Skip to content

Commit d771287

Browse files
ez-pluginsez-plugins
committed
docs(queries): update create.md with ColumnType usage guide and type reference
- Replace minimal example with full ColumnType-based table definition - Add ColumnType section: fixed-type constant table, parameterised factory method table, modifier chain table, and custom-type examples - Expand IF NOT EXISTS and composite-PK examples to use ColumnType - Update method reference table to include column(String, ColumnType)
1 parent cffe8df commit d771287

1 file changed

Lines changed: 107 additions & 12 deletions

File tree

‎docs/queries/create.md‎

Lines changed: 107 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -20,20 +20,108 @@ description: "Building CREATE TABLE statements with CreateBuilder"
2020
## Overview
2121

2222
`CreateBuilder` builds `CREATE TABLE` statements with optional `IF NOT EXISTS`
23-
guards and composite primary keys:
23+
guards and composite primary keys. Column types can be specified as raw SQL
24+
strings or as type-safe `ColumnType` constants and factory methods.
2425

2526
```java
27+
import com.github.ezframework.javaquerybuilder.query.builder.ColumnType;
2628
import com.github.ezframework.javaquerybuilder.query.builder.QueryBuilder;
2729
import com.github.ezframework.javaquerybuilder.query.sql.SqlResult;
2830

2931
SqlResult result = QueryBuilder.createTable("users")
30-
.column("id", "INT")
31-
.column("name", "VARCHAR(64)")
32-
.column("email", "VARCHAR(255)")
32+
.column("id", ColumnType.INT.notNull().autoIncrement())
33+
.column("username", ColumnType.varChar(64).notNull().unique())
34+
.column("balance", ColumnType.decimal(10, 2))
35+
.column("created_at", ColumnType.TIMESTAMP)
3336
.primaryKey("id")
3437
.build();
3538

36-
// → CREATE TABLE users (id INT, name VARCHAR(64), email VARCHAR(255), PRIMARY KEY (id))
39+
// → CREATE TABLE users (
40+
// id INT NOT NULL AUTO_INCREMENT,
41+
// username VARCHAR(64) NOT NULL UNIQUE,
42+
// balance DECIMAL(10, 2),
43+
// created_at TIMESTAMP,
44+
// PRIMARY KEY (id))
45+
```
46+
47+
---
48+
49+
## ColumnType — type-safe column definitions
50+
51+
`ColumnType` provides pre-defined constants for all common SQL types, factory
52+
methods for parameterised types, and chainable modifier methods for column-level
53+
constraints.
54+
55+
### Fixed-width types
56+
57+
| Constant | SQL | Notes |
58+
|----------|-----|-------|
59+
| `ColumnType.TINYINT` | `TINYINT` | 1-byte integer; MySQL / MariaDB |
60+
| `ColumnType.SMALLINT` | `SMALLINT` | 2-byte integer |
61+
| `ColumnType.INT` | `INT` | 4-byte integer |
62+
| `ColumnType.INTEGER` | `INTEGER` | Alias for `INT` in most databases |
63+
| `ColumnType.BIGINT` | `BIGINT` | 8-byte integer |
64+
| `ColumnType.FLOAT` | `FLOAT` | Single-precision float |
65+
| `ColumnType.DOUBLE` | `DOUBLE` | Double-precision float |
66+
| `ColumnType.REAL` | `REAL` | Standard SQL alias for `DOUBLE` |
67+
| `ColumnType.BOOLEAN` | `BOOLEAN` | Boolean value |
68+
| `ColumnType.TEXT` | `TEXT` | Unbounded text |
69+
| `ColumnType.TINYTEXT` | `TINYTEXT` | Up to 255 chars; MySQL / MariaDB |
70+
| `ColumnType.MEDIUMTEXT` | `MEDIUMTEXT` | Up to 16 MB; MySQL / MariaDB |
71+
| `ColumnType.LONGTEXT` | `LONGTEXT` | Up to 4 GB; MySQL / MariaDB |
72+
| `ColumnType.CLOB` | `CLOB` | Character large object (standard SQL) |
73+
| `ColumnType.BLOB` | `BLOB` | Binary large object |
74+
| `ColumnType.TINYBLOB` | `TINYBLOB` | Up to 255 bytes; MySQL / MariaDB |
75+
| `ColumnType.MEDIUMBLOB` | `MEDIUMBLOB` | Up to 16 MB; MySQL / MariaDB |
76+
| `ColumnType.LONGBLOB` | `LONGBLOB` | Up to 4 GB; MySQL / MariaDB |
77+
| `ColumnType.DATE` | `DATE` | Calendar date |
78+
| `ColumnType.TIME` | `TIME` | Time-of-day |
79+
| `ColumnType.DATETIME` | `DATETIME` | Date + time; MySQL / MariaDB / SQLite |
80+
| `ColumnType.TIMESTAMP` | `TIMESTAMP` | Date + time; often auto-updated |
81+
| `ColumnType.JSON` | `JSON` | JSON document; MySQL 5.7+, PG 9.2+, SQLite 3.38+ |
82+
| `ColumnType.SERIAL` | `SERIAL` | Auto-increment 4-byte int (PostgreSQL) |
83+
| `ColumnType.BIGSERIAL` | `BIGSERIAL` | Auto-increment 8-byte int (PostgreSQL) |
84+
| `ColumnType.UUID` | `UUID` | UUID; native on PostgreSQL |
85+
86+
### Parameterised factory methods
87+
88+
| Method | SQL output | Description |
89+
|--------|-----------|-------------|
90+
| `ColumnType.varChar(n)` | `VARCHAR(n)` | Variable-length string up to `n` chars |
91+
| `ColumnType.charType(n)` | `CHAR(n)` | Fixed-length string of `n` chars |
92+
| `ColumnType.decimal(p, s)` | `DECIMAL(p, s)` | Exact decimal with `p` total and `s` fraction digits |
93+
| `ColumnType.numeric(p, s)` | `NUMERIC(p, s)` | Exact numeric; equivalent to `DECIMAL` in most databases |
94+
| `ColumnType.binary(n)` | `BINARY(n)` | Fixed-length binary of `n` bytes |
95+
| `ColumnType.varBinary(n)` | `VARBINARY(n)` | Variable-length binary up to `n` bytes |
96+
| `ColumnType.timestamp(p)` | `TIMESTAMP(p)` | Timestamp with `p` fractional-seconds digits (0–6) |
97+
98+
### Modifier methods (chainable)
99+
100+
Modifiers return a new `ColumnType` instance and can be chained in any order:
101+
102+
| Method | Appends | Example |
103+
|--------|---------|---------|
104+
| `.notNull()` | `NOT NULL` | `ColumnType.INT.notNull()` → `INT NOT NULL` |
105+
| `.unique()` | `UNIQUE` | `ColumnType.varChar(64).unique()` → `VARCHAR(64) UNIQUE` |
106+
| `.autoIncrement()` | `AUTO_INCREMENT` | `ColumnType.INT.notNull().autoIncrement()` → `INT NOT NULL AUTO_INCREMENT` |
107+
| `.defaultValue(val)` | `DEFAULT val` | `ColumnType.BOOLEAN.defaultValue("false")` → `BOOLEAN DEFAULT false` |
108+
109+
{: .warning }
110+
> `.defaultValue(val)` inserts the string verbatim into the SQL. Use only
111+
> static, known-safe values (e.g. `"0"`, `"false"`, `"CURRENT_TIMESTAMP"`).
112+
> Never pass user-supplied input.
113+
114+
### Custom types
115+
116+
For database-specific types not covered by the built-in constants, pass a raw
117+
SQL string directly to `column()` or use the public `ColumnType` constructor:
118+
119+
```java
120+
// Raw SQL string (backward compatible)
121+
.column("geom", "GEOMETRY NOT NULL")
122+
123+
// Public constructor for custom type
124+
.column("geom", new ColumnType("GEOMETRY NOT NULL"))
37125
```
38126

39127
---
@@ -43,13 +131,17 @@ SqlResult result = QueryBuilder.createTable("users")
43131
```java
44132
SqlResult result = QueryBuilder.createTable("sessions")
45133
.ifNotExists()
46-
.column("token", "VARCHAR(128)")
47-
.column("user_id", "INT")
48-
.column("expires_at", "TIMESTAMP")
134+
.column("token", ColumnType.varChar(128).notNull())
135+
.column("user_id", ColumnType.INT)
136+
.column("expires_at", ColumnType.TIMESTAMP)
49137
.primaryKey("token")
50138
.build();
51139

52-
// → CREATE TABLE IF NOT EXISTS sessions (token VARCHAR(128), user_id INT, expires_at TIMESTAMP, PRIMARY KEY (token))
140+
// → CREATE TABLE IF NOT EXISTS sessions (
141+
// token VARCHAR(128) NOT NULL,
142+
// user_id INT,
143+
// expires_at TIMESTAMP,
144+
// PRIMARY KEY (token))
53145
```
54146

55147
---
@@ -58,8 +150,8 @@ SqlResult result = QueryBuilder.createTable("sessions")
58150

59151
```java
60152
SqlResult result = QueryBuilder.createTable("user_roles")
61-
.column("user_id", "INT")
62-
.column("role_id", "INT")
153+
.column("user_id", ColumnType.INT)
154+
.column("role_id", ColumnType.INT)
63155
.primaryKey("user_id")
64156
.primaryKey("role_id")
65157
.build();
@@ -74,8 +166,11 @@ SqlResult result = QueryBuilder.createTable("user_roles")
74166
| Method | Returns | Description |
75167
|--------|---------|-------------|
76168
| `table(String name)` | `CreateBuilder` | Set table name |
77-
| `column(String name, String sqlType)` | `CreateBuilder` | Add a column definition |
169+
| `column(String name, String sqlType)` | `CreateBuilder` | Add a column with a raw SQL type string |
170+
| `column(String name, ColumnType type)` | `CreateBuilder` | Add a column with a type-safe `ColumnType` |
78171
| `primaryKey(String name)` | `CreateBuilder` | Declare a primary key column |
79172
| `ifNotExists()` | `CreateBuilder` | Add `IF NOT EXISTS` guard |
80173
| `build()` | `SqlResult` | Render; throws `IllegalStateException` if table or columns are missing |
81174
| `build(SqlDialect dialect)` | `SqlResult` | Render with specified dialect |
175+
176+
| `build(SqlDialect dialect)` | `SqlResult` | Render with specified dialect |

0 commit comments

Comments
 (0)