go-gorm / gorm.io

GORM official site

Gorm Official Website

Welcome to the GORM official website, accessible at https://gorm.io.

Contributing to Documentation

At our GitHub repository, we currently only accept pull requests for English documentation. Basic markdown knowledge is sufficient for you to contribute. Feel free to update documents in the pages/docs and pages/gen directories. We highly value your contributions!

The site will automatically deploy new changes to the master branch upon commit.

Translating the Website

For translations into other languages, please visit https://translate.gorm.io. To add a new language for GORM, submit your request via GitHub issues. Approved translations will be managed through the translation site.

Developing this Site

The site is developed using hexo. Start your development with these commands:

$ npm install
$ npm install hexo -g
$ hexo serve

gorm.io's Issues

[Question] the fisrt update sql is not match it's comment

Document Link

https://gorm.io/docs/update.html

Your Question

the fisrt update sql is not match it's comment

Expected answer

the update gorm sql may be is that
db.Model(&user).Select("name").Updates(map[string]interface{}{"name": "hello"}

Go get forces Syntax Errors

github.com/jinzhu/gorm/schema

github.com/jinzhu/gorm/schema

src/github.com/jinzhu/gorm/schema/field.go:271:45: fieldValue.IsZero undefined (type reflect.Value has no field or method IsZero)
src/github.com/jinzhu/gorm/schema/field.go:276:45: fieldValue.IsZero undefined (type reflect.Value has no field or method IsZero)
src/github.com/jinzhu/gorm/schema/field.go:297:27: v.IsZero undefined (type reflect.Value has no field or method IsZero)
src/github.com/jinzhu/gorm/schema/naming.go:95:34: undefined: strings.Builder

While using a go get inside my project I am experiences this new errors right now. This happened from one build where it was working to the next. Didn't change go version or anything belonging to this.

[Question] In the new version, should we be using primary_key or primaryKey

Document Link

Your Question

We use gorm to manage our MySQL based tables. We recently upgraded to new gorm version and noticed "unique_index" was not working. We fixed our code to change it to "uniqueIndex". At the same time, we noticed that "primary_key" was still working for our tables where we use composite primary keys.

Expected answer

Please let us know is this expected, working accidentally and/or will be deprecated towards "primaryKey" in future?

[Bug]: select usage query multiple columns is wrong

Document Link

advanced_query.html#Pluck

Problem

// Requesting more than one column, use Scan or Find like this:
db.Select("name", "age").Scan(&users)
db.Select("name", "age").Find(&users)

There is a mistake, query multiple columns correct usage is:

db.Select([]string{"name", "age"}).Scan(&users)

chainable_api.go#L81

Spanish Translation

I would be happy to help with the Spanish translation.

[Question] Does Mssql support JSON field type

Document Link

https://gorm.io/docs/v2_release_note.html#DataTypes-JSON-as-example

Your Question

How to use JSON field with MSSQL database

Expected answer

Plugin, Solution, or it does not work with Gorm.

how to set time.Time default loc and format after query

when want get gorm query time.Time format as "2018-12-07T10:02:25Z" by default is "2018-12-07T18:02:25+08:00"
how can set time loc and format after query before return

Inefficient db writes when creating multiple child records at once

Creating multiple "Belongs To" children records at the same time as creating the parent should execute 1 INSERT statement for all of the child records.

From the MySQL manual

INSERT statements that use VALUES syntax can insert multiple rows. To do this, include multiple lists of column values, each enclosed within parentheses and separated by commas. Example:

INSERT INTO tbl_name (a,b,c) VALUES(1,2,3),(4,5,6),(7,8,9);

how to translate for v2 doc ?

Your Question

I'd like to do a Japanese translation of the v2 documentation site.
What is the best way to contribute?

Expected answer

pull request
or crowdin
or Should I wait a bit?

[Question] Scope is not supported in v2

Document Link

https://gorm.io/docs/update.html

Your Question

<Scope is not supported in v2，but many translations still use it. >

Expected answer

<How do I get SetColumn? >

[Question] please document the fact that gorm:query_option is no longer supported in v2

Document Link

https://gorm.io/docs/v2_release_note.html

Your Question

In v1.0, I've used gorm:query_option to do a locking read, as in:

db = db.Set("gorm:query_option", "FOR UPDATE")
db.Where("ID = ?", id).First(&customer)

This still compiles in v2 but has no effect and leads to subtle bugs.

Expected answer

Please add this issue to the migration guide and point to the documentation on locking reads.

Documentation on Security/SQL injection

Migrated from https://github.com/jinzhu/gorm/issues/660 .

This is a serious problem -- the doc should imply what is good and secure practice, and what is not.

[Question] Would it be helpful to add a warning note about using prepared statements?

Document Link

gorm.io/pages/docs/session.md

Line 43 in b28fc19

`PreparedStmt` creates prepared statement when executing any SQL and caches them to speed up future calls, for example:

Your Question

Should there be a warning that prepared statements don't apply to all use cases? Reading the documentation it reads like it's always a good idea to use prepared statements for improved speed.

There's a slight issue to be concerned with when using connection poolers like PGBouncer.

Useful article: https://www.depesz.com/2012/12/02/what-is-the-point-of-bouncing/

TLDR: It's possible that statements prepared on one database connection aren't available on another. When using a connection pooler the prepare / query execution may use different connections.

I realized this issue when writing tinypg. Here's the changelog description: https://github.com/joeandaverde/tinypg/blob/ab648e650298c68974be8a8fc827cc223795f563/CHANGELOG.md#L17-L23. I hope those learnings are helpful to this project!

Expected answer

Was this helpful?

[Bug]: Gorm v1 documentation search bar

Hi
Whenever I search something on the search bar of v1 documentation (https://v1.gorm.io) it takes me to the latest documentation (https://gorm.io). I think the base URL for the search bar needs to change.

Thai Translation Document

Hello, Can you setup on Thai language in crowdin, i help to translate it!

How I can handle tables Has One to a table [Question]

Document Link

https://gorm.io/docs/has_one.html#Self-Referential-Has-One

Your Question

Following the document, we have a simple case for has-one relationship like below

// User has one CreditCard, CreditCardID is the foreign key
type User struct {
  gorm.Model
  CreditCard CreditCard
}

type CreditCard struct {
  gorm.Model
  Number string
  UserID uint
}

I'm starting concern what if we have 2 tables contain has-one relationship like

type Teacher struct {
  gorm.Model
  CreditCard CreditCard
}

type Student struct {
  gorm.Model
  CreditCard CreditCard
}

type CreditCard struct {
  gorm.Model
  Number string
  TeacherId uint
  StudentId uint
}

Let's say each time we create a teacher or a student, we also need to create their credit cards. So with current implementation, how we can solve it? Thank you.

Expected answer

Incorrect HAS_ONE example

The example in this new documentation appears to be incorrect, unlike the one in the older version, as explained on https://github.com/jinzhu/gorm/issues/2206 : in short, unlike the BELONGS_TO case, with HAS_ONE (like HAS_MANY), the FK ID is on the owned entity, not on the owner.

In the User/CreditCard example, this means having UserID on CreditCard.

Typo on Query#Pluck section

https://gorm.io/docs/query.html#Pluck

Pluck puts single column into a slice, not a map.

Typo on Batch Updates

https://gorm.io/docs/update.html#Batch-Updates

Your Question

Missing closing quote on last word:
// UPDATE users SET name='hello', age=18 WHERE role = 'admin;
Should be
// UPDATE users SET name='hello', age=18 WHERE role = 'admin';

BUG: There's a wrong link on the website

Wrong link at "https://gorm.io/community.html"

under video examples there an anchor tag that should (at least that what I think) lead to.a youtube video about gorm tutorial but instead it has a link to a section in the same page (href="#contribute").

File to be changed: "https://github.com/go-gorm/gorm.io/blob/master/pages/community.md" under "##videos"

Polish translation

Hey, if we could set up Polish translation on gorm.io, I'd be happy to help!

conventions.md chinese translation update

I translated entire page into chinese, include comments.
please check.

Add Yoruba translation

I would like to partake in translation to Yoruba, one of the major Nigerian languages. Thanks

French translation

Hey, I would be interested in starting working on a French translation.

Add documentation on how to create a uuid field in a struct model (preferrably pgcrypto)

[New Translation] Spanish associations.md

Request New Translation

• Language Name: Spanish
• Language Code: es-ES
• Disqus Lang Code: es

Please only request to translate a new language if you are a GORM & Golang user at least one year, and can translate at least 40% of documents

Thank you.

Gorm.io not updated

http://doc.gorm.io/crud.html#query contains a typo (Assgin) whereas in master it's already been fixed more than a year ago: https://github.com/jinzhu/gorm.io/blob/aa737260c9d1253f9f5ae355d30bd313a4720ca0/pages/docs/query.md#attrs-1

Is gorm.io automatically updated from master? cc @jinzhu

German Translation

Hi, I love your gorm project and would be happy to help by translating your docs to german!

Arabic translation

Hello , i'll be very happy if you allow me to help to translate the gorm documentation in Arabic

I'd like to start translating it in Korean

I hope that my effort would be helpful for Koeran developers.

Clarify please the role of "Not null" for required fields

http://gorm.io/docs/models.html

type User struct {
  gorm.Model
  Name         string
  Age          sql.NullInt64
  Birthday     *time.Time
  Email        string  `gorm:"type:varchar(100);unique_index"`
  Role         string  `gorm:"size:255"` // set field size to 255
  MemberNumber *string `gorm:"unique;not null"` // set member number to unique and not null
  Num          int     `gorm:"AUTO_INCREMENT"` // set num to auto incrementable
  Address      string  `gorm:"index:addr"` // create index with name `addr` for address
  IgnoreMe     int     `gorm:"-"` // ignore this field
}

CREATE TABLE public.users
(
  id		serial,
  created_at	timestamp with time zone,
  updated_at	timestamp with time zone,
  deleted_at	timestamp with time zone,
  name		text,
  age		integer,
  birthday	timestamp with time zone,
  email		varchar(100) unique,
  role		varchar(255),
  member_number	text unique not null,
  num		integer,
  address	text,
  CONSTRAINT users_pkey PRIMARY KEY (id)
)
WITH (
    OIDS = FALSE
)
TABLESPACE pg_default;

The point here is: why the migration to SQL is not null if the column is required?
Just take a look to Age. This field de-facto is required, so why the migration isn't adding the clausule not null in the sql table definition?

And finally: MemberNumber *string looks really strange to me. That field de-facto accepts null values, but the label gorm:not null contradicts that definition. Why?

Line breaking for long query example so that user do not need to scroll horizontally and text overlapped

From:

db.Where("name = ?", "jinzhu").Or("name = ?", "jinzhu 2").Find(&users).Count(&count)
//// SELECT * from USERS WHERE name = 'jinzhu' OR name = 'jinzhu 2'; (users)
//// SELECT count(*) FROM users WHERE name = 'jinzhu' OR name = 'jinzhu 2'; (count)
db.Model(&User{}).Where("name = ?", "jinzhu").Count(&count)
//// SELECT count(*) FROM users WHERE name = 'jinzhu'; (count)
db.Table("deleted_users").Count(&count)
//// SELECT count(*) FROM deleted_users;

---

into:

db.
     Where("name = ?", "jinzhu").
     Or("name = ?", "jinzhu 2").
     Find(&users).
     Count(&count)

// SELECT *
// FROM USERS
// WHERE
//     name = 'jinzhu' OR
//     name = 'jinzhu 2'
// ; (count)

// SELECT count(*)
// FROM users
// WHERE
//     name = 'jinzhu' OR
//     name = 'jinzhu 2'
// ; (count)

db.
     Model(&User{}).
     Where("name = ?", "jinzhu").
     Count(&count)
// SELECT count(*)
// FROM users
// WHERE name = 'jinzhu'; (count)

db.
     Table("deleted_users").
     Count(&count)
// SELECT count(*)
// FROM deleted_users;

Typo in http://gorm.io/docs/associations.html

https://github.com/jinzhu/gorm.io/blame/master/pages/docs/associations.md#L17

jinzhu-2@[email protected]

Preload sample code references non-existent fields

Sample structs were added in #168 but they do not include fields referenced throughout the examples. The structs should reflect the actual examples. In particular, I believe the Order struct needs a state field.

[New Translation] Portuguese Brazil

Request New Translation

• Language Name: Portuguese Brazil
• Language Code: pt-BR
• Disqus Lang Code: pt

I'm using GORM and Golang +-2 years on most projects.

Please only request to translate a new language if you are a GORM & Golang user at least one year, and can translate at least 40% of documents

Thank you.

Where is the documentation's hexo theme from?

Where is the documentation's hexo theme from?

I would like to translate to Russian

[Question] Joins-Preloading explanation of generated join type unclear.

Document Link

https://gorm.io/docs/preload.html#Joins-Preloading

Your Question

The documentation states that "Join Preload will loads association data using inner join". But the (Company) query example shows a conditional left join being generated and not an inner join. Its also not clear if this is always the case when using Joins() or only when using Joins() in combination with extra conditions.

Expected answer

Clear explanation of which type of join is used when.

Full Composite Keys are not used when retrieving using Related

This statement:
db.First(&term, edu.Term{CompanyID: companyID, SchoolID: schoolID, ID: id}).Related(&term.School)

Produces the following SQL
[2018-08-30 16:03:06] [0.53ms] SELECT * FROM local-edu-terms WHERE local-edu-terms.deleted_at IS NULL AND ((local-edu-terms.company_id = '2ivyBYA34mJF64xZydUfoC') AND (local-edu-terms.school_id = '3421SZLzgHw3hjM7DEfioa') AND (local-edu-terms.id = '2GvoEzV6n2noEOyyqOlwf4')) ORDER BY local-edu-terms.id ASC LIMIT 1
[1 rows affected or returned ]

[2018-08-30 16:03:06] [0.49ms] SELECT * FROM local-edu-schools WHERE local-edu-schools.deleted_at IS NULL AND ((id = '3421SZLzgHw3hjM7DEfioa')) ORDER BY local-edu-schools.id ASC
[1 rows affected or returned ]

In the above example, local-edu-terms is a child of(Belongs To) local-edu-schools
The second SQL statement should be:
SELECT * FROM local-edu-schools WHERE local-edu-schools.deleted_at IS NULL AND ((local-edu-schools.company_id = '2ivyBYA34mJF64xZydUfoC') AND (id = '3421SZLzgHw3hjM7DEfioa')) ORDER BY local-edu-schools.id ASC

Japanese Translation

Hi,
I want to translate gorm docs to Japanese!

Brazilian Portuguese Translation

I'd gladly help to translate gorm =D

Automigrate not working with dbresolver

Trying to use two databases master and shard1.

Tried using dbresolver to automigrate some models for both databases.

Here is the code for it

dsnMaster := viper.GetString("MYSQL_DSN_MASTER")
dsnShard1 := viper.GetString("MYSQL_DSN_SHARD1")

db, err := gorm.Open(mysql.Open(dsnMaster), &gorm.Config{
	Logger: logger.Default.LogMode(logger.Info)})

if err != nil {
	log.Println("Connection Failed to Open")
} else {
	log.Println("Connection Established")
}

db.Use(dbresolver.Register(dbresolver.Config{
	Sources: []gorm.Dialector{mysql.Open(dsnShard1)},
}, &models.WorkspaceGroup{}, &models.GroupMember{}, &models.WorkspaceFile{}, &models.WorkspacePermission{}, &models.Permission{}, &models.WorkspacePermissionEntry{}, "shard1"))

db.AutoMigrate(&models.Workspace{}, &models.WorkspaceMember{})

// db.AutoMigrate(&models.Workspace{}, &models.WorkspaceMember{}, &models.WorkspaceGroup{}, &models.GroupMember{})

db.Clauses(dbresolver.Use("shard1")).AutoMigrate(&models.WorkspaceGroup{}, &models.GroupMember{}, &models.WorkspaceFile{}, &models.WorkspacePermission{}, &models.Permission{}, &models.WorkspacePermissionEntry{})

When trying to automigrate on models for shard1, it is not getting reflected in the database. Changes are still going to master database. No error is thrown, dbresolver is not able to resolve correct database during automigration.

It there anything that needs to be done? Or is it an issue?

[Question] About New Session Mode

Document Link

Method Chaining > New Session Mode

Your Question

The two examples are very confusing. Correct me if I'm wrong:

In example 2, the last query tx.Where("age = ?", 28).Find(&users) is incorrectly sharing the where clauses of an already-executed query (tx.Where("age = ?", 18).Find(&users)), because the two queries were derived from the same session (created by tx := db.Where("name = ?", "jinzhu")), and because the finisher Find() does not reset internal state of tx.

However, in example 1, all the three queries were also derived from the same db which has the same type (*gorm.DB) as tx in example 2. And since finishers does not reset internal state of tx, one would reasonably think it behaves the same for db. So, after the first query db.Where("name = ?", "jinzhu").Where("age = ?", 18).Find(&users), db is no longer a "newly initialized *gorm.DB" (since a query has been executed on it). If that is true, how come the second query db.Where("name = ?", "jinzhu2").Where("age = ?", 20).Find(&users) does not share the where statement from the first query?

I can think of two explanations:

1. Either: finishers would reset internal state of db but not tx.
2. Or: db is still considered a "newly initialized *gorm.DB", no matter how many queries it has ran.

I kinda think explanation 2 is the correct one, but I'm no sure. Would you mind to clarify? I saw there's another user asking the same question (essentially) in comments of the documentation page, but so far nobody really answered.

Expected answer

[Question] Primary Key tag is camel or snake case?

Document Link

https://gorm.io/docs/composite_primary_key.html

Your Question

Along all docs pages that I visited to set primary key is described as adding the gorm:"primaryKey" label to the struct, but here only worked after I changed to gorm:"primary_key". Just to be clear: I changed camel to snake case.

Expected answer

Russian translation

Would be happy to help here

[Feature] Dark theme

Describe the feature

Adding a dark theme with the ability to switch to a light one. By default, the selected system theme is expected

Motivation

I, like many other programmers, use a dark theme in development and surfing. I think that many people will be grateful to read the documentation in a convenient environment for them

---

UPD: I can help with this if there is any help with the design or other help :)

slack link

the slack link on the community page is dead

U need an Italian translation?

Hi, some of the title? if you need you can add in crowdin page and give me the proof of reader abilitation (some nickname "Deusjudo"

Too big text on site

Why text on site so big? And why site have no option to complain??

www.gorm.io shows parked page

www.gorm.io shows a This domain name has been registered with... parked page instead of this site. Perhaps a redirect needs to be setup for www.