Added .is_null(), .is_not_null(), .like(), .not_like() (#14)

2026-05-05 06:31:22 -05:00 · 2025-05-26 21:45:00 +02:00
parent 97cce29ae6
commit 3d8c4ecbf1
14 changed files with 716 additions and 33 deletions
@@ -5,16 +5,19 @@ Welcome to the sqlgen documentation. This guide provides detailed information ab
 ## Core Concepts

 - [Defining Tables](defining_tables.md) - How to define tables using C++ structs
- [sqlgen::Result](result.md) - How sqlgen handles errors and results
- [sqlgen::PrimaryKey](primary_key.md) - How to define primary keys in sqlgen
+- [sqlgen::col](col.md) - How to represent columns in queries
 - [sqlgen::Flatten](flatten.md) - How to "inherit" fields from other structs
+- [sqlgen::PrimaryKey](primary_key.md) - How to define primary keys in sqlgen
+- [sqlgen::Result](result.md) - How sqlgen handles errors and results
 - [sqlgen::to_sql](to_sql.md) - How to transpile C++ operations to dialect-specific SQL

-## Database Operations
+## Database I/O

 - [sqlgen::read](reading.md) - How to read data from a database
 - [sqlgen::write](writing.md) - How to write data to a database

+## Database Operations
+
 - [sqlgen::create_index](create_index.md) - How to create an index on a table
 - [sqlgen::create_table](create_table.md) - How to create a new table
 - [sqlgen::delete_from](delete_from.md) - How to delete data from a table
@@ -23,18 +26,20 @@ Welcome to the sqlgen documentation. This guide provides detailed information ab
 - [sqlgen::insert](insert.md) - How to insert data within transactions
 - [sqlgen::update](update.md) - How to update data in a table

- [Transactions](transactions.md) - How to use transactions for atomic operations
- [Connection Pool](connection_pool.md) - How to manage database connections efficiently
-
 ## Data Types and Validation

+- [sqlgen::Pattern](pattern.md) - How to add regex pattern validation to avoid SQL injection
 - [sqlgen::Timestamp](timestamp.md) - How timestamps work in sqlgen
 - [sqlgen::Varchar](varchar.md) - How varchars work in sqlgen
- [sqlgen::Pattern](pattern.md) - How to add regex pattern validation to avoid SQL injection
+
+## Other concepts
+
+- [Connection Pool](connection_pool.md) - How to manage database connections efficiently
+- [Transactions](transactions.md) - How to use transactions for atomic operations

 ## Supported Databases

- [PostgreSQL](postgres.md) - How to interact with PostgreSQL and compatible databases (Redshift, Aurora, Greenplum)
+- [PostgreSQL](postgres.md) - How to interact with PostgreSQL and compatible databases (Redshift, Aurora, Greenplum, CockroachDB, ...)
 - [SQLite](sqlite.md) - How to interact with SQLite3

 For installation instructions, quick start guide, and usage examples, please refer to the [main README](../README.md). 
@@ -0,0 +1,195 @@
+# `sqlgen::col`
+
+`sqlgen::col` provides a type-safe way to reference and manipulate database columns in SQL queries. It enables building complex SQL conditions, ordering, and updates through a fluent C++ interface.
+
+## Usage
+
+### Basic Definition
+
+Reference a column using the string literal operator:
+
+```cpp
+using namespace sqlgen;
+
+// Using string literal operator
+const auto age_col = "age"_c;
+
+// Using col template function
+const auto name_col = col<"first_name">;
+```
+
+### Column Operations
+
+#### Comparison Operations
+
+Compare columns with values or other columns:
+
+```cpp
+using namespace sqlgen;
+
+// Compare with value
+const auto query1 = read<std::vector<Person>> | where("age"_c > 18);
+
+// Compare with another column
+const auto query2 = read<std::vector<Person>> | 
+                   where("age"_c > "id"_c);
+```
+
+This generates SQL like:
+
+```sql
+-- For query1
+SELECT "id", "first_name", "last_name", "age" 
+FROM "Person" 
+WHERE "age" > 18;
+
+-- For query2
+SELECT "id", "first_name", "last_name", "age" 
+FROM "Person" 
+WHERE "age" > "id";
+```
+
+#### NULL Operations
+
+Check for NULL or NOT NULL values:
+
+```cpp
+using namespace sqlgen;
+
+// Find records where age is NULL
+const auto query1 = read<std::vector<Person>> | 
+                   where("age"_c.is_null());
+
+// Find records where age is NOT NULL
+const auto query2 = read<std::vector<Person>> | 
+                   where("age"_c.is_not_null());
+```
+
+This generates SQL like:
+
+```sql
+-- For query1
+SELECT "id", "first_name", "last_name", "age" 
+FROM "Person" 
+WHERE "age" IS NULL;
+
+-- For query2
+SELECT "id", "first_name", "last_name", "age" 
+FROM "Person" 
+WHERE "age" IS NOT NULL;
+```
+
+#### Pattern Matching
+
+Use LIKE and NOT LIKE for pattern matching:
+
+```cpp
+using namespace sqlgen;
+
+// Find names starting with 'H'
+const auto query1 = read<std::vector<Person>> | 
+                   where("first_name"_c.like("H%"));
+
+// Find names not starting with 'H'
+const auto query2 = read<std::vector<Person>> | 
+                   where("first_name"_c.not_like("H%"));
+```
+
+This generates SQL like:
+
+```sql
+-- For query1
+SELECT "id", "first_name", "last_name", "age" 
+FROM "Person" 
+WHERE "first_name" LIKE 'H%';
+
+-- For query2
+SELECT "id", "first_name", "last_name", "age" 
+FROM "Person" 
+WHERE "first_name" NOT LIKE 'H%';
+```
+
+#### Ordering
+
+Specify column ordering in queries:
+
+```cpp
+using namespace sqlgen;
+
+// Order by age ascending
+const auto query1 = read<std::vector<Person>> | 
+                    order_by("age"_c);
+
+// Order by age descending
+const auto query2 = read<std::vector<Person>> | 
+                    order_by("age"_c.desc());
+
+// Multiple columns with mixed ordering
+const auto query3 = read<std::vector<Person>> | 
+                    order_by("last_name"_c, "first_name"_c.desc());
+```
+
+This generates SQL like:
+
+```sql
+-- For query1
+SELECT "id", "first_name", "last_name", "age" 
+FROM "Person" 
+ORDER BY "age";
+
+-- For query2
+SELECT "id", "first_name", "last_name", "age" 
+FROM "Person" 
+ORDER BY "age" DESC;
+
+-- For query3
+SELECT "id", "first_name", "last_name", "age" 
+FROM "Person" 
+ORDER BY "last_name", "first_name" DESC;
+```
+
+#### Updates
+
+Set column values in UPDATE statements:
+
+```cpp
+using namespace sqlgen;
+
+// Update a single column
+const auto query1 = update<Person>("age"_c.set(46));
+
+// Update multiple columns
+const auto query2 = update<Person>(
+    "first_name"_c.set("last_name"_c),
+    "age"_c.set(100)
+) | where("first_name"_c == "Hugo");
+```
+
+This generates SQL like:
+
+```sql
+-- For query1
+UPDATE "Person" SET "age" = 46;
+
+-- For query2
+UPDATE "Person" 
+SET "first_name" = "last_name", "age" = 100 
+WHERE "first_name" = 'Hugo';
+```
+
+## Type Safety
+
+`sqlgen::col` class provides compile-time type safety:
+
+- Column names are validated at compile time using string literals
+- SQL injection is prevented through proper escaping and parameterization
+
+## Notes
+
+- The class supports all standard SQL comparison operators: `==`, `!=`, `<`, `<=`, `>`, `>=`
+- Column names are automatically quoted in generated SQL
+- The class is designed to be used with the query builder interface
+- All operations are composable and can be chained together
+- The class supports both value and column-to-column comparisons
+- String literals are automatically converted to the appropriate SQL type
+- The class is thread-safe and has no mutable state