Skip to content

update current README with slight re-wording and typo fixes #6

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
NathanDennis wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

update current README with slight re-wording and typo fixes #6

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 20 additions & 11 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,17 +2,24 @@

Opinionated Database Extraction Library for Go, It's got some ORM, but does not hide the SQL.

While GORM is a popular choice, I believe strongly in developers understanding and writing SQL queries directly. SQL
proficiency should be a fundamental skill for all developers. However, Go's verbose syntax can make database
While GORM is a popular choice, I believe strongly in developers understanding and writing SQL queries directly.

SQL proficiency should be a fundamental skill for all developers. However, Go's verbose syntax can make database
interactions quite lengthy and repetitive.

GSDB give you some ORM features but you still need to write SQL.

GSDB, works for me, as it provides direct access to run queries and access the results with a simple "record" and "field" types. It also provides Database to Struct transformations. If the struct is has the extra "db" tags to define columns, primary keys read default conditions, GSDB will translate DB resources into Structs and provides like .Save() methods. Making it easy to define a struct, load it with data and just call a DB.Save to save it to the database
GSDB works for me, as it provides direct access to run queries and access the results with simple "record" and "field" types.
It also provides Database to Struct transformations. If the struct has the extra "db" tags to define columns, primary keys read default conditions, GSDB will translate DB resources into Structs and provide methods such as .Save(); Making it easy to define a struct, load it with data and just call a DB.Save to save it to the database

GSDB is designed to abstract a lot of the boilerplate DB code away from you. It makes writing CRUD applications easier, but, with that ease of use, comes trade-offs.
GSDB uses reflection to determine many of the type conversions. It also holds complete record sets in memory.
If you need fast, high performance and efficient DB access, GSDB probably isn't for you.

GSDB is designed to abstract alot of the boiler plate DB code away from you, it makes writing CRUD applications easier, with that ease of use, comes trade offs. GSDB uses reflection to determine many of the type conversions, it also holds complete record sets in memory. If you need fast, high performance and efficient DB access, GSDB probably isn't for you.
Another thing I didn't like about SQL handling in Go, was making structs contain SQL data types such as sql.Null.
To me this seems lazy. It ties your struct to a database, increasing the boilerplate and scaffolding you need to work with the data. To me, the data is either strings or dates. Then the struct is either string or time.Time.

Another thing I didn't like about SQL handling in Go, was making structs contain SQL data types. Like sql.Null. To me this seems lazy, and ties your struct to a database. Increasing the boiler plate and scaffolding you need to work with the data, to me the data is string or date. Then the struct is string or time.Time. I'm keen to keep primatives, as primative as possible.
I'm keen to keep primitives, as primitive as possible.

### Connecting

Expand All @@ -29,7 +36,7 @@ lastInsertedID, rowsAffected, err := gsdb.DB.Execute(sqlQuery,parameters...)
```
### Making Insert and Update SQL

gsdb provides 2 functions to make SQL statements from structs, DB.Insert and DB.Update. If you pass in any variable from a struct, the library will build the SQL nessesary for an INSERT or UPDATE statement.
gsdb provides 2 functions to make SQL statements from structs, DB.Insert and DB.Update. If you pass in any variable from a struct, the library will build the SQL necessary for an INSERT or UPDATE statement.

```go
type InsertPerson struct {
Expand Down Expand Up @@ -60,7 +67,7 @@ gsdb provides 2 functions to make SQL statements from structs, DB.Insert and DB.

### Hex conversion of strings

All strings, are converted to HEX. This ensures even the most challenging characters are written to the db as it, it also makes SQL injections attacks difficult.
All strings are converted to HEX. This ensures even the most challenging characters are written to the DB as it also makes SQL injections attacks difficult.

```sql
INSERT INTO Test(name,dtadded,status) VALUES (X'54657374','2025-12-25 15:29:25',1);
Expand All @@ -75,11 +82,13 @@ QueryStruct will return a slice of type T containing all the data.
This works the same as QueryStruct, but returns T, not a slice of type T.
When returning datetimes from the database, there are some extra options to determine how you can view NULL or EMPTY dates in the database. "readdefault=now" or "readdefault=zero"

In a early version of this library, if there was a nil date, it return time.Now(), which is actually undeserved, however early versions of applications depending on a null = time.Now for the some of the business logic. So this was left in as default behaviour, however to handle things properly readdefault=zero, is best. As the date is returned as "0001-01-01 00:00:00"
In early versions of GSDB, if a date field in the database was NULL, the library returned time.Now() instead. That behavior wasn’t really correct, but some applications had already built business logic around the idea that a NULL date meant “current time.” To preserve compatibility, GSDB kept this as the default.

However, the recommended approach is to use the tag readdefault=zero, which tells GSDB to return the Go “zero time” (0001-01-01 00:00:00) for NULL dates. This is usually the proper way to represent missing or unset timestamps.

### Save

If the primary key is zero, the an Insert is done, otherwise it's an Update.
If the primary key is zero, then an Insert is executed, otherwise it's an Update.

```go
type InsertPerson struct {
Expand Down Expand Up @@ -118,13 +127,13 @@ This is experimental at this stage.

### ColumnWarnings

If the struct doesn't match the SQL returned or generated. The library will spit out a warning that there is a mis-match, and then ignore it. You can turn of this warning with
If the struct doesn't match the SQL returned or generated. The library will spit out a warning that there is a mismatch, and then ignore it. You can turn of this warning with

```go
MySQL.ColumnWarnings = true
P, _ := MySQL.QuerySingleStruct[InsertPerson]("select * from Test WHERE ID = ?", lastInsertedID)
```
If there any fields defined in InsertPerson that don't match the record set, a warning is raised.
If there are any fields defined in InsertPerson that don't match the record set, a warning is raised.


### ShowSQL
Expand Down