Getting Started with GORM<\/h2>\n
You\u2019ll need to meet a few requirements to get the most out of this article.<\/p>\n
- \n
- You have experience working with Go<\/a> and have Go installed on your machine.<\/li>\n
- You have experience working with SQL and SQL databases.<\/li>\n<\/ul>\n
In this tutorial, you\u2019ll learn how to use GORM with an SQLite database. The processes are generally the same for all other supported SQL databases.<\/p>\n
After creating a Go workspace, Install the GORM package using these commands in your working directory.<\/p>\n
go get gorm.io\/gorm<\/pre>\n
You\u2019ll need a database driver to work with GORM. Fortunately, GORM also provides database drivers for the popular SQL databases. Install the database driver for your preferred database using any of these commands.<\/p>\n
go get gorm.io\/driver\/sqlite \/\/SQLite \r\ngo get gorm.io\/driver\/mysql \/\/ MySQL \r\ngo get gorm.io\/driver\/postgres \/\/PostgreSQL \r\ngo get gorm.io\/driver\/sqlserver \/\/MSSQL \r\ngo get gorm.io\/driver\/clickhouse \/\/click house <\/pre>\n
GORM also provides functionalities for using custom database drivers. This is beyond the scope of this article, but you can read more here<\/a>.<\/p>\n
After installing your database driver, you can import the driver for use.<\/p>\n
import ( \r\n \"gorm.io\/gorm\" \r\n _ \"github.com\/mattn\/go-sqlite3\" \r\n )<\/pre>\n
As shown above, you\u2019ll have to import the database driver for side effects. (This allows interactions with the database over GORMs interface to do things like query and modify data.)<\/p>\n
Connecting to Databases using GORM<\/h2>\n
After installing and importing the GORM package and your preferred database driver, you can proceed to connect to your database.<\/p>\n
Use the Open method of the gorm module to connect to a database. The Open method takes in the connection and configuration methods as input and returns the database connection instance.<\/p>\n
db, err = gorm.Open(sqlite.Open(\"Blogs.db\"), &gorm.Config{})\r\n \r\nif err != nil { \r\n panic(\"failed to connect database\") \r\n}<\/pre>\nThe previous code connects to an in-memory SQLite database in the code example above. For SQLite, the
Open<\/code> method creates a database in your working directory if the database doesn\u2019t exist. The process is similar if you connect to a database with a connection string. In the following code, I am connecting to a MySQL database using a connection string.<\/p>\nDb, err = gorm.Open(mysql.Open(\u201croot:admin@tcp(127.0.0.1:3306)\/yourdatabase?charset=utf8mb4&parseTime=True&loc=Local\u201d), &gorm.Config{}) \r\nif err != nil { \r\n panic(\u201cfailed to connect database\u201d) \r\n}<\/pre>\nConnecting to a database is similar if you use a custom database driver. You must connect to the database based on the specifications that were included in the driver, and pass the connection details to the
Open<\/code> method.<\/p>\nDb, err := gorm.Open(\u201csqlite3\u201d, \u201c.\/app.db\u201d)<\/pre>\n
In this case, you\u2019re using the custom SQLite driver imported above. On a successful database connection, you\u2019ll be able to interact with the database with Go data types in the same way.<\/p>\n
Mapping Go Types With GORM<\/h2>\n
GORM is a code-first ORM. This means you won\u2019t have to define your schema in SQL. For GORM, you use Go structs to describe the schema and column types with GORM tags.<\/p>\n
Type Human struct { \r\n Age int \r\n Name string \r\n}<\/pre>\nOn migration, the
Human<\/code> struct will be translated to the database schema. The table’s name in the database will beHuman<\/code> and theAge<\/code> andName<\/code> fields are the column names.<\/p>\nGORM provides tags for adding SQL constraints like primary key, foreign keys, index, not null and other database constraints. Here\u2019s how you can add a GORM tag to a struct.<\/p>\n
type Human struct { \r\n Age int `gorm:\"primaryKey\"` \r\n Name string `gorm:\"size:255;not null;unique\"` \r\n}<\/pre>\nThe Age field has a primary key constraint, and the Name field has size, not null and unique constraints.<\/p>\n
For easy schema modelling, GORM provides the GORM Model. The GORM model is a struct that contains popularly used fields like
ID<\/code> as the primary key and the created, updated, and deleted time as columns. You can use theModel<\/code> struct by passing the model to your struct.<\/p>\ntype Human struct { \r\n gorm.Model \r\n Age int `gorm:\"primaryKey\"` \r\n Name string `gorm:\"size:255;not null;unique\"` \r\n}<\/pre>\nThe Human struct above evaluates to the HumanPlus struct below in the database on migration since the Human struct inherits the gorm.Model struct<\/a>.<\/p>\n
type HumanPlus struct { \r\n Age int `gorm:\"primaryKey\"` \r\n Name string `gorm:\"size:255;not null;unique\"` \r\n ID uint `gorm:\"primaryKey\"` \r\n CreatedAt time.Time \r\n UpdatedAt time.Time \r\n DeletedAt gorm.DeletedAt `gorm:\"index\"` \r\n}<\/pre>\nYou can embed your custom structs in other structs using the embedded tag.<\/p>\n
type Human struct { \r\n Age int `gorm:\"primaryKey\"` \r\n Name string `gorm:\"size:255;not null;unique\"` \r\n} \r\ntype Beings struct { \r\n human Human `gorm:\"embedded\"` \r\n gorm.Model \r\n}<\/pre>\nThe
Beings<\/code> struct eventually evaluates to theEvaluate<\/code> struct below on migration.<\/p>\ntype Evaluate struct { \r\n Age int `gorm:\"primaryKey\"` \r\n Name string `gorm:\"size:255;not null;unique\"` \r\n ID uint `gorm:\"primaryKey\"` \r\n CreatedAt time.Time \r\n UpdatedAt time.Time \r\n DeletedAt gorm.DeletedAt `gorm:\"index\"` \r\n}<\/pre>\nGORM supports most features you\u2019ll want in an ORM, including functionality to set field permissions for more data control. Here\u2019s the complete reference from the GORM documentation<\/a>.<\/p>\n
type User struct { \r\n Name string `gorm:\"<-:create\"` \/\/ allow read and create \r\n Name string `gorm:\"<-:update\"` \/\/ allow read and update \r\n Name string `gorm:\"<-\"` \/\/ allow read and write (create and update) \r\n Name string `gorm:\"<-:false\"` \/\/ allow read, disable write permission \r\n Name string `gorm:\"->\"` \/\/ readonly (disable write permission \r\n \/\/unless it configured) \r\n Name string `gorm:\"->;<-:create\"` \/\/ allow read and create \r\n Name string `gorm:\"->:false;<-:create\"` \/\/ create only (disabled read \r\n \/\/from db) \r\n Name string `gorm:\"-\"` \/\/ ignore this field when writing and \r\n \/\/reading with struct \r\n Name string `gorm:\"-:all\"` \/\/ ignore this field when writing, \r\n \/\/reading and migrating with struct \r\n Name string `gorm:\"-:migration\"` \/\/ ignore this field when migrate \r\n \/\/with struct \r\n}<\/pre>\nSetting up Automigrations With GORM<\/h2>\n
Automigrations are one of the significant benefits of using ORMs, making it easy to add data entries. You can migrate instances of the struct model using the
AutoMigrate<\/code> method of the database instance.<\/p>\nerr = db.AutoMigrate(&Human{}) \r\nif err != nil { \r\n panic(\"migration failure\") \r\n}<\/pre>\nBy referencing the struct here, you\u2019ve set the Human struct for auto migration. The
AutoMigrate<\/code> method returns an error that you can handle if any.<\/p>\nConventionally, you\u2019ll use the function that returns your database instance to set up auto migrations and return the database instance.<\/p>\n
func database(DNS string) *gorm.DB { \r\n var db *gorm.DB \r\n db, err = gorm.Open(mysql.Open(DNS), &gorm.Config{}) \r\n if err != nil { \r\n panic(\"failed to connect database\") \r\n } \r\n err = db.AutoMigrate(&Human{}) \r\n if err != nil { \r\n return \r\n } \r\n return db \r\n }<\/pre>\nInserting Into a Database With GORM<\/h2>\n
The Create method accepts a reference to the struct initialization and inserts a new row to the database.<\/p>\n
person := Human{ \r\n Model: gorm.Model{}, \r\n Age: 18, \r\n Name: \"James Dough\", \r\n} \r\ndb.Create(&person)<\/pre>\nDepending on your operation; you can use many methods and functions on the Create method.<\/p>\n
Using the RowsAffected method on the Create method returns the number of Rows affected.<\/p>\n
rows := db.Create(&person).RowsAffected \r\nlog.Println(rows) <\/pre>\n
There are many other methods you can use with the
Create<\/code> method. In figure1 you can see a few of them.<\/p>\n![\"Graphical](\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/2022\/11\/graphical-user-interface-text-description-automa-1.png\")
<\/p>\nFigure 1 – Additional methods you can use with the Create method.<\/p>\n
Reading From a Database With GORM<\/h2>\n
Reading from a database with GORM is easy, and there are many methods you can use based on the operation.<\/p>\n
The read methods decode the query result into an instantiated struct.<\/p>\n
type person := new(Human)<\/pre>\n
The
Take<\/code> ,First<\/code> , andLast<\/code> methods return a single row. TheTake<\/code> method returns a random row that meets the criteria; theFirst<\/code> method returns the first entry that satisfies the query ordered primary key, and theLast<\/code> method returns the last entry that satisfies the query ordered primary key.<\/p>\ndb.Take(&person, \"John\") \r\ndb.First(&person, \"Jane\") \r\ndb.Last(&person, \"Dough\")<\/pre>\n
Using the
Find<\/code> method, you can also query for all the rows that meet the criteria.<\/p>\ndb.Find(&person, \"James\")<\/pre>\n
You can use the Where method with any of the
Find<\/code> ,First<\/code> ,Take<\/code> andLast<\/code> methods for complex queries.<\/p>\ndb.Where(\"Name = ? AND Age >= ?\", \"James\", \"22\").Find(&person)<\/pre>\n
Updating Database Entries With GORM<\/h2>\n
Update operations are easy and quite similar to other GORM operations, and all the methods and functions on read operations are also available.<\/p>\n
You can update a column using the
Update<\/code> method after referencing the struct table you want to update using theModel<\/code> method.<\/p>\nvar rows = db.Model(&Human{}).Update(\"Name\", \"Junior\").RowsAffected<\/pre>\nAfter a successful update operation, the rows variable will store the number of rows affected by the operation.<\/p>\n
You can also update multiple columns using the
Updates<\/code> method. TheUpdates<\/code> method takes in an initialized struct.<\/p>\nperson := Human{ \r\n Name: \"James\", \r\n Age: 18, \r\n} \r\ndb.Model(&person).Updates(person)<\/pre>\nLike the read operation, you can use the Where method with any update methods for complex operations.<\/p>\n
db.Model(&Human{}).Where(\"Age = ?\", 19).Update(\"Name\", \"Junior\")<\/pre>\nDeleting From a Database With GORM<\/h2>\n
You can use the Delete method to delete rows in a database. The
Delete<\/code> method takes in the instantiated struct type.<\/p>\ndb.Delete(&person)<\/pre>\n
You can also use the Delete method on the Where method for complex operations<\/p>\n
db.Where(\"name = ?\", \"John\").Delete(&person)<\/pre>\n
If you need to delete specific columns, You can drop a column using the
DropColumn<\/code> method of the Migrator method of the database instance.<\/p>\nerr := db.Migrator().DropColumn(&Human{}, \"Name\") \r\nif err != nil { \r\nreturn \r\n}<\/pre>\nHere you dropped the Name column of the Human table. The
DropColumn<\/code> method returns an error if there\u2019s any.<\/p>\nThe GORM SQL Builder<\/h2>\n
- You have experience working with SQL and SQL databases.<\/li>\n<\/ul>\n