Getting Started ​

Installation ​

To easily install the latest version of queryx, open your terminal and run the following command:

curl -sf https://raw.githubusercontent.com/swiftcarrot/queryx/main/install.sh | sh

curl -sf https://raw.githubusercontent.com/swiftcarrot/queryx/main/install.sh | sh

You can also build queryx from the source following the instructions here.

After installation, run the following command to validate queryx:

queryx version

queryx version

This command will output current installed queryx version if installed successfully.

Create your first schema ​

Queryx uses HCL format for schema defintion. Create the following sample schema.hcl in the current directory:

database "db" {
  adapter = "postgresql"

  config "development" {
    url = "postgresql://postgres:postgres@localhost:5432/blog_development?sslmode=disable"
  }

  model "Post" {
    column "title" {
      type = string
    }
    column "content" {
      type = text
    }
  }
}

database "db" {
  adapter = "postgresql"

  config "development" {
    url = "postgresql://postgres:postgres@localhost:5432/blog_development?sslmode=disable"
  }

  model "Post" {
    column "title" {
      type = string
    }
    column "content" {
      type = text
    }
  }
}

In this sample schema, we create a queryx database db, which consists of a model Post. Post model contains two fields, title as string type and content as text type. string and text are both predefined queryx types. The db database is defined as the postgresql adapter and the connection config url to the PostgreSQL database is defined through the config block.

Queryx also support MySQL and SQLite databases by changing the adapter attribute and config in database block.

Example for MySQL database:

database "db" {
  adapter = "mysql"

  config "development" {
    url = "mysql://root:@127.0.0.1:3306/blog_development"
  }
}

database "db" {
  adapter = "mysql"

  config "development" {
    url = "mysql://root:@127.0.0.1:3306/blog_development"
  }
}

Example for SQLite database:

database "db" {
  adapter = "sqlite"

  config "development" {
    url = "sqlite:blog_development.sqlite3"
  }
}

database "db" {
  adapter = "sqlite"

  config "development" {
    url = "sqlite:blog_development.sqlite3"
  }
}

Run the following command to automatically format the schema file:

queryx format

queryx format

Database managment ​

Run the following command to create the PostgreSQL database, by default, queryx with read from the development config block. It can be changed by setting the QUERYX_ENV environment variable.

queryx db:create

queryx db:create

which works the same as

QUERYX_ENV=development queryx db:create

QUERYX_ENV=development queryx db:create

Once the database is created, queryx can automatically migrate the database to the schema defined in schema.hcl:

queryx db:migrate

queryx db:migrate

The db:migrate command will initially compare the current state of database to the schema defined in schema.hcl. It will generate migrations files in SQL format in the db/migrations directory if there are any differences. It will proceed to execute the generated migration files to update the database in line with the schema defined in schema.hcl.

Code generation ​

In the sample schema.hcl, we can define multiple generators as:

database "db" {
  generator "client-golang" {}

  generator "client-typescript" {}
}

database "db" {
  generator "client-golang" {}

  generator "client-typescript" {}
}

To generate ORM client methods, simply execute the following command:

queryx generate

queryx generate

Queryx will generate both Golang and TypeScript codes in db directory based on the database name. We will cover the basics of CRUD operations (create, read, update, delete) using the queryx generated code. For a more detailed breakdown of the generated methods, please refer to the ORM API section.

Dependency Installation ​

Queryx generates codes only depending on third-party database driver implementation.

go get ./...

go get ./...

To begin, we instantiate a client object, which serves as the entry point for all interactions with the database.

c, err := db.NewClient()

c, err := db.NewClient()

Queryx supports changing database data (insert, update and delete) through a change object. For each model defined in the schema, queryx generates a corresponding change object with setting methods for each field in the model. This ensures the correctness of query and makes it easy to modify data in the database safely.

Create a new post:

newPost := c.ChangePost().SetTitle("post title").SetContent("post content")
post, err := c.QueryPost().Create(newPost)

newPost := c.ChangePost().SetTitle("post title").SetContent("post content")
post, err := c.QueryPost().Create(newPost)

Queryx also supports the Active Record pattern, which allows Update() or Delete() call on the returned queryx record.

Update the post:

err := post.Update(c.ChangePost().SetTitle("new post title"))

err := post.Update(c.ChangePost().SetTitle("new post title"))

Delete the post:

err := post.Delete()

err := post.Delete()

Queryx also supports update and delete by query.

Update all posts by title:

updated, err := c.QueryPost().Where(c.PostTitle.EQ("post title")).UpdateAll(c.ChangePost().SetTitle("new post title"))

updated, err := c.QueryPost().Where(c.PostTitle.EQ("post title")).UpdateAll(c.ChangePost().SetTitle("new post title"))

Delete all posts by title:

deleted, err := c.QueryPost().Where(c.PostTitle.EQ("post title")).DeleteAll()

deleted, err := c.QueryPost().Where(c.PostTitle.EQ("post title")).DeleteAll()

To retrieve data from the database in Queryx using the primary key:

post, err := c.QueryPost().Find(1)

post, err := c.QueryPost().Find(1)

Retrieve all posts by title:

posts, err := c.QueryPost().Where(c.PostTitle.EQ("post title")).All()

posts, err := c.QueryPost().Where(c.PostTitle.EQ("post title")).All()

Retrieve the first post from query:

post, err := c.QueryPost().Where(c.PostTitle.EQ("post title")).First()

post, err := c.QueryPost().Where(c.PostTitle.EQ("post title")).First()