nosql-tutorial 0.1.0 → 0.1.1

data/lib/views/couchdb-futon.rdiscount

@@ -0,0 +1,116 @@
+#### {% title "CouchDB — Futon" %}
+
+# CouchDB — Futon
+
+Graficzny interfejs do CouchDB jest dostępny z URI:
+
+    http://127.0.0.1:5984/_utils/
+
+albo:
+
+    http://localhost:5984/_utils/
+
+Korzystamy z nakładki Futon aby utworzyć i usunąć bazę danych,
+dodajemy i usuwamy dokument z bazy danych, dodajemy i usuwamy
+załącznik. Tworzymy tymczasowy widok.
+
+
+## Tworzymy bazę i dodajemy do niej dokumenty
+
+Tworzymy prostą bazę danych *sprawdziany*:
+
+    curl -X PUT http://127.0.0.1:5984/sprawdziany
+
+w której będziemy zapisywać takie dokumenty:
+
+    nazwa: "jakie?"
+    wyniki: { "login1":wynik1, ...}
+
+Dodajemy kilka dokumentów do bazy danych. 
+Tak to można zrobić z wiersza poleceń:
+
+    curl -X POST -d @sprawdziany.json http://127.0.0.1:5984/sprawdziany/_bulk_docs
+
+gdzie w pliku *sprawdziany.json* wpisaliśmy:
+
+    :::json
+    {
+      "docs": [
+        {"_id":"1", "nazwa":"html", "wyniki":{"jacek":10, "agatka":20}},
+        {"_id":"2", "nazwa":"css",  "wyniki":{"jacek":1,  "agatka":12}},
+        {"_id":"3", "nazwa":"js",   "wyniki":{"jacek":1,  "agatka":12}}
+      ]
+    }
+
+Możemy też dodać kilka dokumentów, korzystając z *Futona*. **Jak?**
+
+
+## Tymczasowe widoki
+
+Tutaj:
+
+    http://127.0.0.1:5984/_utils/index.html
+
+jest lista baz. A tutaj baza *sprawdziany*:
+
+    http://127.0.0.1:5984/_utils/database.html?sprawdziany
+
+Tworzymy widok tymczasowy (lista rozwijana, prawy górny róg):
+wybieramy **Temporary view**. Domyślny widok definiuje funkcja:
+
+    :::javascript
+    function(doc) {
+      emit(null, doc);
+    }
+
+Uruchamiamy wpisaną *Map Function*.
+Czy można odgadnąć czym jest argument *doc* tej funkcji?
+
+W okienku *View Code* wpisujemy naszą pierwszą *Map Function*:
+
+    :::javascript
+    function(doc) {
+        var login, wynik, value;
+        if (doc.nazwa && doc.wyniki) {
+            for (login in doc.wyniki) {
+                wynik = doc.wyniki[login];
+                value = [login, doc.nazwa, wynik];
+                emit(wynik, value);
+            }
+        }
+    }
+
+Sortowanie po wynikach. Jak posortować po *loginach*? (proste)
+
+Druga funkcja map:
+
+    :::javascript
+    function(doc) {
+        var wynik, key;
+        if (doc.nazwa && doc.wyniki) {
+            for (var login in doc.wyniki) {
+                wynik = doc.wyniki[login];
+                key = [doc.nazwa, wynik];
+                emit(key, login);
+            }
+        }
+    }
+
+Teraz sortowanie jest po `[doc.nazwa, wynik]`. Co to oznacza?
+
+
+## Konfiguracja
+
+Jeśli w konfiguracji **httpd > bind address** zmienimy 127.0.0.1
+na 0.0.0.0, to uzyskamy zdalny dostęp do Futona 
+i CouchDB. (Ale stracimy dostęp lokalny.)
+
+
+## Replikacja bazy danych
+
+Do czego może się przydać?
+
+
+## Compacting database
+
+Ważne! Dlaczego?

data/lib/views/couchdb-ruby.rdiscount

@@ -0,0 +1,53 @@
+#### {% title "CouchDB – Ruby" %}
+
+# CouchDB – Ruby
+
+## Korzystamy z gemu *rest-client*
+
+Przykład z Wiki: [collation](http://wiki.apache.org/couchdb/View_collation):
+
+    :::ruby
+    # file: collseq.rb
+    require 'rubygems'
+    require 'restclient'
+    require 'json'
+
+    DB="http://127.0.0.1:5984/collator"
+    RestClient.delete DB rescue nil
+    RestClient.put "#{DB}",""
+    (32..126).each do |c|
+      RestClient.put "#{DB}/#{c.to_s(16)}", {"x"=>c.chr}.to_json
+    end
+    RestClient.put "#{DB}/_design/test", <<EOS
+    {
+      "views":{
+        "one":{
+          "map":"function (doc) { emit(doc.x,null); }"
+        }
+      }
+    }
+    EOS
+    puts RestClient.get("#{DB}/_design/test/_view/one")
+
+## Couchrest & irb
+
+    :::ruby
+    db = CouchRest.database!("http://localhost:5984/my_db")
+    attr = { "imie" => "Włodek", "login" => "wbzyl", "wiek" => "18" }
+    result = db.save_doc(attr)
+
+Dalej
+
+    :::ruby
+    result['id']
+    record = db.get(result['id'])
+    record['_rev']
+    record['login'] = 'matwb'
+    result = db.save_doc(record)
+    record = db.get(result['id'])
+    db.delete_doc(record)
+
+
+Zob. [Contacts](http://gist.github.com/112109),
+[blog J. P. Wood’a](http://johnpwood.net/tag/couchrest/),
+[Rails Wiki: CouchDB](http://wiki.rubyonrails.org/database-support/couchdb).

data/lib/views/couchdb-views.rdiscount

@@ -0,0 +1,162 @@
+#### {% title "CouchDB — Widoki" %}
+
+# CouchDB — Widoki
+
+Zapytania SQL, takie jak to:
+
+    SELECT name, email, fax FROM contacts
+
+nie mają sensu dla dokumentowych baz danych.  
+
+Dlaczego? Rozważyć wartości NULL. Rekordy w tabelach SQL a dokumenty w
+dokumentowych bazach danych.
+
+W dokumentowych bazach danych zamiast pisać zapytania
+piszemy widoki. Cytat: 
+„Views are the primary tool used for querying and reporting on CouchDB
+documents. There are two different kinds of views: permanent and
+temporary views.”
+
+Widoki są zapisywane w bazie jako specjalne **design documents**.
+Widoki są powielane z zwykłymi dokumentami.
+
+
+## Widoki w CouchDB API
+
+Tymczasowy widok, np. taki:
+
+    :::javascript
+    function(doc) {
+       emit(doc._id, doc);
+    }
+
+wywołujemy z wiersza poleceń w taki sposób:
+
+    curl -X POST http://127.0.0.1:5984/sprawdziany/_temp_view \
+      -d '{"map":"function(doc) { emit(doc._id, doc); }"}'
+
+Widok permanentny wstawiamy do bazy
+z *id* **_design/*nazwa_widoku*** w taki sposób:
+
+    curl -X PUT http://127.0.0.1:5984/sprawdziany/_design/wyniki -d @ja.json
+
+gdzie plik *ja.json* ma następującą zawartość:
+
+    :::json
+    {
+      "language": "javascript",
+      "views": {
+          "wyniki_jacka": {
+              "map": "function(doc) {
+                         if (doc.nazwa && doc.wyniki['jacek']) {
+                             emit(doc.nazwa, doc.wyniki['jacek']);
+                         }
+              }"
+          },
+          "wyniki_agatki": {
+              "map": "function(doc) {
+                         if (doc.nazwa && doc.wyniki['agatka']) {
+                             emit(doc.nazwa, doc.wyniki['agatka']);
+                         }
+              }"
+          }
+      }
+    }
+
+Widoki permanentne wywołujemy inaczej (GET zamiast POST):
+
+    curl -X GET http://127.0.0.1:5984/sprawdziany/_design/wyniki/_view/wyniki_jacka
+    curl -X GET http://127.0.0.1:5984/sprawdziany/_design/wyniki/_view/wyniki_agatki
+
+Ale łatwiejszy w dalszej obróbce byłby taki widok:
+
+    :::javascript
+    function(doc) {
+      if (doc.nazwa && doc.wyniki['jacek']) {
+        emit(doc._id, {"sprawdzian":doc.nazwa, "punkty":doc.wyniki['jacek']});
+      }
+    }
+
+## „Złączenia” w bazach CouchDB
+
+Example: how you'd go about modeling a simple blogging system with “post” and
+“comment” entities, where any blog post might have many comments.
+
+Przykład z artykułu:
+Christopher Lenz, [CouchDB "Joins"](http://www.cmlenz.net/archives/2007/10/couchdb-joins).
+
+### Komentarze inline
+
+Utworzymy bazę zawierającą kilka takich dokumentów:
+
+    :::json
+    {
+      "author": "jacek",
+      "title": "Rails 2",
+      "content": "Bla bla…",
+      "comments": [
+        {"author": "agatka", "content": "…"},
+        {"author": "bolek",  "content": "…"}
+      ]
+    }
+
+Dane do umieścimy w bazie za pomocą skryptu 
+{%= link_to 'blog-inline.rb', '/doc/couchdb/blog-inline.rb' %}.
+
+Widok:
+
+    :::javascript
+    function(doc) {
+      for (var i in doc.comments) {
+        emit(doc.comments[i].author, doc.comments[i].content);
+      }
+    }
+
+Jakie problemy może dawać takie podejście?
+
+
+### Komentarze w osobnych dokumentach:
+
+Utworzymy bazę zawierającą kilka postów:
+
+    :::json
+    {
+      "_id": "01"
+      "type": "post",
+      "author": "jacek",
+      "title": "Rails 3",
+      "content": "Bla bla bla …"
+    }
+
+oraz komentarzy:
+
+    :::json
+    {
+      "type": "comment",
+      "post_id": "01",
+      "author": "agatka",
+      "content": "…"
+    }
+    {
+      "type": "comment",
+      "post_id": "01",
+      "author": "bolek",
+      "content": "…"
+    }
+
+TODO: 
+Dane do umieścimy w bazie za pomocą skryptu 
+{%= link_to 'blog-separate.rb', '/doc/couchdb/blog-separate.rb' %}.
+
+Poniższy widok, wypisuje komentarze zgrupowane po *post_id*:
+
+    :::javascript
+    function(doc) {
+      if (doc.type == "comment") {
+        emir(doc.post_id, {author: doc.author, content: doc.content});
+      }
+    }
+
+Sprawdzić powyższe stwierdzenie.
+
+Takie podejście ma swoje braki. Jakie?

data/lib/views/couchdb.rdiscount

@@ -0,0 +1,122 @@
+#### {% title "CouchDB – Zaczynamy" %}
+
+# CouchDB – Zaczynamy
+
+Co to są [dokumentowe bazy danych] [document-oriented database]?
+
+Dlaczego korzystamy z dokumentowych baz danych: 
+
+1. Dokumentowe systemy baz danych są **schema-free**.
+1. Another advantage of document oriented databases is **the ease of
+  usage and programming** so that untrained business users, for example,
+  can create applications and design their own databases. Information
+  can be added without worrying about the "record size" and so
+  programmers simply need to build an interface to allow the
+  information to be entered easily.
+
+Dwa cytaty ze strony [projektu CouchDB](http://couchdb.apache.org/):
+
+„Apache CouchDB is a document-oriented database that can be queried and
+indexed in a MapReduce fashion using JavaScript.”
+
+„CouchDB provides a RESTful JSON API than can be accessed from any
+environment that allows HTTP requests.”
+
+Trochę historii:
+
+* [Damien Katz](http://damienkatz.net/) – autor
+* Przepisanie programu z C++ na Erlang – 2006
+* Restful API – kwiecień 2006
+* Pierwsza dostępna wersja 0.2 – sierpień 2006
+* Przejście z XML na JSON, Javascript językiem zapytań – sierpień 2007
+* [Map/Reduce][map-reduce] – luty 2008
+
+
+## Instalacja serwera CouchDB
+
+Najłatwiej jest zainstalować serwer z pakietu:
+
+* Fedora: `su –c 'yum install couchdb'`
+* Ubuntu: ???
+
+Sprawdzamy, czy instalacja przebiegła bez błędów:
+
+    curl http://127.0.0.1:5984/
+      => {"couchdb":"Welcome","version":"0.11.0b"}
+
+Na koniec wchodzimy na stronę:
+
+    http://127.0.0.1:5984/_utils/
+
+gdzie jest dostępny *Futon*, czyli narzędzie do administracji bazami
+danych zarządzanymi przez CouchDB.
+
+Klikając w odpowiednie zakładki *Futona* możemy wyświetlić
+listę zainstalowanych baz danych, szczegóły konfiguracji itd.
+
+Ale informacje te można też uzyskać inaczej, korzystając
+z na przykład programu *curl*:
+
+    curl -X GET http://127.0.0.1:5984/_all_dbs
+    curl -X GET http://127.0.0.1:5984/_config
+
+Na koniec kilka innych zapytań:
+
+    curl -X GET  http://127.0.0.1:5984/_uuids?count=2
+    curl -X POST http://127.0.0.1:5984/_replicate?source=xxx&target=yyy
+
+W odpowiedzi na każde żądanie HTTP (*request*), dostajemy 
+odpowiedź HTTP (*response*) w formacie [JSON][json]. 
+
+**Co to jest:** HTTP request, HTTP response, format wymiany danych JSON?
+
+Jeśli skorzystamy z opcji `-v` programu *curl*
+to program wypisze szczegóły tego co robi, na przykład:
+
+    curl -vX POST http://127.0.0.1:5984/_replicate?source=xxx&target=yyy
+
+(Chociaż tutaj *content-type* jest ustawiony na *text/plain;charset=utf-8*.
+Dlaczego?)
+
+[json]: http://www.json.org/ "JSON"
+
+
+## CRUD na bazach danych
+
+CRUD to skrót od pierwszych liter słów: 
+Create, Read, Update, Delete.
+
+Poniżej zobaczymy jak korzystając z programu *curl* 
+utworzyć nową bazę danych, usunąć bazę, pobrać informację o bazie
+itd. Skorzystam ze ściągi:
+
+* [Ściąga z API: Database level](http://wiki.apache.org/couchdb/API_Cheatsheet)
+
+Tworzymy nową bazę o nazwie *xxx*:
+
+    curl -X PUT http://127.0.0.1:5984/xxx
+
+Pobieramy info o bazie *xxx*:
+
+    curl -X GET http://127.0.0.1:5984/xxx
+
+Usuwamy bazę *xxx*:
+
+    curl -X DELETE http://127.0.0.1:5984/xxx
+
+Nie ma polecenia dla *Update*.
+Omówić pozostałe operacje ze ściągi: *Database level* 
+
+**REST** to akronim od *Represenational State Transfer*.
+Zwykle w kontekście WWW rozumiemy ten skrót tak:
+
+* Dane są zasobami (ang. resources)
+* Każdy zasób ma swój unikalny URI
+* Na zasobach można wykonywać cztery podstawowe operacje CRUD
+* Klient i serwer komunikują się ze sobą korzystając protokołu
+  bezstanowego. Oznacza to, że klient zwraca się z żądaniem do
+  serwera. Serwer odpowiada i cała konwersacja się kończy.
+
+
+[document-oriented database]: http://en.wikipedia.org/wiki/Document-oriented_database "Document-oriented database"
+[map-reduce]: http://en.wikipedia.org/wiki/MapReduce "MapReduce"