std::vector
std::vector<T> fields map directly to native collection types in supported databases.
Currently supported for DuckDB and PostgreSQL. On other databases, std::vector fields fail with a compile-time error.
Usage
Basic Definition
Define a list field directly as std::vector<T>:
struct ListTable {
int32_t id;
std::vector<int32_t> numbers;
std::vector<std::string> labels;
};This generates the following SQL schema:
-- DuckDB/PostgreSQL
CREATE TABLE IF NOT EXISTS "ListTable"("id" INTEGER NOT NULL, "numbers" INTEGER[] NOT NULL, "labels" TEXT[] NOT NULL);Nested Lists
Nested vectors are supported to arbitrary depth, with one [] suffix added per nesting level:
struct Matrix {
int32_t id;
std::vector<std::vector<int32_t>> nested;
};-- DuckDB/PostgreSQL
CREATE TABLE IF NOT EXISTS "Matrix"("id" INTEGER NOT NULL, "nested" INTEGER[][] NOT NULL);Nullable Lists and Nullable Elements
Nullability is controlled the same way as for scalar fields:
std::optional<std::vector<T>>: the entire list may beNULLstd::vector<std::optional<T>>: the list isNOT NULL, but individual elements may beNULL
struct NullableLists {
int32_t id;
std::optional<std::vector<int32_t>> nullable_list;
std::vector<std::optional<int32_t>> nullable_elements;
};-- DuckDB / PostgreSQL
CREATE TABLE IF NOT EXISTS "NullableLists"("id" INTEGER NOT NULL, "nullable_list" INTEGER[], "nullable_elements" INTEGER[] NOT NULL);Reading and Writing
Use the regular sqlgen::write and sqlgen::read APIs.
using namespace sqlgen;
using namespace sqlgen::literals;
struct Person {
int32_t id;
std::string first_name;
std::vector<std::string> children;
};
const auto people = std::vector<Person>({
Person{.id = 1, .first_name = "Homer", .children = {"Bart", "Lisa", "Maggie"}},
Person{.id = 2, .first_name = "Bart", .children = {}}
});
// DuckDB example (analogous for PostgreSQL)
const std::vector<Person> result = sqlgen::duckdb::connect()
.and_then(create_table<Person>)
.and_then(write(std::ref(people)))
.and_then(sqlgen::read<std::vector<Person>>)
.value();
// result is identical to people
Empty lists and missing values round-trip correctly.
Database Integration
std::vector<T> maps to the dialect’s native collection type:
- DuckDB:
LIST(variable-length, no shape restrictions) - PostgreSQL:
ARRAY(governed by a strict structural rule)
Important: PostgreSQL arrays must be rectangular, so every sub-array within a dimension must have the same length: {{1, 2}, {3, 4}} is valid, while {{1, 2}, {3}} is not (PostgreSQL docs). sqlgen cannot check this at compile-time, so a non-rectangular value only surfaces as an error when the database rejects it on write.
Notes
- Only supported for DuckDB and PostgreSQL. Compilation fails with
"std::vector fields are not supported by this database."if the database doesn’t support it. - Works with type-safe operations such as
create_table,write/insertandread - Nested vectors (
std::vector<std::vector<T>>) supported to arbitrary depth