{"id":14920517,"url":"https://github.com/scylladb/gocqlx","last_synced_at":"2025-05-13T19:11:22.139Z","repository":{"id":23159804,"uuid":"97840838","full_name":"scylladb/gocqlx","owner":"scylladb","description":"All-In-One: CQL query builder, ORM and migration tool","archived":false,"fork":false,"pushed_at":"2025-05-07T11:01:34.000Z","size":417,"stargazers_count":960,"open_issues_count":29,"forks_count":124,"subscribers_count":20,"default_branch":"master","last_synced_at":"2025-05-07T12:20:07.445Z","etag":null,"topics":["cassandra","cql","gocql","golang","migration","orm","query-builder","scylla"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/scylladb.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2017-07-20T13:50:33.000Z","updated_at":"2025-05-07T04:42:38.000Z","dependencies_parsed_at":"2023-02-10T04:30:22.325Z","dependency_job_id":"ce7c94b2-fbde-4687-9567-c56e9c5fc958","html_url":"https://github.com/scylladb/gocqlx","commit_stats":{"total_commits":240,"total_committers":40,"mean_commits":6.0,"dds":0.3125,"last_synced_commit":"dec046bd85e6a33abcc66eeb5dc61ae71c9bb132"},"previous_names":["mmatczuk/gocqlx"],"tags_count":27,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scylladb%2Fgocqlx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scylladb%2Fgocqlx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scylladb%2Fgocqlx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scylladb%2Fgocqlx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/scylladb","download_url":"https://codeload.github.com/scylladb/gocqlx/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254010824,"owners_count":21998993,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cassandra","cql","gocql","golang","migration","orm","query-builder","scylla"],"created_at":"2024-09-23T02:01:15.784Z","updated_at":"2025-05-13T19:11:22.090Z","avatar_url":"https://github.com/scylladb.png","language":"Go","funding_links":[],"categories":["Drivers and Libraries","Go"],"sub_categories":["Go"],"readme":"# 🚀 GocqlX [![GoDoc](https://pkg.go.dev/badge/github.com/scylladb/gocqlx/v3.svg)](https://pkg.go.dev/github.com/scylladb/gocqlx/v3) [![Go Report Card](https://goreportcard.com/badge/github.com/scylladb/gocqlx)](https://goreportcard.com/report/github.com/scylladb/gocqlx) [![Build Status](https://travis-ci.org/scylladb/gocqlx.svg?branch=master)](https://travis-ci.org/scylladb/gocqlx)\n\nGocqlX makes working with Scylla easy and less error-prone.\nIt’s inspired by [Sqlx](https://github.com/jmoiron/sqlx), a tool for working with SQL databases, but it goes beyond what Sqlx provides.\n\n## Features\n\n* Binding query parameters from struct fields, map, or both\n* Scanning query results into structs based on field names\n* Convenient functions for common tasks such as loading a single row into a struct or all rows into a slice (list) of structs\n* Making any struct a UDT without implementing marshalling functions\n* GocqlX is fast. Its performance is comparable to raw driver. You can find some benchmarks [here](#performance).\n\nSubpackages provide additional functionality:\n\n* CQL query builder ([package qb](https://github.com/scylladb/gocqlx/blob/master/qb))\n* CRUD operations based on table model ([package table](https://github.com/scylladb/gocqlx/blob/master/table))\n* Database migrations ([package migrate](https://github.com/scylladb/gocqlx/blob/master/migrate))\n\n## Installation\n\n```bash\ngit clone git@github.com:scylladb/gocqlx.git\ncd gocqlx/cmd/schemagen/\ngo install .\n```\n\n## Getting started\n\nWrap gocql Session:\n\n```go\n// Create gocql cluster.\ncluster := gocql.NewCluster(hosts...)\n// Wrap session on creation, gocqlx session embeds gocql.Session pointer. \nsession, err := gocqlx.WrapSession(cluster.CreateSession())\nif err != nil {\n\tt.Fatal(err)\n}\n```\n\nSpecify table model:\n\n```go\n// metadata specifies table name and columns it must be in sync with schema.\nvar personMetadata = table.Metadata{\n\tName:    \"person\",\n\tColumns: []string{\"first_name\", \"last_name\", \"email\"},\n\tPartKey: []string{\"first_name\"},\n\tSortKey: []string{\"last_name\"},\n}\n\n// personTable allows for simple CRUD operations based on personMetadata.\nvar personTable = table.New(personMetadata)\n\n// Person represents a row in person table.\n// Field names are converted to snake case by default, no need to add special tags.\n// A field will not be persisted by adding the `db:\"-\"` tag or making it unexported.\ntype Person struct {\n\tFirstName string\n\tLastName  string\n\tEmail     []string\n\tHairColor string `db:\"-\"`  // exported and skipped\n\teyeColor  string           // unexported also skipped\n}\n```\n\nBind data from a struct and insert a row:\n\n```go\np := Person{\n\t\"Michał\",\n\t\"Matczuk\",\n\t[]string{\"michal@scylladb.com\"},\n\t\"red\",    // not persisted\n\t\"hazel\"   // not persisted\n}\nq := session.Query(personTable.Insert()).BindStruct(p)\nif err := q.ExecRelease(); err != nil {\n\tt.Fatal(err)\n}\n```\n\nLoad a single row to a struct:\n\n```go\np := Person{\n\t\"Michał\",\n\t\"Matczuk\",\n\tnil, // no email\n}\nq := session.Query(personTable.Get()).BindStruct(p)\nif err := q.GetRelease(\u0026p); err != nil {\n\tt.Fatal(err)\n}\nt.Log(p)\n// stdout: {Michał Matczuk [michal@scylladb.com]}\n```\n\nLoad all rows in to a slice:\n\n```go\nvar people []Person\nq := session.Query(personTable.Select()).BindMap(qb.M{\"first_name\": \"Michał\"})\nif err := q.SelectRelease(\u0026people); err != nil {\n\tt.Fatal(err)\n}\nt.Log(people)\n// stdout: [{Michał Matczuk [michal@scylladb.com]}]\n```\n\n## Generating table metadata with schemagen\n\nInstallation\n\n```bash\ngo get -u \"github.com/scylladb/gocqlx/v3/cmd/schemagen\"\n```\n\nUsage:\n```bash\nschemagen [flags]\n\nFlags:\n  -cluster string\n    \ta comma-separated list of host:port tuples (default \"127.0.0.1\")\n  -keyspace string\n    \tkeyspace to inspect (required)\n  -output string\n    \tthe name of the folder to output to (default \"models\")\n  -pkgname string\n    \tthe name you wish to assign to your generated package (default \"models\") \n```\n\nExample:\n\nRunning the following command for `examples` keyspace: \n```bash\nschemagen -cluster=\"127.0.0.1:9042\" -keyspace=\"examples\" -output=\"models\" -pkgname=\"models\"\n```\n\nGenerates `models/models.go` as follows:\n```go\n// Code generated by \"gocqlx/cmd/schemagen\"; DO NOT EDIT.\n\npackage models\n\nimport \"github.com/scylladb/gocqlx/v3/table\"\n\n// Table models.\nvar (\n\tPlaylists = table.New(table.Metadata{\n\t\tName: \"playlists\",\n\t\tColumns: []string{\n\t\t\t\"album\",\n\t\t\t\"artist\",\n\t\t\t\"id\",\n\t\t\t\"song_id\",\n\t\t\t\"title\",\n\t\t},\n\t\tPartKey: []string{\n\t\t\t\"id\",\n\t\t},\n\t\tSortKey: []string{\n\t\t\t\"title\",\n\t\t\t\"album\",\n\t\t\t\"artist\",\n\t\t},\n\t})\n\n\tSongs = table.New(table.Metadata{\n\t\tName: \"songs\",\n\t\tColumns: []string{\n\t\t\t\"album\",\n\t\t\t\"artist\",\n\t\t\t\"data\",\n\t\t\t\"id\",\n\t\t\t\"tags\",\n\t\t\t\"title\",\n\t\t},\n\t\tPartKey: []string{\n\t\t\t\"id\",\n\t\t},\n\t\tSortKey: []string{},\n\t})\n)\n```\n\n## Examples\n\nYou can find lots of examples in [example_test.go](https://github.com/scylladb/gocqlx/blob/master/example_test.go).\n\nGo and run them locally:\n\n```bash\nmake run-scylla\nmake run-examples\n```\n\n## Training\n\nThe course [Using Scylla Drivers](https://university.scylladb.com/courses/using-scylla-drivers) in Scylla University explains how to use drivers in different languages to interact with a Scylla cluster. The lesson, [Golang and Scylla Part 3 - GoCQLX](https://university.scylladb.com/courses/using-scylla-drivers/lessons/golang-and-scylla-part-3-gocqlx/), goes over a sample application that, using GoCQLX, interacts with a three-node Scylla cluster. It connects to a Scylla cluster, displays the contents of a table, inserts and deletes data, and shows the contents of the table after each action. [Scylla University](https://university.scylladb.com/) includes other training material and online courses which will help you become a Scylla NoSQL database expert.\n\n## Performance\n\nGocqlX performance is comparable to the raw `gocql` driver.\nBelow benchmark results running on my laptop.\n\n```\nBenchmarkBaseGocqlInsert            2392            427491 ns/op            7804 B/op         39 allocs/op\nBenchmarkGocqlxInsert               2479            435995 ns/op            7803 B/op         39 allocs/op\nBenchmarkBaseGocqlGet               2853            452384 ns/op            7309 B/op         35 allocs/op\nBenchmarkGocqlxGet                  2706            442645 ns/op            7646 B/op         38 allocs/op\nBenchmarkBaseGocqlSelect             747           1664365 ns/op           49415 B/op        927 allocs/op\nBenchmarkGocqlxSelect                667           1877859 ns/op           42521 B/op        932 allocs/op\n```\n\nSee the benchmark in [benchmark_test.go](https://github.com/scylladb/gocqlx/blob/master/benchmark_test.go).\n\n## License\n\nCopyright (C) 2017 ScyllaDB\n\nThis project is distributed under the Apache 2.0 license. See the [LICENSE](https://github.com/scylladb/gocqlx/blob/master/LICENSE) file for details.\nIt contains software from:\n\n* [gocql project](https://github.com/gocql/gocql), licensed under the BSD license\n* [sqlx project](https://github.com/jmoiron/sqlx), licensed under the MIT license\n\nApache®, Apache Cassandra® are either registered trademarks or trademarks of \nthe Apache Software Foundation in the United States and/or other countries. \nNo endorsement by The Apache Software Foundation is implied by the use of these marks.\n\nGitHub star is always appreciated!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fscylladb%2Fgocqlx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fscylladb%2Fgocqlx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fscylladb%2Fgocqlx/lists"}