kvdb.gtw

~~LANG:FR@frman:kvdb~~

Jelix has an abstract layer to access to key-value databases, less complex than SQL databases.

You have a @@C@jKVDb@@ from which you retrieve a connector to a key-value database. Like jDb, there are some "profiles", stored in the @@F@profiles.ini.php@@ file (See [[config#the-profiles.ini.php-file|the corresponding chapter]]), where you define parameters to connect to these databases.

jKVDb works with some "drivers" to access to "key-value" data. Jelix provides drivers for simple files (file and file2), memcache, redis, and... sql. See below for more informations about this drivers.


===== Configuration =====

As for jDb, @@F@profiles.ini.php@@ contains some section, one for each databases you want to access. Each section should contain at least, one parameter, @@driver@@, indicating the name of the driver to use. Other parameters should be set, depending on the driver.

The connection type to indicate in profile names is @@jkvdb@@.


===== Accessing to a database =====

You must call @@jKVDb::getConnection()@@, by giving eventually a profile (else the profile "default" is used). You retrieve an object inheriting from @@C@jKVDriver@@.

With this object, you can access and modify the content of the key-value database. Here are some methods you can call:


   * @@M@get($key)@@: to retrieve the value corresponding to the given key.
   * @@M@set($key, $value)@@: to store a new value or modify an existing value
   * @@M@insert($key, $value)@@: to store a new value. return false if the key already exists
   * @@M@replace($key,$value)@@: to change the value of the corresponding key. If the key doesn't exist, it returns false.
   * @@M@delete($key)@@: delete the given key-value
   * @@M@flush()@@: delete all keys
   * @@M@append($key, $value)@@: append a string to an existing key value
   * @@M@prepend($key, $value)@@: prepend a string to an existing key value
   * @@M@increment($key)@@: increment the value. You can indicate also the value of the incrementation
   * @@M@decrement($key)@@: decrement the value. You can indicate also the value of the decrementation

===== Other specific operations =====

Some drivers can implement additionnal methods, depending of the capabilites of the database. One of this interface is @@I@jIKVttl@@, where values have a limited life time.

To store such values, you should call the method @@M@setWithTtl($key, $value, $ttl)@@, where $ttl must be a value in seconds.

You can call also the @@M@garbage@@ method to delete all keys which are not anymore valid.


===== Drivers =====

==== memcache ====

It uses the Memcache API of PHP (don't confuse with the other API, memcached). It supports only the version 3.0.1 of memcache or lower.

In the profile, you have to indicate a host and a port, or several host/port. Example with a single server:

<code ini>
[jkvdb:mymemcacheserver]
driver=memcache
host=localhost
</code>

Or with several servers:

<code ini>
[jkvdb:mymemcacheserver]
driver=memcache

host=memcache_server1:11211;memcache_server2:11212

; or:
host[]=memcache_server1:11211
host[]=memcache_server2:11212

</code>

You can also set the parameter @@compress=1@@, so values will be compressed during the storage.


This driver supports the @@I@jIKVttl@@ interface.

==== redis ====

This driver allows to access to a Redis database. It uses the library php5redis. For the configuration, indicate a @@host@@ and a @@port@@ parameter.

<code ini>
[jkvdb:myredis]
driver=redis
host = localhost
port = 6379
</code>

This driver supports the @@I@jIKVttl@@ interface.


==== db ====

It allows to use a SQL table as a storage for key-values. In the configuration, you must indicate:

  * @@table@@: the name of the table to use
  * @@dbprofile@@: the name of the jDb profile to use to access to the sql database.

The table should contain three fields, with specific field names and types. here is a SQL script to create such tables:

<code sql>
CREATE TABLE mykvdbtable (
k_key VARCHAR( 50 ) NOT NULL ,
k_value longblob NOT NULL ,
k_expire DATETIME NOT NULL ,
PRIMARY KEY (k_key)
);
</code>

You can have several tables, to avoid conflict between all modules which use jKVDb.


This driver supports the @@I@jIKVttl@@ interface.


==== file ====

It stores values in files. Each file content one value. Configuration:

   * @@storage_dir@@: the directory where files are stored. Can contain shortcuts like "var:" or "temp:". default dir is @@F@var/kvfiles/@@.
   * @@file_locking@@: false to disable file locking. By default: true. 
   * @@automatic_cleaning_factor@@: indicate the frequency to clean deprecated files. @@L@0@@ means never, @@L@1@@ means at each access, higher means a lower frequency.
   * @@directory_level@@: if you know that you'll have thousand values, you can increase the directory level. By default: 2.
   * @@directory_umask@@: umask of created directories. By default: 0700
   * @@file_umask@@: umask of created files. By default: 0600.

This driver supports the @@I@jIKVttl@@ interface.

==== file2 ====

It is a driver similar to the "file" driver, but it is less sophisticated. It has no configuration parameters and store files into @@F@temp/filekv/@@.

You must use it only for temporary values.