README.md
1# sessions
2
3[](https://godoc.org/github.com/gorilla/sessions) [](https://travis-ci.org/gorilla/sessions)
4[](https://sourcegraph.com/github.com/gorilla/sessions?badge)
5
6gorilla/sessions provides cookie and filesystem sessions and infrastructure for
7custom session backends.
8
9The key features are:
10
11- Simple API: use it as an easy way to set signed (and optionally
12 encrypted) cookies.
13- Built-in backends to store sessions in cookies or the filesystem.
14- Flash messages: session values that last until read.
15- Convenient way to switch session persistency (aka "remember me") and set
16 other attributes.
17- Mechanism to rotate authentication and encryption keys.
18- Multiple sessions per request, even using different backends.
19- Interfaces and infrastructure for custom session backends: sessions from
20 different stores can be retrieved and batch-saved using a common API.
21
22Let's start with an example that shows the sessions API in a nutshell:
23
24```go
25 import (
26 "net/http"
27 "github.com/gorilla/sessions"
28 )
29
30 // Note: Don't store your key in your source code. Pass it via an
31 // environmental variable, or flag (or both), and don't accidentally commit it
32 // alongside your code. Ensure your key is sufficiently random - i.e. use Go's
33 // crypto/rand or securecookie.GenerateRandomKey(32) and persist the result.
34 var store = sessions.NewCookieStore([]byte(os.Getenv("SESSION_KEY")))
35
36 func MyHandler(w http.ResponseWriter, r *http.Request) {
37 // Get a session. We're ignoring the error resulted from decoding an
38 // existing session: Get() always returns a session, even if empty.
39 session, _ := store.Get(r, "session-name")
40 // Set some session values.
41 session.Values["foo"] = "bar"
42 session.Values[42] = 43
43 // Save it before we write to the response/return from the handler.
44 err := session.Save(r, w)
45 if err != nil {
46 http.Error(w, err.Error(), http.StatusInternalServerError)
47 return
48 }
49 }
50```
51
52First we initialize a session store calling `NewCookieStore()` and passing a
53secret key used to authenticate the session. Inside the handler, we call
54`store.Get()` to retrieve an existing session or create a new one. Then we set
55some session values in session.Values, which is a `map[interface{}]interface{}`.
56And finally we call `session.Save()` to save the session in the response.
57
58More examples are available [on the Gorilla
59website](https://www.gorillatoolkit.org/pkg/sessions).
60
61## Store Implementations
62
63Other implementations of the `sessions.Store` interface:
64
65- [github.com/starJammer/gorilla-sessions-arangodb](https://github.com/starJammer/gorilla-sessions-arangodb) - ArangoDB
66- [github.com/yosssi/boltstore](https://github.com/yosssi/boltstore) - Bolt
67- [github.com/srinathgs/couchbasestore](https://github.com/srinathgs/couchbasestore) - Couchbase
68- [github.com/denizeren/dynamostore](https://github.com/denizeren/dynamostore) - Dynamodb on AWS
69- [github.com/savaki/dynastore](https://github.com/savaki/dynastore) - DynamoDB on AWS (Official AWS library)
70- [github.com/bradleypeabody/gorilla-sessions-memcache](https://github.com/bradleypeabody/gorilla-sessions-memcache) - Memcache
71- [github.com/dsoprea/go-appengine-sessioncascade](https://github.com/dsoprea/go-appengine-sessioncascade) - Memcache/Datastore/Context in AppEngine
72- [github.com/kidstuff/mongostore](https://github.com/kidstuff/mongostore) - MongoDB
73- [github.com/srinathgs/mysqlstore](https://github.com/srinathgs/mysqlstore) - MySQL
74- [github.com/EnumApps/clustersqlstore](https://github.com/EnumApps/clustersqlstore) - MySQL Cluster
75- [github.com/antonlindstrom/pgstore](https://github.com/antonlindstrom/pgstore) - PostgreSQL
76- [github.com/boj/redistore](https://github.com/boj/redistore) - Redis
77- [github.com/rbcervilla/redisstore](https://github.com/rbcervilla/redisstore) - Redis (Single, Sentinel, Cluster)
78- [github.com/boj/rethinkstore](https://github.com/boj/rethinkstore) - RethinkDB
79- [github.com/boj/riakstore](https://github.com/boj/riakstore) - Riak
80- [github.com/michaeljs1990/sqlitestore](https://github.com/michaeljs1990/sqlitestore) - SQLite
81- [github.com/wader/gormstore](https://github.com/wader/gormstore) - GORM (MySQL, PostgreSQL, SQLite)
82- [github.com/gernest/qlstore](https://github.com/gernest/qlstore) - ql
83- [github.com/quasoft/memstore](https://github.com/quasoft/memstore) - In-memory implementation for use in unit tests
84- [github.com/lafriks/xormstore](https://github.com/lafriks/xormstore) - XORM (MySQL, PostgreSQL, SQLite, Microsoft SQL Server, TiDB)
85- [github.com/GoogleCloudPlatform/firestore-gorilla-sessions](https://github.com/GoogleCloudPlatform/firestore-gorilla-sessions) - Cloud Firestore
86- [github.com/stephenafamo/crdbstore](https://github.com/stephenafamo/crdbstore) - CockroachDB
87
88## License
89
90BSD licensed. See the LICENSE file for details.
91
){kind=link}
){kind=link}
){kind=link}