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

Chapter: jKVDb: accessing to key/value databases

« jDb: accessing to SQL database ^ Jelix components Write your own business classes »
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 witch you retrieve a connector to a key-value database. Like jDb, there are some "profiles", stored in a file, kvprofiles.ini.php, 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, kvprofiles.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.

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 accessing and modifying to 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.
  • 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 additionnal methods, depending of the capabilites of the database. One of this interface is jIKVttl, where values have a limited live time.

To store such values, you should call the method 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 use 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:


[mymemcacheserver]
driver=memcache
host=localhost

Or with several servers:


[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. It uses the library php5redis. For the configuration, indicate a host and a port parameter.


[myredis]
driver=redis
host = localhost
port = 6379

This driver supports the 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:


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 less 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 Write your own business classes »
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.