Redis - Python 客户端基本使用指南

概述

参考：python 模块Redis模块，连接Redis数据库

Python 中的 Redis 客户端库允许开发者与 Redis 数据库进行交互。这些库允许在 Python 中连接到 Redis、执行命令以读取或写入数据，并处理 Redis 数据。

以下是一些常见的 Python Redis 客户端库：

• redis 库：是 Python 中最常用的 Redis 客户端库之一。它提供了与 Redis 数据库的高度集成，支持 Python 2.x 和 3.x 版本。它具有易于使用的 API，可以轻松地执行 Redis 命令，例如设置值、获取值、处理列表、集合、有序集合等。

  注：python 的 redis 库支持直连和哨兵模式，但并不支持集群模式，推荐库：redis-py-cluster

  安装命令：pip install redis

• redis-py-cluster 库：是 Python 中的一个用于连接和操作 Redis 集群的客户端库，允许以编程方式连接到 Redis 集群，并执行各种操作，而无需手动管理分片和节点。

  Redis 集群是 Redis 数据库的一种分布式部署方式，通过将数据分片存储在不同的 Redis 实例上来提供高可用性和横向扩展性。

  主要特点和功能：

  • 自动节点发现：允许指定一个或多个节点的初始连接地址，然后会自动发现集群中的其他节点，不需要手动配置每个节点的连接信息。
  • 自动分片：可以自动将操作路由到正确的节点和分片，不需要手动计算分片和维护节点列表。
  • 高可用性：支持 Redis 集群的故障转移和自动重新连接，确保在节点故障或网络问题后的连续可用性。
  • 支持常用 Redis 命令：可以使用执行常见的 Redis 命令，如 SET、GET、HGET、HSET、DEL、INCR、DECR 等。
  • 线程安全：是线程安全的，可以在多线程应用程序中使用。

  安装命令：pip install redis-py-cluster

连接 redis 数据库

单点 | 直连模式

• 同步连接

  连接方法：

  redis.Redis(
      host='localhost', 	# ip地址
      port=6379, 			# 端口
      db=0, 				# 数据库，默认 0
      password=None, 		# 密码
      single_connection_client=False, 	# True时，不使用连接池
      connection_pool=None, 				# 连接池
      decode_responses=False, 			# 默认为False，若设置为True，则在获取数据时将字节解码为字符串(utf-8)
      socket_timeout=None, 				# 响应的时间
      socket_connect_timeout=None, 		# 建立连接超时时间
      retry_on_timeout=False, 			# True时, 命令超时后,将会重试一次, 重试成功则正常返回; 失败则抛出timeout异常；False时直接抛出异常
      retry_on_error=None, 		# 重试错误列表
      max_connections=None, 		# 最大连接数
  )
  

  示例：

  import redis
  
  connect = redis.Redis(host='127.0.0.1', port=6379, decode_responses=True)
  connect.set('test','哈哈哈哈')
  print(connect.get('test'))
  

• 异步连接

  redis.asyncio.Redis() ：异步连接 redis 数据库，参数同 redis.Redis()

  示例：

  import asyncio
  import redis.asyncio as redis
  
  async def run():
      async with redis.Redis(host='127.0.0.1',port=6379,decode_responses=True) as connect:
          await connect.set('test','我是异步')
          result = await connect.get('test')
          print(result)
  
  asyncio.run(run())
  

哨兵模式

• 示例：

  from redis.sentinel import Sentinel
  
  sentinel_nodes = [('192.168.1.110', 16380), ('192.168.1.110', 16381), ('192.168.1.110', 16382)]
  sentinel = Sentinel(sentinel_nodes, sentinel_kwargs={'password': '123456'}, db=0, socket_timeout=0.5)
  master = sentinel.master_for('mymaster', password='123456')
  slave = sentinel.slave_for('mymaster', password='123456')
  print(master.llen('test'))
  

集群模式

• 示例：

  from rediscluster import StrictRedisCluster
  
  redis_nodes = [{'host':'192.168.1.110','port':13790},
                 {'host':'192.168.1.110','port':13791},
                 {'host':'192.168.1.110','port':13793},
                 {'host':'192.168.1.120','port':13794}]
  redisconn = StrictRedisCluster(startup_nodes=redis_nodes, decode_responses=True, password='123456')
  redisconn.set("name", "helloworld")
  print("My name is: ", redisconn.get('name'))
  

redis.connect 常用方法

注：以下方法，异步需要使用 async await

字符串操作

设置值

• set(name, value, ex=None, px=None, nx=False, xx=False) ：设置指定 key 的值
  • name ：键名
  • value ：键对应的值
  • ex ：可选，设置键的过期时间，单位是秒
  • px ：可选，设置键的过期时间，单位是毫秒
  • nx ：可选，默认为 False，如果设置为 True，只有当键不存在时才设置值
  • xx ：可选，默认为 False，如果设置为 True，只有当键已存在时才设置值
• setnx(name, value) ：设置值，只有 name 不存在时，执行设置操作
• setex(name, time, value)) ：设置值
  • time ：过期时间（秒）
• psetex(name, time_ms, value) ：设置值
  • time_ms ：过期时间（毫秒）
• mset({name1:value1, name2:value2, name3:value3, …}) ：批量设置值

获取值、删除值

• get(name) ：获取指定 key 的值

  • name：键名

• mget(name1, name2, name3, …) ：批量获取值

• getrange(name, start, end) ：获取部分值

  • start ：开始 index
  • end ：结束 index，不包含结束 index 的字符

• getset(name,value) ：设置新值，并获取旧值

• *delete(names) ：删除一个或多个 key

  • names ：要删除的键名

其他

• setrange(name, offset, value) ：从指定字符串索引 offset 开始，替换字符串
• append(name, value) ：在原有字符基础上追加字符
• strlen(name) ：返回 name 对应值的字节长度（一个汉字 3 个字节）
• incr(name, amount=1) ：自增 name 对应的值，当 name 不存在时，则创建 name＝amount，否则，则自增
• decr(name, amount=1) ：自减 name 对应的值，当 name 不存在时，则创建 name＝amount，否则，则自减
• incrby(name, amount=1) ：在原有数值基础上加上一定的数值，当 name 不存在时，则创建 name＝amount
• decrby(name, amount=1) ：在原有数值基础上减去一定的数值，当 name 不存在时，则创建 name＝amount
• incrbyfloat(name, amount=1.0) ：自增 name 对应的值，当 name 不存在时，则创建 name＝amount，否则，则自增。
• setbit(name, offset, value) ：对 name 对应值的二进制表示的位进行操作
• getbit(name, offset) ：获取 name 对应的值的二进制表示中的某位的值 （0 或1 ）
• bitcount(key, start=None, end=None) ：获取 name 对应的值的二进制表示中 1 的个数

列表操作

• *lpush(name, values) ：将一个或多个值插入列表头部（左侧）
  • name ：列表名
  • values ：一个或多个值
• *rpush(name, values) ：将一个或多个值插入列表尾部（右侧）
• lpushx(name, value) ：向已有 name 的列表的左边添加元素，没有的话无法创建
• rpushx(name, value) ：向已有 name 的列表的右边添加元素，没有的话无法创建
• linsert(name, where, refvalue, value) ：在name对应的列表的某一个值前或后插入一个新值
  • where ：BEFORE或AFTER
  • refvalue ：标杆值，即：在它前后插入数据
  • value ：要插入的数据
• lset(name, index, value) ：指定索引位置重新赋值
• lrange(name, start, end) ：在 name 对应的列表中取出 start - end 索引之间的值，包含 end
• llen(name) ：获取 name 列表中值的数量
• lindex(index) ：取值（根据索引号取值）
• lpop(name) ：移除并返回列表左侧的第一个元素
• rpop(name) ：移除并返回列表右侧的第一个元素
• *blpop(keys, timeout) ：将多个列表排列，按照从左到右去移除对应列表的元素
• *brpop(keys, timeout) ：将多个列表排列，按照从右到左去移除各个列表内的元素
• rpoplpush(src, dst, timeout ) ：从一个列表取出最右边的元素，同时将其添加至另一个列表的最左边
  • src ：要取数据的列表的 name
  • dst ：要添加数据的列表的 name
• brpoplpush(src, dst, timeout=0) ：从一个列表的右侧移除一个元素并将其添加到另一个列表的左侧
  • timeout ：当src对应的列表中没有数据时，阻塞等待其有数据的超时时间（秒），0 表示永远阻塞
• lrem(name, value, num) ：删除指定的 value，num 为负数时从后向前删除
• ltrim(name, start, end) ：在 name 对应的列表中移除没有在 start - end 索引之间的值

哈希操作

• hset(name, key, value) ：在哈希表中设置字段的值
  • name ：哈希表名
  • key ：字段名
  • value ：字段的值
• hsetnx(name, key, value) ：设置值，只有 name 不存在时，执行设置操作
• hmset(name, {key1:value1, key2:value2, key3:value3, …}) ：批量添加值
• hget(name, key) ：获取哈希表中 key 字段的值
• *hmget(name, keys) ：获取哈希表中一个或多个字段的值
• hgetall(name) ：取出所有的值
• hkeys(name) ：获取所有的 key
• hvals(name) ：获取所有的 value
• hlen(name) ：获取 hash 中键值对的个数
• hstrlen(name, key) ：获取指定 key 值的长度
• *hdel(name, keys) ：删除哈希表中一个或多个字段
• hexists(name, key) ：判断 hash 中 key 是否存在
• hincrby(name, key, amount=1) ：自增自减数（正数自增，负数自减）
• hincrbyfloat(name, key, amount=1.0) ：自增自减浮点数（正浮点数自增，负浮点数自减）
• hscan(name, cursor=0, match=None, count=None) ：取值查看–分片读取
  • cursor ：游标（基于游标分批取获取数据）
  • match ：匹配指定 key，默认 None，表示所有的 key
  • count ：每次分片最少获取个数，默认 None，表示采用 Redis 的默认分片个数
• hscan_iter(name, match=None, count=None) ：利用 yield 封装 hscan 创建生成器，实现分批去 redis 中获取数据
  • match ：匹配指定 key，默认 None，表示所有的key
  • count ：每次分片最少获取个数，默认 None，表示采用 Redis 的默认分片个数

集合操作

• sadd(name, values) ：向集合添加一个或多个元素
  • name ：集合名
  • values ：一个或多个元素
• smembers(name) ：获取集合中的所有元素
• scard(name) ：获取name集合中的个数
• srandmember(namem,num) ：从集合随机取出 num 个元素
• srem(name, values) ：从集合中删除一个或多个元素
• spop(name) ：从集合移除一个成员，并将其返回，说明一下，集合是无序的，所有是随机删除的
• smove(src, dst, value) ：将某个成员从一个集合中移动到另外一个集合
• sismember(name, value) ：检查 value 是否是 name 对应的集合的成员，结果为 True 和 False
• sdiff(keys) ：获取多个集合的差集
• *sdiffstore(dest, keys) ：获取多个集合的差集，并存进一个新的集合
• sinter(keys) ：获取多个集合的交集
• *sinterstore(dest, keys) ：获取多个集合的差集，并存进一个新的集合
• sunion(keys) ：获取多个集合的并集
• *sunionstore(dest, keys) ：获取多个集合的并集，并存进一个新的集合

有序集合操作

• zadd(name, mapping) ：向有序集合添加一个或多个成员

  • name ：有序集合名
  • mapping ：成员及其分数的字典

  其他可选参数：

  • nx ：强制 ZADD 只创建新元素而不更新已经存在的元素的分数。默认 False

  • xx ：强制 ZADD 只更新已经存在的元素的分数存在。不会添加新元素。默认 False

  • ch ：将返回值修改为已更改的元素数。更改的元素包括添加的新元素和元素谁的分数变了。默认 False

  • incr ：修改 ZADD 的行为像 ZINCRBY。默认 False

    在这种模式下，只有 a 可以指定单个元素/分数对，分数是数量现有的分数将增加到。

    使用此模式时 ZADD 的返回值将是元素的新分数。

  • lt ：仅在新分数小于时更新现有元素当前分数。这个标志不会阻止添加新元素。默认 False

  • gt ：仅在新分数大于时更新现有元素当前分数。这个标志不会阻止添加新元素。默认 False

• zrange(name, start, end) ：按分数范围获取有序集合的成员

  • start ：分数的起始值
  • end ：分数的结束值

  其他可选参数：

  • desc ：排序规则，默认按照分数从小到大排序。默认 False
  • withscores ：是否获取元素的分数，默认只获取元素的值。默认 False
  • score_cast_func ：对分数进行数据转换的函数。默认 float

• zrevrange(name, start, end) ：从大到小排序（同 zrange 默认排序，集合是从大到小排序的）

  其他可选参数：

  • withscores ：是否获取元素的分数，默认只获取元素的值 。默认 False
  • score_cast_func ：对分数进行数据转换的函数。默认 float

• zrangebyscore(name, min, max) ：按照分数范围获取 name 对应的有序集合的元素

  • min ：最小值
  • max ：最大值

  其他可选参数：

  • start ：有序集合索引起始位置（非分数）。默认 None
  • num ：获取数量。默认 None
  • withscores ：是否获取元素的分数，默认只获取元素的值 。默认 False
  • score_cast_func ：对分数进行数据转换的函数。默认 float

• zrevrangebyscore(name, max, min, start=None, num=None, withscores=False, score_cast_func=float) ：按照分数范围获取有序集合的元素并排序（默认从大到小排序）

• zscan(name, cursor=0, match=None, count=None, score_cast_func=float) ：获取所有元素

• zscan_iter(name, match=None, count=None, score_cast_func=float) ：获取所有元素–迭代器

• zcard(name) ：获取元素集合中的个数

• *zrem(name, values) ：从有序集合中删除一个或多个成员

• zremrangebyrank(name, min, max) ：根据索引范围删除

• zremrangebyscore(name, min, max) ：根据分数范围删除

• zcount(name, min, max) ：获取 name 对应的有序集合中分数在 [min,max] 之间的个数

• zincrby(name, value, amount) ：自增自减数（正数自增，负数自减）

• zrank(name, value) ：获取索引，按照分数顺序（从小到大）

• zrevrank(name, value) ：获取索引，按照倒序（从大到小）

• zscore(name, value) ：获取对应值的分数

键的相关通用操作

• dbsize() ：返回服务器中的键数
• keys(pattern) ：返回匹配 “pattern” 的键列表，不传返回全部
• scan_iter(match, count) ：返回匹配 match 键迭代器，不传返回全部
• move(name, db) ：将键 name 移动到另一个数据库 db
• flushall(asynchronous=False) ：删除当前主机上所有数据库中的所有键，asynchronous 是否异步
• flushdb(asynchronous=False) ：删除当前数据库中的所有键，asynchronous 是否异步
• dump(name) ：返回存储在指定键处的值的序列化版本
• type(name) ：返回键类型
• rename(src, dst) ：重命名键 src 为 dst
• renamex(src, dst) ：如果 dst 不存在，则将 src 重命名为 dst
• exists(names) ：一个或多个由 “names” 指定的键是是否存在

过期时间

• expire(name, time, nx=False, xx=False, gt=False, lt=False) ：为键 name 设置过期时间
  • time ：过期时间，单位：秒
  • nx ：仅当密钥没有过期时设置过期
  • xx ：仅当密钥已存在过期时才设置过期
  • gt ：仅当新过期时间大于当前过期时间时设置过期时间
  • lt ：仅在新到期时间小于当前到期时间时设置到期时间
• expireat(name, when, nx=False, xx=False, gt=False, lt=False) ：为键 name 设置过期时间
  • when ：可以表示为整数表示 unix 时间或 Python datetime 对象
• pexpire(name, time, nx=False, xx=False, gt=False,lt=False) ：为键 name 设置过期时间
  • time ：过期时间，单位：毫秒
• ttl(name) ：返回键 name 到期前的秒数
• pttl(name) ：返回键 name 到期前的毫秒数
• persist(name) ：删除 name 的过期
• time() ：获取 redis 服务端的当前时间。它返回一个包含两个元素的数组，其中第一个元素是当前时间的秒数（自 Unix 时间戳的起始点以来的秒数），第二个元素是当前时间的微秒数。

连接状态和数据持久化

• close() ：关闭 Redis 连接
• ping() ：判断服务器是否连接成功
• select(index) ：切换数据库
• save() ：持久化数据
• bgsave() ：异步持久化数据
• shutdonw(save=False, nosave=False, now=False, force=False, abort=False) ：如果 Redis 配置了持久化，数据将在关机前被刷新
  • save ：会强制执行 DB 保存操作
  • nosave ：将阻止数据库保存操作，即使有一个或多个保存点配置
  • now ：跳过等待滞后副本，即它绕过了第一步关机顺序
  • force ：忽略任何通常会阻止服务器退出的错误
  • abort ：取消正在进行的关机，不能与其他标志结合使用
• lastsave() ：获取 Redis 数据库中最后一次成功执行持久化操作的时间戳（一个 Python datetime 对象），也就是最后一次生成 RDB 快照的时间。

连接池

• redis.ConnectionPool(option)

  option参数大部分和 redis.Redis 一致

  连接池的原理是，通过预先创建多个连接，当进行 redis 操作时，直接获取已经创建的连接进行操作，而且操作完成后，不会释放，用于后续的其他 redis 操作，这样就达到了避免频繁的 redis 连接创建和释放的目的，从而提高性能。

  redis 模块采用 ConnectionPool 来管理对 redis server 的所有连接

  import redis
  
  pool = redis.ConnectionPool(host='127.0.0.1', port=6379, decode_responses=True)
  connect = redis.Redis(connection_pool=pool)
  connect.set('name','数据库0')
  print(connect.get('name'))
  

• redis.BlockingConnectionPool(option)

  option 参数大部分和 redis.Redis 一致

  BlockingConnectionPool 和 ConnectionPool 功能是一样的，但是是线程安全的，在多线程的环境下，建议用BlockingConnectionPool，比如 gunicorn 使用了多线程的 worker。同时，当所有连接都在使用时，获取可用连接不会抛异常，而是可以设置等待时间。