Permalink
Browse files

Merge branch 'gh-pages' of git://github.com/oreilly/couchdb-guide int…

…o gh-pages
  • Loading branch information...
christophercliff committed Jul 3, 2011
2 parents 438d7d9 + 2559456 commit 6c9704a1d92cceb65903d24a6e42d55f102a0def
View
@@ -178,7 +178,7 @@ <h3 id="databases">Databases</h3>
&lt; Date: Sun, 05 Jul 2009 22:48:28 GMT
</pre>
-<p>The <code>Date</code> header tells you the time of the server. Since client and server time are not necessary synchronized, this header is purely informational. You shouldn’t build any critical application logic on top of this!
+<p>The <code>Date</code> header tells you the time of the server. Since client and server time are not necessarily synchronized, this header is purely informational. You shouldn’t build any critical application logic on top of this!
<pre>
&lt; Content-Type: text/plain;charset=utf-8
@@ -265,7 +265,7 @@ <h3 id="documents">Documents</h3>
{"uuids":["6e1295ed6c29495e54cc05947f18c8af"]}
</pre>
-<p>Voilá, a UUID. If you need more than one, you can pass in the <code>?count=10</code> HTTP parameter to request 10 UUIDs, or really, any number you need.
+<p>Voilà, a UUID. If you need more than one, you can pass in the <code>?count=10</code> HTTP parameter to request 10 UUIDs, or really, any number you need.
</div>
@@ -368,7 +368,7 @@ <h5 id="attachments">Attachments</h5>
<p>Attachments get their own URL where you can upload data. Say we want to add the album artwork to the <code>6e1295ed6c29495e54cc05947f18c8af</code> document (“There is Nothing Left to Lose”), and let’s also say the artwork is in a file <code>artwork.jpg</code> in the current directory:
<pre>
-&gt; curl -vX PUT http://127.0.0.1:5984/albums/6e1295ed6c29495e54cc05947f18c8af/ artwork.jpg?rev=2-2739352689 --data-binary @artwork.jpg -H "Content-Type: image/jpg"
+&gt; curl -vX PUT http://127.0.0.1:5984/albums/6e1295ed6c29495e54cc05947f18c8af/artwork.jpg?rev=2-2739352689 --data-binary @artwork.jpg -H "Content-Type: image/jpg"
</pre>
<p>The <code>--data-binary @</code> option tells <code>curl</code> to read a file’s contents into the HTTP request body. We’re using the <code>-H</code> option to tell CouchDB that we’re uploading a JPEG file. CouchDB will keep this information around and will send the appropriate header when requesting this attachment; in case of an image like this, a browser will render the image instead of offering you the data for download. This will come in handy later. Note that you need to provide the current revision number of the document you’re attaching the artwork to, just as if you would update the document. Because, after all, attaching some data is changing the document.
@@ -408,7 +408,7 @@ <h3 id="replication">Replication</h3>
<p>Now we can use the database <code>albums-replica</code> as a replication target:
<pre>
-curl -vX POST http://127.0.0.1:5984/_replicate -d '{"source":"albums","target":"albums-replica"}'
+curl -vX POST http://127.0.0.1:5984/_replicate -d '{"source":"albums","target":"albums-replica"}' -H "Content-Type: application/json"
</pre>
<div class="aside note">
@@ -449,7 +449,7 @@ <h3 id="replication">Replication</h3>
<p>There are more types of replication useful in other situations. The <code>source</code> and <code>target</code> members of our replication request are actually links (like in HTML) and so far we’ve seen links relative to the server we’re working on (hence <em>local</em>). You can also specify a remote database as the target:
<pre>
-curl -vX POST http://127.0.0.1:5984/_replicate -d '{"source":"albums","target":"http://example.org:5984/albums-replica"}'
+curl -vX POST http://127.0.0.1:5984/_replicate -d '{"source":"albums","target":"http://example.org:5984/albums-replica"}' -H "Content-Type: application/json"
</pre>
<p>Using a local <code>source</code> and a remote <code>target</code> database is called <em>push replication</em>. We’re pushing changes to a remote server.
@@ -465,13 +465,13 @@ <h3 id="replication">Replication</h3>
<p>You can also use a remote <code>source</code> and a local <code>target</code> to do a <em>pull replication</em>. This is great for getting the latest changes from a server that is used by others:
<pre>
-curl -vX POST http://127.0.0.1:5984/_replicate -d '{"source":"http://example.org:5984/albums-replica","target":"albums"}'
+curl -vX POST http://127.0.0.1:5984/_replicate -d '{"source":"http://example.org:5984/albums-replica","target":"albums"}' -H "Content-Type: application/json"
</pre>
<p>Finally, you can run <em>remote replication</em>, which is mostly useful for management operations:
<pre>
-curl -vX POST http://127.0.0.1:5984/_replicate -d '{"source":"http://example.org:5984/albums","target":"http://example.org:5984/albums-replica"}'
+curl -vX POST http://127.0.0.1:5984/_replicate -d '{"source":"http://example.org:5984/albums","target":"http://example.org:5984/albums-replica"}' -H "Content-Type: application/json"
</pre>
<div class="aside note">
View
@@ -145,7 +145,7 @@ <h3 id="working">Working with Conflicts</h3>
{"ok":true,"id":"foo","rev":"1-74620ecf527d29daaab9c2b465fbce66"}
&gt; curl -X POST $HOST/_replicate -d '{"source":"db","target":"http://127.0.0.1:5984/db-replica"}'
-{"ok":true,...,"docs_written":1,"doc_write_failures":0}]}
+{"ok":true,...,"docs_written":1,"doc_write_failures":0}]} -H "Content-Type: application/json"
</pre>
<p>We skip a bit of the output of the replication session (see <a href="replication.html">Chapter 16, Replication</a> for details). If you see <code>"docs_written":1</code> and <code>"doc_write_failures":0</code>, our document made it over to <code>db-replica</code>. We now update the document to <code>{"count":2}</code> in <code>db-replica</code>. Note that we now need to include the correct <code>_rev</code> property.
@@ -162,7 +162,7 @@ <h3 id="working">Working with Conflicts</h3>
{"ok":true,"id":"foo","rev":"2-7c971bb974251ae8541b8fe045964219"}
&gt; curl -X POST $HOST/_replicate -d '{"source":"db","target":"http://127.0.0.1:5984/db-replica"}'
-{"ok":true,..."docs_written":1,"doc_write_failures":0}]}
+{"ok":true,..."docs_written":1,"doc_write_failures":0}]} -H "Content-Type: application/json"
</pre>
<p>To see that we have a conflict, we create a simple view in <code>db-replica</code>. The map function looks like this:
@@ -231,7 +231,7 @@ <h3 id="working">Working with Conflicts</h3>
<p>Finally, we replicate from <code>db-replica</code> back to <code>db</code> by simply swapping <code>source</code> and <code>target</code> in our request to <code>_replicate</code>:
<pre>
-&gt; curl -X POST $HOST/_replicate -d '{"target":"db","source":"http://127.0.0.1:5984/db-replica"}'
+&gt; curl -X POST $HOST/_replicate -d '{"target":"db","source":"http://127.0.0.1:5984/db-replica"}' -H "Content-Type: application/json"
</pre>
<p>We see that our revision ends up in <code>db</code>, too:
View
@@ -288,7 +288,7 @@ <h3 id="aggregate">Aggregate Functions</h3>
<p>The total sum of all <code>age</code> fields in all our documents is <code>15</code>. Just what we wanted. The <code>key</code> member of the result object is <code>null</code>, as we can’t know anymore which documents took part in the creation of the reduced result. We’ll cover more advanced reduce cases later on.
-<p>As a rule of thumb, the reduce function should reduce a single scalar value. That is, an integer; a string; or a small, fixed-size list or object that includes an aggregated value (or values) from the <code>values</code> argument. It should never just return <code>values</code> or similar. CouchDB will give you a warning if you try to use reduce “the wrong way”:
+<p>As a rule of thumb, the reduce function should reduce to a single scalar value. That is, an integer; a string; or a small, fixed-size list or object that includes an aggregated value (or values) from the <code>values</code> argument. It should never just return <code>values</code> or similar. CouchDB will give you a warning if you try to use reduce “the wrong way”:
<pre>
{"error":"reduce_overflow_error","message":"Reduce output must shrink more rapidly: Current output: ..."}
View
@@ -109,7 +109,7 @@ <h3 id="basic">A Basic Design Document</h3>
<pre>
curl -X PUT http://127.0.0.1:5984/basic
-curl -X PUT http://127.0.0.1:5984/basic/_design/example -d @mydesign.json
+curl -X PUT http://127.0.0.1:5984/basic/_design/example -data-binarymydesign.json
</pre>
<p>From the second request, you should see a response like:
@@ -121,7 +121,7 @@ <h3 id="basic">A Basic Design Document</h3>
<p>Now we can query the view we’ve defined, but before we do that, we should add a few documents to the database so we have something to view. Running the following command a few times will add empty documents:
<pre>
-curl -X POST http://127.0.0.1:5984/basic -d '{}'
+curl -X POST http://127.0.0.1:5984/basic -d '{}' -H "Content-Type: application/json"
</pre>
<p>Now to query the view:
View
@@ -149,7 +149,7 @@ <h4 id="scaffold">The HTML Scaffold</h4>
<p>The only missing piece of this puzzle is the HTML that it takes to save a document like this.
-<p>In your browser, visit <code>http://127.0.0.1:5984/blog/_design/sofa/_show/edit</code> and, using your text editor, open the source file <code>templates/edit.html</code> (or view source in your browser). Everything is ready to go; all we have to do is wire up CouchDB using in-page JavaScript. See <a href="#figure/2">Figure 2, “HTML listing for edit.html”</a>.
+<p>In your browser, visit <code>http://127.0.0.1:5984/sofa/_design/sofa/_show/edit</code> and, using your text editor, open the source file <code>templates/edit.html</code> (or view source in your browser). Everything is ready to go; all we have to do is wire up CouchDB using in-page JavaScript. See <a href="#figure/2">Figure 2, “HTML listing for edit.html”</a>.
<p>Just like any web application, the important part of the HTML is the form for accepting edits. The edit form captures a few basic data items: the post title, the body (in Markdown format), and any tags the author would like to apply.
View
@@ -24,7 +24,7 @@ <h2 id="preface">Preface</h2>
<p>Writing an open book was great fun. We’re happy O’Reilly supported our decision in every way possible. The best part—besides giving the CouchDB community early access to the material—was the commenting functionality we implemented on the <a href="http://books.couchdb.org/relax">book’s website</a>. It allows anybody to comment on any paragraph in the book with a simple click. We used some simple JavaScript and Google Groups to allow painless commenting. The result was astounding. As of today, 866 people have sent more than 1,100 messages to our little group. Submissions have ranged from pointing out small typos to deep technical discussions. Feedback on our original first chapter led us to a complete rewrite in order to make sure the points we wanted to get across did, indeed, get across. This system allowed us to clearly formulate what we wanted to say in a way that worked for you, our readers.
-<p>Overall, the book has become so much better because of the help of hundreds of volunteers who took the time to send in their suggestions. We understand the immense value this model has, and we want to keep it up. New features in CouchDB should make it into the book without us necessarily having to do a reprint every thee months. The publishing industry is not ready for that yet, but we want to continue to release new and revised content and listen closely to the feedback. The specifics of how we’ll do this are still in flux, but we’ll be posting the information to the book’s website the first moment we know it. That’s a promise! So make sure to visit the book’s website at <a href="http://books.couchdb.org/relax">http://books.couchdb.org/relax</a> to keep up-to-date.
+<p>Overall, the book has become so much better because of the help of hundreds of volunteers who took the time to send in their suggestions. We understand the immense value this model has, and we want to keep it up. New features in CouchDB should make it into the book without us necessarily having to do a reprint every three months. The publishing industry is not ready for that yet, but we want to continue to release new and revised content and listen closely to the feedback. The specifics of how we’ll do this are still in flux, but we’ll be posting the information to the book’s website the first moment we know it. That’s a promise! So make sure to visit the book’s website at <a href="http://books.couchdb.org/relax">http://books.couchdb.org/relax</a> to keep up-to-date.
<p>Before we let you dive into the book, we want to make sure you’re well prepared. CouchDB is written in Erlang, but you don’t need to know anything about Erlang to use CouchDB. CouchDB also heavily relies on web technologies like HTTP and JavaScript, and some experience with those does help when following the examples throughout the book. If you have built a website before—simple or complex—you should be ready to go.
View
@@ -20,7 +20,7 @@ <h2 id="replication">Replication</h2>
<pre>
POST /_replicate HTTP/1.1
-{"source":"database","target":"http://example.org/database"}
+{"source":"database","target":"http://example.org/database"} -H "Content-Type: application/json"
</pre>
<p>This call sends all the documents in the local database <code>database</code> to the remote database <code>http://example.org/database</code>. A database is considered “local” when it is on the same CouchDB instance you send the <code>POST /_replicate</code> HTTP request to. All other instances of CouchDB are “remote.”
@@ -29,6 +29,7 @@ <h2 id="replication">Replication</h2>
<pre>
POST /_replicate HTTP/1.1
+Content-Type: application/json
{"source":"http://example.org/database","target":"database"}
</pre>
@@ -98,15 +99,15 @@ <h3 id="detail">Replication in Detail</h3>
<p>One common scenario is triggering replication on nodes that have admin accounts enabled. Creating design documents is restricted to admins, and if the replication is triggered without admin credentials, writing the design documents during replication will fail and be recorded as <code>doc_write_failures</code>. If you have admins, be sure to include the credentials in the replication request:
<pre>
-&gt; curl -X POST http://127.0.0.1:5984/_replicate -d '{"source":"http://example.org/database", "target":"http://admin:password@e127.0.0.1:5984/database"}'
+&gt; curl -X POST http://127.0.0.1:5984/_replicate -d '{"source":"http://example.org/database", "target":"http://admin:password@127.0.0.1:5984/database"}' -H "Content-Type: application/json"
</pre>
<h3 id="continuous">Continuous Replication</h3>
<p>Now that you know how replication works under the hood, we share a neat little trick. When you add <code>"continuous":true</code> to the replication trigger object, CouchDB will not stop after replicating all missing documents from the source to the target. It will listen on CouchDB’s <code>_changes</code> API (see <a href="notifications.html">Chapter 20, Change Notifications</a>) and automatically replicate over any new docs as they come into the source to the target. In fact, they are not replicated right away; there’s a complex algorithm determining the ideal moment to replicate for maximum performance. The algorithm is complex and is fine-tuned every once in a while, and documenting it here wouldn’t make much sense.
<pre>
-&gt; curl -X POST http://127.0.0.1:5984/_replicate -d '{"source":"db", "target":"db-replica", "continuous":true}'
+&gt; curl -X POST http://127.0.0.1:5984/_replicate -d '{"source":"db", "target":"db-replica", "continuous":true}' -H "Content-Type: application/json"
</pre>
<p>At the time of writing, CouchDB doesn’t remember continuous replications over a server restart. For the time being, you are required to trigger them again when you restart CouchDB. In the future, CouchDB will allow you to define permanent continuous replications that survive a server restart without you having to do anything.
View
@@ -24,7 +24,7 @@ <h3 id="party">The Admin Party</h3>
<p>A note of relief: by default, CouchDB will listen only on your loopback network interface (<code>127.0.0.1</code> or <code>localhost</code>) and thus only you will be able to make requests to CouchDB, nobody else. But when you start to open up your CouchDB to the public (that is, by telling it to bind to your machine’s public IP address), you will want to think about restricting access so that the next bad guy doesn’t ruin your admin party.
-<p>In our previous discussions, w dropped some keywords about how things without the admin party work. First, there’s <em>admin</em> itself, which implies some sort of super user. Then there are <em>privileges</em>. Let’s explore these terms a little more.
+<p>In our previous discussions, we dropped some keywords about how things without the admin party work. First, there’s <em>admin</em> itself, which implies some sort of super user. Then there are <em>privileges</em>. Let’s explore these terms a little more.
<p>CouchDB has the idea of an <em>admin user</em> (e.g. an administrator, a super user, or root) that is allowed to do anything to a CouchDB installation. By default, everybody is an admin. If you don’t like that, you can create specific admin users with a username and password as their credentials.
@@ -160,7 +160,7 @@ <h4 id="validation">Update Validations Again</h4>
<pre>
&gt; curl -X POST $HOST/somedatabase/ -d '{"a":1}'
-{"ok":true,"id":"36174efe5d455bd45fa1d51efbcff986","rev":"1-23202479633c2b380f79507a776743d5"}
+{"ok":true,"id":"36174efe5d455bd45fa1d51efbcff986","rev":"1-23202479633c2b380f79507a776743d5"} -H "Content-Type: application/json"
</pre>
<p>we should see this in our <code>couch.log</code> file:
@@ -195,7 +195,7 @@ <h3 id="cookies">Cookie Authentication</h3>
<pre>
&gt; HOST="http://127.0.0.1:5984"
-&gt; curl -vX POST $HOST/_session -H 'application/x-www-form-urlencoded' -d 'name=anna&amp;password=secret'
+&gt; curl -vX POST $HOST/_session -H 'Content-Type: application/x-www-form-urlencoded' -d 'name=anna&amp;password=secret'
</pre>
<p>CouchDB replies, and we’ll give you some more detail:
View
@@ -174,7 +174,7 @@ <h3 id="welcome">Welcome to Futon</h3>
<div class="aside warning">
-<p>Some common network configurations cause the replication test to fail when accessed via the <code>localhost</code> address. You can fix this by accessing CouchDB via <code>127.0.0.1</code>, e.g. <code>http://127.0.1:5984/_utils/</code>.
+<p>Some common network configurations cause the replication test to fail when accessed via the <code>localhost</code> address. You can fix this by accessing CouchDB via <code>127.0.0.1</code>, e.g. <code>http://127.0.0.1:5984/_utils/</code>.
</div>
View
@@ -178,7 +178,7 @@ <h4 id="timestamps">Timestamps</h4>
false
</pre>
-<p>JavaScript considers these arrays to be different because it doesn’t look at the contents of the array when making the decision. Since they are distinct objects, JavaScript must consider them not equal. We use the <code>toJSON</code> function to convert objects to a string representation, which makes comparisons more likely to succeed in the case where two objects have the same contents. This is not guaranteed to work for deeply nested objects, as <code>toJSON</code> may serialize objects.
+<p>JavaScript considers these arrays to be different because it doesn’t look at the contents of the array when making the decision. Since they are distinct objects, JavaScript must consider them not equal. We use the <code>toJSON</code> function to convert objects to a string representation, which makes comparisons more likely to succeed in the case where two objects have the same contents. This is not guaranteed to work for deeply nested objects, as <code>toJSON</code> may serialize objects in an undefined order.
<div class="aside note">
@@ -110,7 +110,7 @@ <h3 id="basic">Ein einfaches Design Dokument</h3>
<pre>
curl -X PUT http://127.0.0.1:5984/basic
-curl -X PUT http://127.0.0.1:5984/basic/_design/example -d @mydesign.json
+curl -X PUT http://127.0.0.1:5984/basic/_design/example -data-binarymydesign.json
</pre>
<p>Nach dem zweiten Request sollte eine Antwort wie die Folgende zu sehen sein:
Oops, something went wrong.

0 comments on commit 6c9704a

Please sign in to comment.