Documentazione DataStax su Cassandra
!L'ultima versione della documentazione su Cassandra fornita da DataStax copre argomenti che vanno dall'installazione alla risoluzione di problemi, e include anche una guida introduttiva. La documentazione per le versioni più datate è comunque disponibile.
Cassandra su una VM
Si può provare Cassandra seguendo questi dieci minuti di introduzione per sviluppatori e amministratori.
Installare Cassandra in locale
Questo documento ha la scopo di spiegare i pochi, semplici passi per effettuare una prima installazione, avviare un nodo Cassandra, e configurare un cluster. Cassandra è pensata per girare su un cluster, ma può tranquillamente essere usata su una singola macchina. Di seguito è descritto un modo semplice per provare Cassandra, evitandosi l'onere della gestione di un sistema più grande.
Step 0: Prerequisiti e connessione alla Community
Cassandra richiede la versione più stabile di Java 7 o 8 con cui si possa lavorare, preferibilmente la Oracle/Sun JVM. Cassandra funziona anche con la OpenJDK e la IBM JVM. (Mentre non va bene la JRockit, che è compatibile solo con Java 6.)
Il miglior modo per assicurarsi di avere sempre informazioni aggiornate sul progetto, selle release, la stabilità, i bug, e le nuove funzionalità è iscriversi alla mailing list degli utenti (iscrizione richiesta) e participare al #cassandra channel su IRC.
Step 1: Scaricare Cassandra
- I link per il download della versione stabile più recente sono sempre reperibili sul website.
- Gli utenti di sistemi Debian o Debian-like possono aggiornare l'ultima versione stabile come pacchetto, vedere DebianPackaging per i dettagli.
- Gli utenti di distribuzioni RPM-based possono trovare i pacchetti aggiornati su Datastax.
- Se si desidera fare direttamente il build dai sorgenti di Cassandra, leggere la pagina How to Build.
Per maggiori dettagli sul build, fare riferimento alla pagina Cassandra versions and builds.
Step 2: Configurazione di base
Il file di configurazione di Cassandra si trova nella cartella conf della distribuzione scelta (sia binary che source). Se si è scelto di installare Cassandra da un pacchetto deb o rpm, i file di configurazione si trovano in /etc/cassandra.
Step 2.1: Cartelle usate Cassandra
Se si è scelto di installare Cassandra tramite un pacchetto deb o rpm, le cartelle che Cassandra andrà ad usare dovrebbero già esistere e avere i corretti permessi di accesso. Altrimenti, occorre controllare i seguenti parametri nel file conf/cassandra.yaml: data_file_directories (/var/lib/cassandra/data), commitlog_directory (/var/lib/cassandra/commitlog), e saved_caches_directory (/var/lib/cassandra/saved_caches). Assicurarsi che queste cartelle esistano e siano accessibili.
Di default, Cassandra scriverà i suoi log in /var/log/cassandra/. Assicurarsi che la cartella esista e abbia i corretti permessi in lettura, oppure cambiare la seguente riga nel file conf/log4j-server.properies:
log4j.appender.R.File=/var/log/cassandra/system.log
Nota: in Cassandra 2.1+, the logger usato è un logback, quindi occcorre cambiare la cartella di log nel file conf/logback.xml così:
<file>/var/log/cassandra/system.log</file>
Le configurazioni JVM-level come l'heap size possono essere settate in conf/cassandra-env.sh.
Step 3: Avvio di Cassandra
E ora giunge il momento della verità: avviare Cassandra lanciando il comando 'bin/cassandra -f' da terminale
1
. Il servizio dovrebbe partire in foreground e i log dovrebbero essere visibili dalla console. Se non compaiono messaggi con parole spaventose come "error", o "fatal", o altro che potrebbe sembrare un messaggio dal Java stack trace, allora tutto dovrebbe essere partito correttamente.
Digitare "Control-C" per interrompere Cassandra.
Se si avvia senza l'opzione "-f", Cassandra partità in background. Si può interrompere il processo effettuandone il kill, usando 'pkill -f CassandraDaemon', ad esempio.
- Gli utenti che usano distribuzioni di Linux recenti e Mac OS X Snow Leopard dovrebbero poter avviare Cassandra semplicemente scompattando il pacchetto e lanciando
bin/cassandra -f. Da Cassandra 2.1 in poi, il download del tar.gz contiene anche le cartelle di log e dei dati di default. Le versioni precedenti hanno come default/var/log/cassandrae/var/lib/cassandra/. Per questo è necessario avviare Cassandra con i permessi da root o cambiare ilconf/cassandra.yamlper usare una cartella a cui abbia accesso l'utente corrente. Snow Leopard viene distribuito con Java 1.6.0 e non necessità del settaggio diJAVA_HOMEtra le variabili d'ambiente o dell'aggiunta di cartelle nel proprioPATH. Su Linux assicurarsi solo di avere un Java JDK package installato e funzionante, ad esempioopenjdk-6-jdksu Ubuntu Lucid Lynx.
Step 4: Usare cqlsh
bin/cqlsh è un'interfaccia da riga di comando per Cassandra. cqlsh permette l'esecuzione di comandi CQL (Cassandra Query Language) su Cassandra. Usando il CQL, si possono definire schemi, inserire dati, eseguire query. Lanciare il seguente comando per connettersi alla propria istanza di Cassandra in locale con cqlsh:
$ bin/cqlsh
Dovrebbe comparire il seguente messaggio, se tutto è andato a buon fine:
Connected to Test Cluster at localhost:9160. [cqlsh 2.3.0 | Cassandra 1.2.2 | CQL spec 3.0.0 | Thrift protocol 19.35.0] Use HELP for help.
Per chiarezza, ometteremo il cqlsh prompt nei seguenti esempi.
Si può accedere all'help online, digitando 'help;'. Tutti i comandi devono terminare con il punto e virgola (';') in cqlsh.
Innazitutto, creiamo un keyspace – ovvero un namespace di tabelle.
CREATE KEYSPACE mykeyspace
WITH REPLICATION = { 'class' : 'SimpleStrategy', 'replication_factor' : 1 };
Poi, accediamo al nuovo keyspace:
USE mykeyspace;
Poi, creiamo una tabella users:
CREATE TABLE users ( user_id int PRIMARY KEY, fname text, lname text );
Ora si possono inserire dati dentro users:
INSERT INTO users (user_id, fname, lname) VALUES (1745, 'john', 'smith'); INSERT INTO users (user_id, fname, lname) VALUES (1744, 'john', 'doe'); INSERT INTO users (user_id, fname, lname) VALUES (1746, 'john', 'smith');
E si possono leggere i dati inseriti:
SELECT * FROM users;
Dovrebbero comparire le nuove righe inserite:
user_id | fname | lname
---------+-------+-------
1745 | john | smith
1744 | john | doe
1746 | john | smith
Si possono recuperare i dati degli utenti il cui cognome è "smith" creando un indice, e interrogando la tabella come segue:
CREATE INDEX ON users (lname);
SELECT * FROM users WHERE lname = 'smith';
user_id | fname | lname
---------+-------+-------
1745 | john | smith
1746 | john | smith
Sviluppare un'applicazione
Per connettersi a Cassandra, è necessario un database driver per il linguaggio di programmazione scelto. DataStax fornisce driver CQL su https://github.com/datastax. Un elenco completo di driver CQL può essere trovato nella pagina ClientOptions.
Per la progettazione del proprio modello di dati, può essere utile dare un'occhiata alla pagina DataModel.
Può essere utile anche leggere la completa documentazione CQL.
Configurare Cluster Multinodo
Ora abbiamo un singolo nodo di Cassandra funzionante. Di fatto è un cluster Cassandra con un solo nodo. Aggiungendo altri nodi, possiamo trasformarlo in un cluster multinodo.
Configurare un cluster Cassandra è semplice quasi come ripetere la procedura sopra descritta per ogni nodo del proprio cluster cluster. Ci sono giusto alcune piccole differenze.
I nodi Cassandra si scambiano informazioni usando un protocollo chiamato Gossip, ma per entrare in gioco, un nuovo nodo deve conoscere almeno un altro nodo, chiamato Seed. É buona norma mantenere relativamente stabili alcuni dei propri nodi per usarli come seed, ma non ci sono vere regole per farlo. Assicurarsi che ogni seed conosca almeno uno degli altri, e, ricordarsi che l'obiettivo è quello di evitare una situazione di loop e fornire un modo in cui ogni nodo possa ricevere informazioni sugli altri.
Oltre ai seed, sarà necessario configurare anche l'interfaccia IP che resti in ascolto delle chiamate Gossip e CQL, (listen_address e rpc_address rispettivamente). Usare un 'listen_address{{ che sia raggiungibile dai }}listen_address{{ degli altri nodi, e un }}rpc_address` che sia accessibile dai clients.
Una volta terminate le configurazioni e i nodi sono avviati, usare il comando bin/nodetool status per verificare lo stato effettivo del cluster. Ad esempio:
$ bin/nodetool -host 192.168.0.10 -p 7199 status Datacenter: datacenter1 ======================= Status=Up/Down |/ State=Normal/Leaving/Joining/Moving -- Address Load Tokens Owns Host ID Rack UN 127.0.0.3 30.99 KB 256 32.4% 92b20e08-9ddd-4f55-9173-8516e74d27f5 rack1 UN 127.0.0.2 31 KB 256 31.5% b9616658-c744-48fb-b64f-83f96b007d93 rack1 UN 127.0.0.1 30.96 KB 256 36.1% f7a08973-85bd-460f-8176-d6f9df8c23f4 rack1
Una gestione del cluster più avanzata è descritta in Operations.
Se non si ha a disposizione hardware sufficiente per un vero cluster Cassandra, si possono facilmente gestire cluster locali con ccm (Cassandra Cluster Manager).
Se qualcosa va storto
Se si sono seguiti gli step sopra descritti, ma qualcosa è andato storto, saremo felici di dare una mano. Ecco ciò di cui avremo bisogno.
- Se si sta usando una versione non stabile, si prega prima di effettuare un upgrade e vedere se anche così il problema si ripresenti.
- Assicurarsi che il logging di debug sia attivo (suggerimento:
conf/log4j.properties) e salvare una copia dell'output. - Cercare negli archivi delle mailing list per vedere se qualcun altro abbia segnalato un problema analogo e se sia stata già trovata una soluzione
- Stessa cosa per il sistema di bug tracking.
- Controllare se si riesce a riprodurre l'errore con uno unit test, uno script o un'applicazione.
Infine, postare un messaggio con tutti i dettagli rilevanti nella mailing list (iscrizione richiesta), o collegarsi a IRC (network irc.freenode.net, channel #cassandra) e chiederci aiuto.
Note:
https://c.statcounter.com/9397521/0/fe557aad/1/|stats
- Per saperne di più su come controllare il comportamento degli script di startup, leggere RunningCassandra. ↩