Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 153 lines (107 sloc) 5.392 kB
f6619a1 @jed deprecated in favor of Amazon's own SDK.
authored
1 # This library has been deprecated.
2
3 Please use [Amazon's SDK for node.js](http://aws.amazon.com/sdkfornodejs/) instead.
4
222b409 @jed update README
authored
5 dynamo
f6619a1 @jed deprecated in favor of Amazon's own SDK.
authored
6 ------
de0d945 @jed first cut
authored
7
222b409 @jed update README
authored
8 [![Build Status](https://secure.travis-ci.org/jed/dynamo.png)][travis]
9
2bcfce3 @jed 0.2.0
authored
10 This is a [node.js][node] binding for the [DynamoDB][dynamo] service provided by [Amazon Web Services][aws]. It aims to abstract DynamoDB's implementation (request signing, session tokens, pagination), but not its tradeoffs/philosophy, by providing two APIs:
222b409 @jed update README
authored
11
37a239a @jed operations++ [ci skip]
authored
12 - a [low-level-but-ugly API][low-api] that supports all 13 DynamoDB operations as-is, and
2bcfce3 @jed 0.2.0
authored
13 - a [high-level API][high-api] that uses the above to provide a more natural interface.
de0d945 @jed first cut
authored
14
c3d31a0 @jed add example
authored
15 Example
16 -------
17
18 ```javascript
ef78ee4 @jed add region support. closes #17.
authored
19 var dynamo = require("dynamo")
20 , client = dynamo.createClient()
21 , db = client.get("us-east-1")
2bcfce3 @jed 0.2.0
authored
22
2f01aef @jed consolidate boilerplate to make example clearer.
authored
23 // High-level API
24
2bcfce3 @jed 0.2.0
authored
25 db.get("myTable")
829d3e7 @jed bad comma (h/t @evilhackerdude)
authored
26 .query({id: "123", date: {">=": new Date - 6000 }})
c4c59ba @mhart Updated query/get example to be slightly less verbose given new syntax
mhart authored
27 .get("id", "date", "name")
2bcfce3 @jed 0.2.0
authored
28 .reverse()
29 .fetch(function(err, data){ ... })
30
31 // Same call, using low-level API
32
33 db.query({
34 TableName: "myTable",
3a8f54b @jed formatting [ci skip]
authored
35 HashKeyValue: {S: "123"},
2bcfce3 @jed 0.2.0
authored
36 RangeKeyValue: {
37 ComparisonOperator: "LE",
3a8f54b @jed formatting [ci skip]
authored
38 AttributeValueList: [{N: "1329912311806"}]
2bcfce3 @jed 0.2.0
authored
39 },
40 AttributesToGet: ["id", "date", "name"],
41 ScanIndexForward: false
42 }, function(err, data){ ... })
c3d31a0 @jed add example
authored
43 ```
505312b @jed add details about callbacks and API
authored
44
2bcfce3 @jed 0.2.0
authored
45 Installation
46 ------------
505312b @jed add details about callbacks and API
authored
47
2bcfce3 @jed 0.2.0
authored
48 This library has no dependencies, and can be installed from [npm][npm]:
505312b @jed add details about callbacks and API
authored
49
2bcfce3 @jed 0.2.0
authored
50 npm install dynamo
505312b @jed add details about callbacks and API
authored
51
52 API
53 ---
54
2bcfce3 @jed 0.2.0
authored
55 ### dynamo = require("dynamo")
505312b @jed add details about callbacks and API
authored
56
2bcfce3 @jed 0.2.0
authored
57 This module exposes the `createClient` method, which is the preferred way to interact with dynamo.
505312b @jed add details about callbacks and API
authored
58
ef78ee4 @jed add region support. closes #17.
authored
59 ### client = dynamo.createClient([_credentials_])
505312b @jed add details about callbacks and API
authored
60
ef78ee4 @jed add region support. closes #17.
authored
61 Returns a client instance attached to the account specified by the given credentials. The credentials can be specified as an object with `accessKeyId` and `secretAccessKey` members such as the following:
505312b @jed add details about callbacks and API
authored
62
63 ```javascript
ef78ee4 @jed add region support. closes #17.
authored
64 client = dynamo.createClient({
505312b @jed add details about callbacks and API
authored
65 accessKeyId: "...", // your access key id
66 secretAccessKey: "..." // your secret access key
67 })
68 ```
69
70 You can also omit these credentials by storing them in the environment under which the current process is running, as `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`.
71
72 If neither of the above are provided, an error will be thrown.
73
ef78ee4 @jed add region support. closes #17.
authored
74 ### db = client.get(_regionName_)
75
76 Returns a database in the selected region. Currently, DynamoDB supports the following regions:
77
78 - `us-east-1`
79 - `us-west-1`
80 - `us-west-2`
81 - `ap-northeast-1`
82 - `ap-southeast-1`
83 - `eu-west-1`
84
2bcfce3 @jed 0.2.0
authored
85 Once you have a database instance, you can use either of the provided APIs:
ca7edcf @jed add table methods
authored
86
24ce7af @jed fix case
authored
87 ### [High-level API][high-api] (blue pill)
ca7edcf @jed add table methods
authored
88
2bcfce3 @jed 0.2.0
authored
89 The primary purpose of this library is to abstract away the often bizzare API design decisions of DynamoDB, into a composable and intuitive interface based on Database, Table, Item, Batch, Query, and Scan objects.
02e173b @jed add anchors
authored
90
2bcfce3 @jed 0.2.0
authored
91 See [the wiki][high-api] for more information.
02e173b @jed add anchors
authored
92
24ce7af @jed fix case
authored
93 ### [Low-level API][low-api] (red pill)
d0baf1f @jed explain low-level API
authored
94
2bcfce3 @jed 0.2.0
authored
95 All of the [original DynamoDB operations][api] are provided as methods on database instances. You won't need to use them unless you want to sacrifice a clean interdace for more control, and don't mind learning Amazon's JSON format.
d0baf1f @jed explain low-level API
authored
96
2bcfce3 @jed 0.2.0
authored
97 See [the wiki][low-api] for more information.
d0baf1f @jed explain low-level API
authored
98
a2b86b3 @jed add testing summary
authored
99 Testing
100 -------
101
e68521b @jed update testing info
authored
102 Testing for dynamo is handled using continuous integration against a real DynamoDB instance, under credentials limited to Travis CI.
a2b86b3 @jed add testing summary
authored
103
e68521b @jed update testing info
authored
104 If you'd like to run the test stuie with your own credentials, make sure they're set using the `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` environment variables, and then run the tests:
a2b86b3 @jed add testing summary
authored
105
106 npm test
107
711a9b1 @mlogan Support array-based schema specification. (See https://github.com/jed…
mlogan authored
108 The test suite creates three tables called `DYNAMO_TEST_TABLE_1`, `DYNAMO_TEST_TABLE_2`, and 'DYNAMO_TEST_TABLE_3` before the tests are run, and then deletes them once the tests are done. Note that you will need to delete them manually in the event that the tests fail.
e68521b @jed update testing info
authored
109
4e316cd @jed todos [ci skip]
authored
110 To do
111 -----
112
113 - Factor out tests into integration tests and unit tests
114 - Make all callbacks optional, returning an event emitter no callback given
115 - Add method to specify Limit and ExclusiveStartKey
116
4d3f160 @jed credits
authored
117 Credits
118 -------
119
e68521b @jed update testing info
authored
120 - [Travis CI][travis] for an awesome open-source testing service
4eaf836 @jed shout out to @chriso
authored
121 - [@chriso][chriso] for letting me have the "dynamo" name on npm
4d3f160 @jed credits
authored
122 - [@skomski][skomski] for turning me on to [IAM credentials][iam]
e68521b @jed update testing info
authored
123 - [@mranney][mranney] for inspiration from the venerable [node_redis][node_redis]
4d3f160 @jed credits
authored
124 - [@visionmedia][tj] for making testing easy with [mocha][mocha] and [should.js][should]
125
02e173b @jed add anchors
authored
126 <a name="copyright"></a>
de0d945 @jed first cut
authored
127 Copyright
128 ---------
129
130 Copyright (c) 2012 Jed Schmidt. See LICENSE.txt for details.
131
222b409 @jed update README
authored
132 Send any questions or comments [here][twitter].
133
134 [travis]: http://travis-ci.org/jed/dynamo
135 [node]: http://nodejs.org
136 [dynamo]: http://docs.amazonwebservices.com/amazondynamodb/latest/developerguide/Introduction.html
137 [aws]: http://aws.amazon.com
138 [api]: http://docs.amazonwebservices.com/amazondynamodb/latest/developerguide/operationlist.html
139 [mranney]: https://github.com/mranney
4d3f160 @jed credits
authored
140 [skomski]: https://github.com/skomski
222b409 @jed update README
authored
141 [node_redis]: https://github.com/mranney/node_redis
9caab30 @jed space commit to trigger travis
authored
142 [twitter]: http://twitter.com/jedschmidt
b22a282 @jed add mocha, should, heroku
authored
143 [heroku]: http://heroku.com
144 [mocha]: https://visionmedia.github.com/mocha
145 [should]: https://github.com/visionmedia/should.js
06f7c70 @jed update testing info
authored
146 [tj]: https://github.com/visionmedia
505312b @jed add details about callbacks and API
authored
147 [iam]: http://docs.amazonwebservices.com/IAM/latest/UserGuide/IAM_Introduction.html
4eaf836 @jed shout out to @chriso
authored
148 [connect]: http://www.senchalabs.org/connect
2bcfce3 @jed 0.2.0
authored
149 [chriso]: https://github.com/chriso
150 [low-api]: https://github.com/jed/dynamo/wiki/Low-level-API
151 [high-api]: https://github.com/jed/dynamo/wiki/High-level-API
152 [npm]: http://npmjs.org
Something went wrong with that request. Please try again.