github.com/fragmenta/query@v1.5.3/README.md (about)

     1  Query [![GoDoc](https://godoc.org/github.com/fragmenta/query?status.svg)](https://godoc.org/github.com/fragmenta/query) [![Go Report Card](https://goreportcard.com/badge/github.com/fragmenta/query)](https://goreportcard.com/report/github.com/fragmenta/query)
     2  =====
     3  
     4  
     5  
     6  Query lets you build SQL queries with chainable methods, and defer execution of SQL until you wish to extract a count or array of models. It will probably remain limited in scope - it is not intended to be a full ORM with strict mapping between db tables and structs, but a tool for querying the database with minimum friction, and performing CRUD operations linked to models; simplifying your use of SQL to store model data without getting in the way. Full or partial SQL queries are of course also available, and full control over sql. Model creation and column are delegated to the model, to avoid dictating any particular model structure or interface, however a suggested interface is given (see below and in tests), which makes usage painless in your handlers without any boilerplate.
     7  
     8  Supported databases: PostgreSQL, SQLite, MySQL. Bug fixes, suggestions and contributions welcome. 
     9  
    10  Usage
    11  =====
    12  
    13  
    14  ```go
    15  
    16  // In your app - open a database with options
    17  options := map[string]string{"adapter":"postgres","db":"query_test"}
    18  err := query.OpenDatabase(options)
    19  defer query.CloseDatabase()
    20  
    21  ...
    22  
    23  // In your model
    24  type Page struct {
    25  	ID			int64
    26  	CreatedAt   time.Time
    27  	UpdatedAt   time.Time
    28  	MyField	    myStruct
    29  	...
    30  	// Models can have any structure, any PK, here an int is used
    31  }
    32  
    33  // Normally you'd define helpers on your model class to load rows from the database
    34  // Query does not attempt to read data into columns with reflection or tags - 
    35  // that is left to your model so you can read as little or as much as you want from queries
    36  
    37  func Find(ID int64) (*Page, error) {
    38  	result, err := PagesQuery().Where("id=?", ID).FirstResult()
    39  	if err != nil {
    40  		return nil, err
    41  	}
    42  	return NewWithColumns(result), nil
    43  }
    44  
    45  func FindAll(q *Query) ([]*Page, error) {
    46  	results, err := q.Results()
    47  	if err != nil {
    48  		return nil, err
    49  	}
    50  
    51  	var models []*Page
    52  	for _, r := range results {
    53  		m := NewWithColumns(r)
    54  		models = append(models, m)
    55  	}
    56  
    57  	return models, nil
    58  }
    59  
    60  ...
    61  
    62  // In your handlers, construct queries and ask your models for the data
    63  
    64  // Find a simple model by id
    65  page, err := pages.Find(1)
    66  
    67  // Start querying the database using chained finders
    68  q := page.Query().Where("id IN (?,?)",4,5).Order("id desc").Limit(30)
    69  
    70  // Build up chains depending on other app logic, still no db requests
    71  if shouldRestrict {
    72  	q.Where("id > ?",3).OrWhere("keywords ~* ?","Page")
    73  }
    74  
    75  // Pass the relation around, until you are ready to retrieve models from the db
    76  results, err := pages.FindAll(q)
    77  ```
    78  
    79  What it does
    80  ============
    81  
    82  * Builds chainable queries including where, orwhere,group,having,order,limit,offset or plain sql
    83  * Allows any Primary Key/Table name or model fields (query.New lets you define this)
    84  * Allows Delete and Update operations on queried records, without creating objects
    85  * Defers SQL requests until full query is built and results requested
    86  * Provide helpers and return results for join ids, counts, single rows, or multiple rows
    87  
    88  
    89  What it doesn't do
    90  ==================
    91  
    92  * Attempt to read your models with reflection or struct tags
    93  * Require changes to your structs like tagging fields or specific fields
    94  * Cause problems with untagged fields, embedding, and fields not in the database
    95  * Provide hooks after/before update etc - your models are fully in charge of queries and their lifecycle
    96  
    97  
    98  
    99  Tests
   100  ==================
   101  
   102  All 3 databases supported have a test suite - to run the tests, create a database called query_test in mysql and psql then run go test at the root of the package. The sqlite tests are disabled by default because enabling them prohibits cross compilation, which is useful if you don't want to install go on your server but just upload a binary compiled locally. 
   103  
   104  ```bash
   105  go test
   106  ```
   107  
   108  
   109  
   110  Versions
   111  ==================
   112  
   113  - 1.0 - First version with interfaces and chainable finders
   114  - 1.0.1 - Updated to quote table names and fields, for use of reserved words, bug fix for mysql concurrency
   115  - 1.3 - updated API, now shifted instantiation to models instead, to avoid use of reflection
   116  - 1.3.1 - Fixed bugs in Mysql import, updated tests