Quick links: Content - sections - sub sections
EN FR
Developer manual
Jelix 1.8.1

Chapter: jKVDb: accessing to key/value databases

« jDb: accessing to SQL database ^ Jelix components jUrl: automatic urls »
Switch to language: FR

− Table of content

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

You have a jKVDb from which you retrieve a connector to a key-value database. Like jDb, there are some "profiles", stored in the profiles.ini.php file (See 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, 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 jKVDriver.

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

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

Other specific operations

Some drivers can implement additional methods, depending of the capabilities of the database. One of this interface is 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 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:


[jkvdb:mymemcacheserver]
driver=memcache
host=localhost

Or with several servers:


[jkvdb:mymemcacheserver]
driver=memcache

host=memcache_server1:11211;memcache_server2:11212

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

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

This driver supports the jIKVttl interface.

redis

This driver allows to access to a Redis database.

In fact, there are two plugins:

  • "redis_ext": it uses the API of the PHP extension Redis (plugin introduced into Jelix 1.6.14)
  • "redis_php": it uses a pure PHP class, PHPRedis to communicate with Redis. (this plugin was named "redis" before Jelix 1.6.14). This plugin is available separatly, by installing the Composer package "jelix/php-redis-plugin".

For the configuration, indicate a host and a port parameter.


[jkvdb:myredis]
driver=redis_ext
host = localhost
port = 6379

This driver supports the jIKVttl interface.

Since Jelix 1.6.8, it supports also these parameters:

  • db : the database number in Redis (0 by default)
  • key_prefix : a prefix which will be added on each key
  • key_prefix_flush_method: the method to delete keys when a prefix is indicated.

If you indicate a prefix, all keys you indicate to jKvDb will be prefixed by the key_prefix value into the Redis database.

Moreover, when the jkvdb database is asked to be flushed, only keys having the prefix will be deleted. However, because of how Redis is working, it may be very slow, and then "freeze" your application.

So the plugin implements different methods to do the flush in this case. You indicate the method into the key_prefix_flush_method parameter:

  • direct : keys are deleted directly. This is the default behavior, but should not use it if you know that your database could have hundred keys.
  • jkvdbredisworker : the deletion will be made asynchronously by a worker or a cron script. See details below.
  • event : if you want an other behavior, you should implement it (and it is better if it is an asynchronous process). Then you can notify your implementation by listening the jKvDbRedisFlushKeyPrefix event jEvent. This event contains the profile name and the prefix of keys to delete.

How is the jkvdbredisworker method working?

When a flush is asked, the plugin only stores the prefix into a Redis list, named jkvdbredisdelkeys. A worker (a process that run aside the web server) or a cron script (a script that is launched by the server periodically), should then remove these prefixes from the list and delete corresponding keys.

You have an example of a such worker in lib/jelix/core-modules/jelix/controller/redisworker.cmdline.php. You can launch it with systemd/sysinit/supervisord for example. The command is: php myapp/console.php jkvdb:redis:delete <profile>. Replace <profile> by the profile name of jKvDb. It waits after incoming prefixes in the list, and delete corresponding keys. If you launch it by hand on the command line, just hit <ctrl>+C to stop it.

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:


CREATE TABLE mykvdbtable (
k_key VARCHAR( 50 ) NOT NULL ,
k_value longblob NOT NULL ,
k_expire DATETIME NOT NULL ,
PRIMARY KEY (k_key)
);

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

This driver supports the 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 var/kvfiles/.
  • file_locking: false to disable file locking. By default: true.
  • automatic_cleaning_factor: indicate the frequency to clean deprecated files. 0 means never, 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 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 temp/filekv/.

You must use it only for temporary values.

« jDb: accessing to SQL database ^ Jelix components jUrl: automatic urls »
Switch to language: FR
This manual is distributed under the terms of licence Creative Commons by-nc-sa 3.0. Therefore you're allowed to copy, modify and distribute and transmit it publicly under the following conditions: Attribution, Noncommercial, Share Alike.