Skip to content

Commit ec6a5a6

Browse files
github-actions[bot]SockworkOrange
github-actions[bot]
and
SockworkOrange
authoredMar 4, 2025··
update docs (#227)
Co-authored-by: SockworkOrange <26390445+SockworkOrange@users.noreply.github.com>
1 parent 614cded commit ec6a5a6

File tree

2 files changed

+167
-18
lines changed

2 files changed

+167
-18
lines changed
 

‎README.md

+165-16
Original file line numberDiff line numberDiff line change
@@ -12,8 +12,8 @@ version: "2"
1212
plugins:
1313
- name: csharp
1414
wasm:
15-
url: https://github.com/DaredevilOSS/sqlc-gen-csharp/releases/download/v0.15.2/sqlc-gen-csharp.wasm
16-
sha256: 251cfaaeccaf726aa06103fcdab500006b4bc5cd0be523eb6a8894db8d520147
15+
url: https://github.com/DaredevilOSS/sqlc-gen-csharp/releases/download/v0.16.0/sqlc-gen-csharp.wasm
16+
sha256: 648c06737ea6050b06d2469f1c56be39dd336dec15097de01c550f7001928b91
1717
sql:
1818
# For PostgresSQL
1919
- schema: schema.sql
@@ -48,7 +48,12 @@ sql:
4848
| useDapper | default: `false`<br/>values: `false`,`true` | Yes | Enables Dapper as a thin wrapper for the generated code. For more information, please refer to the [Dapper documentation](https://github.com/DapperLib/Dapper). |
4949
| overrideDapperVersion | default:<br/> `2.1.35`<br/>values: The desired Dapper version | Yes | If `useDapper` is set to `true`, this option allows you to override the version of Dapper to be used. |
5050

51-
## Query Annotations
51+
## Supported Features
52+
- ✅ means the feature is fully supported.
53+
- 🚫 means the database does not support the feature.
54+
- ❌ means the feature is not supported by the plugin (but could be supported by the database).
55+
56+
### Query Annotations
5257
Basic functionality - same for all databases:
5358
- `:one` - returns 0...1 records
5459
- `:many` - returns 0...n records
@@ -60,26 +65,22 @@ Advanced functionality - varies between databases:
6065
- `:copyfrom` - batch insert, implementation varies greatly
6166
<br/>
6267

63-
| Annotation | PostgresSQL | MySQL | SQLite |
64-
|-------------|-------------|-------|--------|
68+
| Annotation | PostgresSQL | MySQL | SQLite |
69+
|-------------|-------------|-------|---------|
6570
| :one | ✅ | ✅ | ✅ |
6671
| :many | ✅ | ✅ | ✅ |
6772
| :exec | ✅ | ✅ | ✅ |
6873
| :execrows | ✅ | ✅ | ✅ |
6974
| :execlastid | ✅ | ✅ | ✅ |
70-
| :copyfrom | ✅ | ✅ | ❌ |
71-
72-
- ✅ means the feature is fully supported.
73-
- ❌ means the feature is not supported by the plugin (but could be supported by the database).
75+
| :copyfrom | ✅ | ✅ | ✅ |
7476

7577
More info can be found in [here](https://docs.sqlc.dev/en/stable/reference/query-annotations.html).
7678

77-
## Macro Annotations
79+
### Macro Annotations
7880
- `sqlc.arg` - Attach a name to a parameter in a SQL query
7981
- `sqlc.narg` - The same as `sqlc.arg`, but always marks the parameter as nullable
8082
- `sqlc.slice` - For databases that do not support passing arrays to the `IN` operator, generates a dynamic query at runtime with the correct number of parameters
8183
- `sqlc.embed` - Embedding allows you to reuse existing model structs in more queries
82-
8384
<br/>
8485

8586
| Annotation | PostgresSQL | MySQL | SQLite |
@@ -89,12 +90,160 @@ More info can be found in [here](https://docs.sqlc.dev/en/stable/reference/query
8990
| sqlc.slice | 🚫 | ✅ | ✅ |
9091
| sqlc.embed | ✅ | ✅ | ✅ |
9192

92-
- ✅ means the feature is fully supported.
93-
- 🚫 means the database does not support the feature.
94-
- ❌ means the feature is not supported by the plugin (but could be supported by the database).
95-
9693
More info can be found in [here](https://docs.sqlc.dev/en/stable/reference/macros.html#macros).
97-
# Contributing
94+
# PostgresSQL
95+
## :execlastid - Implementation
96+
Implemented via a `RETURNING` clause, allowing the `INSERT` command to return the newly created id, which can be of any
97+
data type that can have a unique constraint.
98+
99+
## :copyfrom - Implementation
100+
Implemented via the `COPY FROM` command which can load binary data directly from `stdin`.
101+
102+
## Data Types
103+
Since in batch insert the data is not validated by the SQL itself but written in a binary format,
104+
we consider support for the different data types separately for batch inserts and everything else.
105+
106+
| DB Type | Supported? | Supported in Batch? |
107+
|-----------------------------------------|-----------|---------------------|
108+
| boolean | ✅ | ✅ |
109+
| smallint | ✅ | ✅ |
110+
| integer | ✅ | ✅ |
111+
| bigint | ✅ | ✅ |
112+
| real | ✅ | ✅ |
113+
| decimal, numeric | ✅ | ✅ |
114+
| double precision | ✅ | ✅ |
115+
| date | ✅ | ✅ |
116+
| timestamp, timestamp without time zone | ✅ | ✅ |
117+
| timestamp with time zone | ❌ | ❌ |
118+
| time, time without time zone | ❌ | ❌ |
119+
| time with time zone | ❌ | ❌ |
120+
| interval | ❌ | ❌ |
121+
| char | ✅ | ✅ |
122+
| bpchar | ❌ | ❌ |
123+
| varchar, character varying | ✅ | ✅ |
124+
| text | ✅ | ✅ |
125+
| bytea | ✅ | ✅ |
126+
| 2-dimensional arrays (e.g text[],int[]) | ✅ | ❌ |
127+
| money | ❌ | ❌ |
128+
| line | ❌ | ❌ |
129+
| lseg | ❌ | ❌ |
130+
| box | ❌ | ❌ |
131+
| path | ❌ | ❌ |
132+
| polygon | ❌ | ❌ |
133+
| circle | ❌ | ❌ |
134+
| cidr | ❌ | ❌ |
135+
| inet | ❌ | ❌ |
136+
| macaddr | ❌ | ❌ |
137+
| macaddr8 | ❌ | ❌ |
138+
| tsvector | ❌ | ❌ |
139+
| tsquery | ❌ | ❌ |
140+
| uuid | ❌ | ❌ |
141+
| json | ❌ | ❌ |
142+
| jsonb | ❌ | ❌ |
143+
| jsonpath | ❌ | ❌ |
144+
# MySQL
145+
146+
## :execlastid - Implementation
147+
The implementation differs if we're using `Dapper` or not.
148+
149+
### Driver - MySqlConnector
150+
The driver provides a `LastInsertedId` property to get the latest inserted id in the DB.
151+
When accessing the property, it automatically performs the below query:
152+
153+
```sql
154+
SELECT LAST_INSERT_ID();
155+
```
156+
157+
That will work only when the id column is defined as `serial` or `bigserial`, and the generated method will always return
158+
a `long` value.
159+
160+
### Dapper
161+
Since the `LastInsertedId` is DB specific and hence not available in Dapper, the `LAST_INSERT_ID` query is simply
162+
appended to the original query like this:
163+
164+
```sql
165+
INSERT INTO tab1 (field1, field2) VALUES ('a', 1);
166+
SELECT LAST_INSERT_ID();
167+
```
168+
169+
The generated method will return `int` & `long` for `serial` & `bigserial` respectively.
170+
171+
## :copyfrom - Implementation
172+
Implemented via the `LOAD DATA` command which can load data from a `CSV` file to a table.
173+
Requires us to first save the input batch as a CSV, and then load it via the driver.
174+
175+
## Data Types
176+
Since in batch insert the data is not validated by the SQL itself but written and read from a CSV,
177+
we consider support for the different data types separately for batch inserts and everything else.
178+
179+
| DB Type | Supported? | Supported in Batch? |
180+
|---------------------------|------------|---------------------|
181+
| bool, boolean, tinyint(1) | ✅ | ✅ |
182+
| bit | ✅ | ✅ |
183+
| tinyint | ✅ | ✅ |
184+
| smallint | ✅ | ✅ |
185+
| mediumint | ✅ | ✅ |
186+
| integer, int | ✅ | ✅ |
187+
| bigint | ✅ | ✅ |
188+
| real | ✅ | ✅ |
189+
| numeric | ✅ | ✅ |
190+
| decimal | ✅ | ✅ |
191+
| double precision | ✅ | ✅ |
192+
| year | ✅ | ✅ |
193+
| date | ✅ | ✅ |
194+
| timestamp | ✅ | ✅ |
195+
| char | ✅ | ✅ |
196+
| nchar, national char | ✅ | ✅ |
197+
| varchar | ✅ | ✅ |
198+
| tinytext | ✅ | ✅ |
199+
| mediumtext | ✅ | ✅ |
200+
| text | ✅ | ✅ |
201+
| longtext | ✅ | ✅ |
202+
| binary | ✅ | ❌ |
203+
| varbinary | ✅ | ❌ |
204+
| tinyblob | ✅ | ❌ |
205+
| blob | ✅ | ❌ |
206+
| mediumblob | ✅ | ❌ |
207+
| longblob | ✅ | ❌ |
208+
| enum | ❌ | ❌ |
209+
| set | ❌ | ❌ |
210+
| json | ❌ | ❌ |
211+
| geometry | ❌ | ❌ |
212+
| point | ❌ | ❌ |
213+
| linestring | ❌ | ❌ |
214+
| polygon | ❌ | ❌ |
215+
| multipoint | ❌ | ❌ |
216+
| multilinestring | ❌ | ❌ |
217+
| multipolygon | ❌ | ❌ |
218+
| geometrycollection | ❌ | ❌ |
219+
# SQLite3
220+
221+
## :execlastid - Implementation
222+
Implemented via a `RETURNING` clause, allowing the `INSERT` command to return the newly created id, which can be of any
223+
data type that can have a unique constraint.
224+
225+
```sql
226+
INSERT INTO tab1 (field1, field2) VALUES ('a', 1) RETURNING id_field;
227+
```
228+
229+
## :copyfrom - Implementation
230+
Implemented via a multi `VALUES` clause, like this:
231+
232+
```sql
233+
INSERT INTO tab1 (field1, field2) VALUES
234+
('a', 1),
235+
('b', 2),
236+
('c', 3);
237+
```
238+
239+
## Data Types
240+
241+
| DB Type | Supported? |
242+
|---------|------------|
243+
| integer | ✅ |
244+
| real | ✅ |
245+
| text | ✅ |
246+
| blob | ✅ |# Contributing
98247
## Local plugin development
99248
### Prerequisites
100249
Make sure that the following applications are installed and added to your path.

‎docs/02_Quickstart.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,8 @@ version: "2"
44
plugins:
55
- name: csharp
66
wasm:
7-
url: https://github.com/DaredevilOSS/sqlc-gen-csharp/releases/download/v0.15.2/sqlc-gen-csharp.wasm
8-
sha256: 251cfaaeccaf726aa06103fcdab500006b4bc5cd0be523eb6a8894db8d520147
7+
url: https://github.com/DaredevilOSS/sqlc-gen-csharp/releases/download/v0.16.0/sqlc-gen-csharp.wasm
8+
sha256: 648c06737ea6050b06d2469f1c56be39dd336dec15097de01c550f7001928b91
99
sql:
1010
# For PostgresSQL
1111
- schema: schema.sql

0 commit comments

Comments
 (0)
Please sign in to comment.