Google Git
Sign in
apache / cassandra-gocql-driver / refs/tags/v1.5.0
tage2d9a011e665f45b0cbf2d587419c96a62ff8e84
taggerMartin Sucha <martin.sucha@kiwi.com>Mon Jun 12 17:29:34 2023 +0200
objectc27e8098fa3e9e2d59e114a63e8d09f3729fc472 
v1.5.0

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256

2023-06-12:
Switching signing key used for github.com/gocql/gocql tags (since v1.5.0)
from GPG key ID: E0C5EC9218CB255D
to SSH key with the following fingerprint:
SHA256:TcKxeY58a0HRfycY4dCuqMF23FrNyEcclOdVzUI9BBI
You can verify it with
martin.sucha@kiwi.com namespaces="git" ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIN8Cnim2/FWQqDJmhidmXK/9VNO64rLfVJrvZqKaLqUl
in your gpg.ssh.allowedSignersFile
-----BEGIN PGP SIGNATURE-----

iQIzBAEBCAAdFiEEW7CgRMsA2lq5yf6v4MXskhjLJV0FAmSHOcYACgkQ4MXskhjL
JV2IXhAAye6kQhLwiiCag6bHUKIbKxM0TQHiOZf7aRKYlU2s0aWcsOXMeS6S9pvC
cJqmjBdhDZx569bPrgjAy9+jMoe+rNBR5Cr8dcJUk31cKUTjm/7PsKfiCxfDrbnm
ARDY2Z3vdGJC39mvBjG16UurzAPlRnP66jzyWYaXBiFBJJGWkP1+m+PNG4eF9ggo
6W89MEeK6ZpLCxI0URq2RyB5JEgGkr1Gb9UB4/70euiTjUxeRjS+RHjosGREC0nG
MxfpHND/Z+gOhHXCYt87zrF7N7JWIFU3+4vOj/th8MvMGRYaDzOAKT7MQmc/wc3A
drBA5G/adltjNw9aWTRQGNV69jhaoaIkZfv4fy+AvPDz41iGOQD9Nulw8ujkocUC
8zr4OxPhc0LIX1LtqwA2ahYfJABXnC7ObzqZLyXsE0sW5yvWpPNlF+Bj/slAdO+6
d+4uxGs8dd3N/bOihFL2XZoeOStF6ehT5KIFsbr885FUueu6iRgZYPalfv/aWe95
VIh97ikNsfgFH3mO0ZTGP9tnjSCbGIwG2Oh3+0dj5J4tZU1ihJRKiHJJNQirG1xK
jMdu9EXOEPFK4CPwaXZgHpTy38cFF2MOxHbsrxErCuWJY8JxRpqlJeOyx0F+eTR4
NGQSrMKvxfKd/F192UznSUSfflRTrQT7stUOhZk3Lc4YcCSiDEk=
=em6i
-----END PGP SIGNATURE-----
commitc27e8098fa3e9e2d59e114a63e8d09f3729fc472[log] [tgz]
authorMartin Sucha <martin.sucha@kiwi.com>Mon Jun 12 13:29:01 2023 +0200
committerMartin Sucha <martin.sucha@kiwi.com>Mon Jun 12 13:29:01 2023 +0200
tree912bfbe5c39f853d83f33d5e2dbaa743d41723d9
parent86b5752ed989e8bd1f0e551987a21480000ddabe [diff]
Mention version advertising in documentation
1 file changed
tree: 912bfbe5c39f853d83f33d5e2dbaa743d41723d9
  1. .github/
  2. internal/
  3. lz4/
  4. testdata/
  5. .gitignore
  6. address_translators.go
  7. address_translators_test.go
  8. AUTHORS
  9. batch_test.go
  10. cass1batch_test.go
  11. cassandra_test.go
  12. CHANGELOG.md
  13. cluster.go
  14. cluster_test.go
  15. common_test.go
  16. compressor.go
  17. compressor_test.go
  18. conn.go
  19. conn_test.go
  20. connectionpool.go
  21. connectionpool_test.go
  22. CONTRIBUTING.md
  23. control.go
  24. control_ccm_test.go
  25. control_test.go
  26. cqltypes.go
  27. debug_off.go
  28. debug_on.go
  29. dial.go
  30. doc.go
  31. errors.go
  32. errors_test.go
  33. events.go
  34. events_ccm_test.go
  35. events_test.go
  36. example_batch_test.go
  37. example_dynamic_columns_test.go
  38. example_lwt_batch_test.go
  39. example_lwt_test.go
  40. example_marshaler_test.go
  41. example_nulls_test.go
  42. example_paging_test.go
  43. example_set_test.go
  44. example_test.go
  45. example_udt_map_test.go
  46. example_udt_marshaler_test.go
  47. example_udt_struct_test.go
  48. example_udt_unmarshaler_test.go
  49. filters.go
  50. filters_test.go
  51. frame.go
  52. frame_test.go
  53. framer_bench_test.go
  54. fuzz.go
  55. go.mod
  56. go.sum
  57. helpers.go
  58. helpers_test.go
  59. host_source.go
  60. host_source_gen.go
  61. host_source_test.go
  62. install_test_deps.sh
  63. integration.sh
  64. integration_test.go
  65. LICENSE
  66. logger.go
  67. marshal.go
  68. marshal_test.go
  69. metadata.go
  70. metadata_test.go
  71. policies.go
  72. policies_test.go
  73. prepared_cache.go
  74. query_executor.go
  75. README.md
  76. ring.go
  77. ring_test.go
  78. session.go
  79. session_connect_test.go
  80. session_test.go
  81. session_unit_test.go
  82. stress_test.go
  83. token.go
  84. token_test.go
  85. topology.go
  86. topology_test.go
  87. tuple_test.go
  88. udt_test.go
  89. uuid.go
  90. uuid_test.go
  91. version.go
  92. wiki_test.go
README.md

gocql

Join the chat at https://gitter.im/gocql/gocql go build GoDoc

Package gocql implements a fast and robust Cassandra client for the Go programming language.

Project Website: https://gocql.github.io/
API documentation: https://godoc.org/github.com/gocql/gocql
Discussions: https://groups.google.com/forum/#!forum/gocql

Supported Versions

The following matrix shows the versions of Go and Cassandra that are tested with the integration test suite as part of the CI build:

Go/Cassandra4.0.x4.1.x
1.19yesyes
1.20yesyes

Gocql has been tested in production against many versions of Cassandra. Due to limits in our CI setup we only test against the latest 2 GA releases.

Sunsetting Model

In general, the gocql team will focus on supporting the current and previous versions of Go. gocql may still work with older versions of Go, but official support for these versions will have been sunset.

Installation

go get github.com/gocql/gocql

Features

  • Modern Cassandra client using the native transport
  • Automatic type conversions between Cassandra and Go
    • Support for all common types including sets, lists and maps
    • Custom types can implement a Marshaler and Unmarshaler interface
    • Strict type conversions without any loss of precision
    • Built-In support for UUIDs (version 1 and 4)
  • Support for logged, unlogged and counter batches
  • Cluster management
    • Automatic reconnect on connection failures with exponential falloff
    • Round robin distribution of queries to different hosts
    • Round robin distribution of queries to different connections on a host
    • Each connection can execute up to n concurrent queries (whereby n is the limit set by the protocol version the client chooses to use)
    • Optional automatic discovery of nodes
    • Policy based connection pool with token aware and round-robin policy implementations
  • Support for password authentication
  • Iteration over paged results with configurable page size
  • Support for TLS/SSL
  • Optional frame compression (using snappy)
  • Automatic query preparation
  • Support for query tracing
  • Support for Cassandra 2.1+ binary protocol version 3
    • Support for up to 32768 streams
    • Support for tuple types
    • Support for client side timestamps by default
    • Support for UDTs via a custom marshaller or struct tags
  • Support for Cassandra 3.0+ binary protocol version 4
  • An API to access the schema metadata of a given keyspace

Performance

While the driver strives to be highly performant, there are cases where it is difficult to test and verify. The driver is built with maintainability and code readability in mind first and then performance and features, as such every now and then performance may degrade, if this occurs please report and issue and it will be looked at and remedied. The only time the driver copies data from its read buffer is when it Unmarshal's data into supplied types.

Some tips for getting more performance from the driver:

  • Use the TokenAware policy
  • Use many goroutines when doing inserts, the driver is asynchronous but provides a synchronous API, it can execute many queries concurrently
  • Tune query page size
  • Reading data from the network to unmarshal will incur a large amount of allocations, this can adversely affect the garbage collector, tune GOGC
  • Close iterators after use to recycle byte buffers

Important Default Keyspace Changes

gocql no longer supports executing “use ” statements to simplify the library. The user still has the ability to define the default keyspace for connections but now the keyspace can only be defined before a session is created. Queries can still access keyspaces by indicating the keyspace in the query:

SELECT * FROM example2.table;

Example of correct usage:

	cluster := gocql.NewCluster("192.168.1.1", "192.168.1.2", "192.168.1.3")
	cluster.Keyspace = "example"
	...
	session, err := cluster.CreateSession()

Example of incorrect usage:

	cluster := gocql.NewCluster("192.168.1.1", "192.168.1.2", "192.168.1.3")
	cluster.Keyspace = "example"
	...
	session, err := cluster.CreateSession()

	if err = session.Query("use example2").Exec(); err != nil {
		log.Fatal(err)
	}

This will result in an err being returned from the session.Query line as the user is trying to execute a “use” statement.

Example

See package documentation.

Data Binding

There are various ways to bind application level data structures to CQL statements:

  • You can write the data binding by hand, as outlined in the Tweet example. This provides you with the greatest flexibility, but it does mean that you need to keep your application code in sync with your Cassandra schema.
  • You can dynamically marshal an entire query result into an []map[string]interface{} using the SliceMap() API. This returns a slice of row maps keyed by CQL column names. This method requires no special interaction with the gocql API, but it does require your application to be able to deal with a key value view of your data.
  • As a refinement on the SliceMap() API you can also call MapScan() which returns map[string]interface{} instances in a row by row fashion.
  • The Bind() API provides a client app with a low level mechanism to introspect query meta data and extract appropriate field values from application level data structures.
  • The gocqlx package is an idiomatic extension to gocql that provides usability features. With gocqlx you can bind the query parameters from maps and structs, use named query parameters (:identifier) and scan the query results into structs and slices. It comes with a fluent and flexible CQL query builder that supports full CQL spec, including BATCH statements and custom functions.
  • Building on top of the gocql driver, cqlr adds the ability to auto-bind a CQL iterator to a struct or to bind a struct to an INSERT statement.
  • Another external project that layers on top of gocql is cqlc which generates gocql compliant code from your Cassandra schema so that you can write type safe CQL statements in Go with a natural query syntax.
  • gocassa is an external project that layers on top of gocql to provide convenient query building and data binding.
  • gocqltable provides an ORM-style convenience layer to make CRUD operations with gocql easier.

Ecosystem

The following community maintained tools are known to integrate with gocql:

  • gocqlx is a gocql extension that automates data binding, adds named queries support, provides flexible query builders and plays well with gocql.
  • journey is a migration tool with Cassandra support.
  • negronicql is gocql middleware for Negroni.
  • cqlr adds the ability to auto-bind a CQL iterator to a struct or to bind a struct to an INSERT statement.
  • cqlc generates gocql compliant code from your Cassandra schema so that you can write type safe CQL statements in Go with a natural query syntax.
  • gocassa provides query building, adds data binding, and provides easy-to-use “recipe” tables for common query use-cases.
  • gocqltable is a wrapper around gocql that aims to simplify common operations.
  • gockle provides simple, mockable interfaces that wrap gocql types
  • scylladb is a fast Apache Cassandra-compatible NoSQL database
  • go-cql-driver is an CQL driver conforming to the built-in database/sql interface. It is good for simple use cases where the database/sql interface is wanted. The CQL driver is a wrapper around this project.

Other Projects

  • gocqldriver is the predecessor of gocql based on Go‘s database/sql package. This project isn’t maintained anymore, because Cassandra wasn't a good fit for the traditional database/sql API. Use this package instead.

SEO

For some reason, when you Google golang cassandra, this project doesn‘t feature very highly in the result list. But if you Google go cassandra, then we’re a bit higher up the list. So this is note to try to convince Google that golang is an alias for Go.

License

Copyright (c) 2012-2016 The gocql Authors. All rights reserved. Use of this source code is governed by a BSD-style license that can be found in the LICENSE file.