leveldown
v6.1.1
Reemplazado por classic-level . Consulte las preguntas frecuentes.
db = leveldown(location)db.open([options, ]callback)optionsdb.close(callback)db.put(key, value[, options], callback)optionsdb.get(key[, options], callback)optionsdb.getMany(keys[, options][, callback])db.del(key[, options], callback)optionsdb.batch(operations[, options], callback) (formulario de matriz)db.batch() (forma encadenada)db.approximateSize(start, end, callback)db.compactRange(start, end, callback)db.getProperty(property)db.iterator([options])db.clear([options, ]callback)chainedBatchchainedBatch.put(key, value)chainedBatch.del(key)chainedBatch.clear()chainedBatch.write([options, ]callback)chainedBatch.dbiteratorfor await...of iteratoriterator.next([callback])iterator.seek(key)iterator.end([callback])iterator.dbleveldown.destroy(location, callback)leveldown.repair(location, callback) Este módulo originalmente era parte de levelup , pero luego se extrajo y ahora sirve como una unión independiente para LevelDB.
Se recomienda encarecidamente que use levelup en preferencia a leveldown a menos que tenga razones de rendimiento medibles para hacerlo. levelup está optimizado para la usabilidad y la seguridad. Aunque estamos trabajando para mejorar la seguridad de la interfaz leveldown todavía es fácil bloquear el proceso de su nodo si no hace las cosas de la manera correcta.
Consulte la sección sobre seguridad a continuación para obtener detalles de las operaciones inseguras conocidas con leveldown .
Nuestro objetivo es admitir al menos las liberaciones activas de LTS y Node.js de nodo, Electron 5.0.0, así como cualquier versión futura de nodo.js y electrones gracias a N-API. La versión mínima de nodo para leveldown es 10.12.0 . Por el contrario, para el nodo> = 12, la versión mínima leveldown es 5.0.0 .
El paquete NPM leveldown se envía con binarios prebuilados para plataformas populares de 64 bits, así como ARM, M1, Android y Alpine (Musl) y se sabe que trabaja:
Al instalar leveldown , node-gyp-build verificará si existe un binario compatible y retroceso a un paso de compilación si no es así. En ese caso, necesitará una instalación válida node-gyp .
Si no desea utilizar el binario prebuilt para la plataforma en la que está instalando, especifique el indicador --build-from-source cuando se instale. Uno de:
npm install --build-from-source
npm install leveldown --build-from-source
Si está trabajando en leveldown y desea volver a compilar el código C ++, ejecute npm run rebuild .
leveldown > = 5. Esto se puede verificar ejecutando npm ls leveldown .leveldown a> = 5.3.0 o usar --build-from-source .--build-from-source . Este ya no es el caso.nodejs-mobile Fork. Si está actualizando: consulte UPGRADING.md .
db = leveldown(location) Devuelve una nueva instancia leveldown . location es una cadena que apunta a la ubicación nivelada que se abrirá.
db.open([options, ]callback) Abra la tienda. La función callback se llamará sin argumentos cuando la base de datos se ha abierto con éxito, o con un solo argumento error si la operación abierta falló por algún motivo.
options El argumento options opcionales puede contener:
createIfMissing (boolean, predeterminado: true ): si es true , inicializará una base de datos vacía en la ubicación especificada si aún no existe. Si false y una base de datos no existe, recibirá un error en su devolución de llamada open() y su base de datos no se abrirá.
errorIfExists (boolean, predeterminado: false ): si es true , recibirá un error en su devolución de llamada open() si la base de datos existe en la ubicación especificada.
compression (boolean, predeterminado: true ): si es true , todos los datos compresibles se ejecutarán a través del algoritmo de compresión ágil antes de almacenarse. Snappy es muy rápido y no debería ganar mucha velocidad al deshabilitar, así que deje esto a menos que tenga buenas razones para apagarlo.
cacheSize (número, predeterminado: 8 * 1024 * 1024 = 8MB): el tamaño (en bytes) del caché LRU en memoria con contenido de bloque sin comprimir con frecuencia.
Opciones avanzadas
Las siguientes opciones son para el ajuste avanzado de rendimiento. Modifíquelos solo si puede probar el beneficio real para su aplicación en particular.
writeBufferSize (número, predeterminado: 4 * 1024 * 1024 = 4MB): el tamaño máximo (en bytes) del registro (en la memoria y almacenado en el archivo .log en el disco). Más allá de este tamaño, LevelDB convertirá los datos de registro en el primer nivel de archivos de tabla ordenados. Desde la documentación de LevelDB:Los valores más grandes aumentan el rendimiento, especialmente durante las cargas a granel. Se pueden mantener hasta dos buffers de escritura en la memoria al mismo tiempo, por lo que es posible que desee ajustar este parámetro para controlar el uso de la memoria. Además, un búfer de escritura más grande dará como resultado un tiempo de recuperación más largo la próxima vez que se abra la base de datos.
blockSize (número, predeterminado 4096 = 4K): el tamaño aproximado de los bloques que componen los archivos de la tabla. El tamaño relacionado con los datos no comprimidos (por lo tanto "aproximados"). Los bloques están indexados en el archivo de tabla y las miradas de entrada implican leer un bloque completo y un análisis para descubrir la entrada requerida.
maxOpenFiles (número, predeterminado: 1000 ): el número máximo de archivos que LevelDB puede tener abierto a la vez. Si es probable que su almacén de datos tenga un conjunto de trabajo grande, puede aumentar este valor para evitar la rotación del descriptor de archivos. Para calcular el número de archivos requeridos para su conjunto de trabajo, divida sus datos totales por 'maxFileSize' .
blockRestartInterval (número, predeterminado: 16 ): el número de entradas antes de reiniciar la "codificación delta" de las claves dentro de los bloques. Cada punto de "reiniciar" almacena la clave completa para la entrada, entre reinicios, se omite el prefijo común de las teclas para esas entradas. Los reinicios son similares al concepto de fotogramas clave en la codificación de video y se utilizan para minimizar la cantidad de espacio requerido para almacenar las claves. Esto es particularmente útil cuando se usa una profunda compensación / prefijo de nombres en sus claves.
maxFileSize (número, predeterminado: 2* 1024 * 1024 = 2mb): la cantidad máxima de bytes para escribir a un archivo antes de cambiar a uno nuevo. Desde la documentación de LevelDB:
... Si su sistema de archivos es más eficiente con archivos más grandes, podría considerar aumentar el valor. La desventaja será compacciones más largas y, por lo tanto, la latencia más larga/hipo de rendimiento. Otra razón para aumentar este parámetro podría ser cuando inicialmente está llenando una gran base de datos.
db.close(callback) close() es un método de instancia en un objeto de base de datos existente. La base de datos nivelada subyacente se cerrará y se llamará a la función callback sin argumentos si la operación es exitosa o con un solo argumento error si la operación falló por algún motivo.
leveldown espera a que termine cualquier operación pendiente antes de cerrar. Por ejemplo:
db . put ( 'key' , 'value' , function ( err ) {
// This happens first
} )
db . close ( function ( err ) {
// This happens second
} )db.put(key, value[, options], callback)Almacene una nueva entrada o sobrescriba una entrada existente.
Los objetos key y value pueden ser cadenas o buffers. Otros tipos de objetos se convierten en cadenas con el método toString() . Las teclas pueden no ser null o undefined y los objetos convertidos con toString() no deberían dar como resultado una cuerda vacía. Los valores pueden no ser null o undefined . Los valores de '' , [] y Buffer.alloc(0) (y cualquier objeto que resulte en una toString() de uno de estos) se almacenará como una matriz de caracteres de longitud cero y, por lo tanto, se recuperará como '' o Buffer.alloc(0) dependiendo del tipo solicitado.
Se atiende un conjunto más rico de tipos de datos en levelup .
options La única propiedad actualmente disponible en el objeto options es sync (boolean, predeterminado: false ) . Si proporciona un valor de sync de true en su objeto options , LevelDB realizará una escritura sincrónica de los datos; Aunque la operación será asíncrona en lo que respecta al nodo. Normalmente, LevelDB pasa los datos al sistema operativo para escribir y devuelve de inmediato, sin embargo, una escritura sincrónica usará fsync() o equivalente para que su devolución de llamada no se active hasta que los datos estén realmente en el disco. Las escrituras del sistema de archivos sincrónicos son significativamente más lentas que las escrituras asíncronas, pero si desea estar absolutamente seguro de que los datos están enjuagados, entonces puede usar { sync: true } .
La función callback se llamará sin argumentos si la operación es exitosa o con un solo argumento error si la operación falló por algún motivo.
db.get(key[, options], callback) Obtenga un valor de la tienda LevelDB por key .
El objeto key puede ser una cadena o un búfer y no puede ser undefined o null . Otros tipos de objetos se convierten en cadenas con el método toString() y la cadena resultante puede no ser una longitud cero. Se atiende un conjunto más rico de tipos de datos en levelup .
Los valores obtenidos a través de get() que se almacenan como matrices de caracteres de longitud cero ( null , undefined , '' , [] , Buffer.alloc(0) ) volverán como String vacía ( '' ) o Buffer.alloc(0) cuando se obtenga con asBuffer: true (ver abajo).
options El objeto options opcionales puede contener:
asBuffer (booleano, predeterminado: true ): se usa para determinar si debe devolver el value de la entrada como una cadena o un búfer. Tenga en cuenta que la conversión de un búfer a una cadena incurre en un costo, por lo que si necesita una cadena (y el value puede convertirse legítimamente en una cadena UTF8), debe obtenerlo como uno con { asBuffer: false } y evitará este costo de conversión.fillCache (boolean, predeterminado: true ): LevelDB llenará de forma predeterminada el caché LRU en memoria con datos de una llamada para obtener. Deshabilitar esto se hace configurando fillCache en false . La función callback se llamará con un solo error si la operación falló por algún motivo, incluso si no se encontró la clave. Si tiene éxito, el primer argumento será null y el segundo argumento será el value como una cadena o búfer dependiendo de la opción asBuffer .
db.getMany(keys[, options][, callback]) Obtenga múltiples valores de la tienda por una variedad de keys . El objeto options opcionales puede contener asBuffer y fillCache , como se describe en get() .
La función callback se llamará con un Error si la operación falló por algún motivo. Si tiene éxito, el primer argumento será null y el segundo argumento será una matriz de valores con el mismo orden que keys . Si no se encontró una clave, el valor relevante estará undefined .
Si no se proporciona una devolución de llamada, se devuelve una promesa.
db.del(key[, options], callback) Eliminar una entrada. El objeto key puede ser una cadena o un búfer y no puede ser undefined o null . Otros tipos de objetos se convierten en cadenas con el método toString() y la cadena resultante puede no ser una longitud cero. Se atiende un conjunto más rico de tipos de datos en levelup .
options La única propiedad actualmente disponible en el objeto options es sync (boolean, predeterminado: false ) . Consulte db.put() para obtener detalles sobre esta opción.
La función callback se llamará sin argumentos si la operación es exitosa o con un solo argumento error si la operación falló por algún motivo.
db.batch(operations[, options], callback) (formulario de matriz) Realice múltiples operaciones PUT y/o Del a granel. El argumento operations debe ser una Array que contenga una lista de operaciones que se ejecutarán secuencialmente, aunque en su conjunto se realizan como una operación atómica.
Cada operación está contenida en un objeto que tiene las siguientes propiedades: type , key , value , donde el type es 'put' o 'del' . En el caso de 'del' se ignora la propiedad value .
Cualquier entrada en la que la key o el value (en el caso de 'put' ) sea null o undefined hará que se devuelva un error en la callback . Cualquier entrada en la que el type sea 'put' que tenga un value de [] , '' o Buffer.alloc(0) se almacenará como una matriz de caracteres de longitud cero y, por lo tanto, se obtendrá durante las lecturas como '' o Buffer.alloc(0) dependiendo de cómo se soliciten. Vea levelup para la documentación completa sobre cómo funciona esto en la práctica.
El argumento options opcionales puede contener:
sync (boolean, predeterminado: false ). Consulte db.put() para obtener detalles sobre esta opción. La función callback se llamará sin argumentos si el lote es exitoso o con un Error si el lote falló por algún motivo.
db.batch() (forma encadenada) Devuelve una nueva instancia chainedBatch .
db.approximateSize(start, end, callback) approximateSize() es un método de instancia en un objeto de base de datos existente. Se utiliza para obtener el número aproximado de bytes del espacio del sistema de archivos utilizado por el rango [start..end) . El resultado puede no incluir datos escritos recientemente.
Los parámetros start y end pueden ser cadenas o amortiguadores que representan claves en la tienda LevelDB.
La función callback se llamará con un solo error si la operación falló por algún motivo. Si tiene éxito, el primer argumento será null y el segundo argumento será el tamaño aproximado como un número.
db.compactRange(start, end, callback) compactRange() es un método de instancia en un objeto de base de datos existente. Se utiliza para activar manualmente una compactación de la base de datos en el rango [start..end) .
Los parámetros start y end pueden ser cadenas o amortiguadores que representan claves en la tienda LevelDB.
La función callback se llamará sin argumentos si la operación es exitosa o con un solo argumento error si la operación falló por algún motivo.
db.getProperty(property) getProperty se puede usar para obtener detalles internos de LevelDB. Cuando se emite una cadena de propiedad válida, se devolverá una cadena legible (este método es sincrónico).
Actualmente, las únicas propiedades válidas son:
leveldb.num-files-at-levelN : devuelva el número de archivos en el nivel n , donde n es un entero que representa un nivel válido (por ejemplo, "0").
leveldb.stats : Devuelve una cadena de múltiples líneas que describe estadísticas sobre la operación interna de LevelDB.
leveldb.sstables : Devuelve una cadena de múltiples líneas que describe todos los sstables que componen el contenido de la base de datos actual.
db.iterator([options]) Devuelve una nueva instancia iterator . Acepta las siguientes opciones de rango:
gt (mayor que), gte (mayor o igual) definen el límite inferior del rango a ser iterado. Solo las entradas donde la clave es mayor que (o igual a) esta opción se incluirá en el rango. Cuando reverse=true el orden se invirtería, pero las entradas iteradas serán las mismas.lt (menos que), lte (menor o igual) definen el límite más alto del rango a ser iterado. Solo las entradas donde la clave es menor (o igual a) esta opción se incluirá en el rango. Cuando reverse=true el orden se invirtería, pero las entradas iteradas serán las mismas.reverse (booleano, predeterminado: false ) : iterador de entradas en orden inverso. Tenga en cuenta que una búsqueda inversa puede ser más lenta que una búsqueda hacia adelante.limit (número, predeterminado: -1 ) : Limite el número de entradas recopiladas por este iterador. Este número representa un número máximo de entradas y no se puede alcanzar si llega al final del rango primero. Un valor de -1 significa que no hay límite. Cuando reverse=true las entradas con las teclas más altas se devolverán en lugar de las claves más bajas. Además de las opciones de rango, iterator() toma las siguientes opciones:
keys (boolean, predeterminado: true ) : si debe devolver la clave de cada entrada. Si se establece en false , las llamadas a iterator.next(callback) producirán claves con un valor de undefined . Hay una pequeña ganancia de eficiencia si, en última instancia, no le importa cuáles son las claves, ya que no necesitan ser convertidas y copiadas en JavaScript.values (booleano, predeterminado: true ) : si debe devolver el valor de cada entrada. Si se establece en false , las llamadas a iterator.next(callback) producirán valores con un valor de undefined .keyAsBuffer (boolean, predeterminado: true ) : si debe devolver la clave de cada entrada como un búfer o cadena. La conversión de un búfer a una cadena incurre en un costo, por lo que si necesita una cadena (y la key puede convertirse legítimamente en una cadena UTF8), debe obtenerla como una sola.valueAsBuffer (boolean, predeterminado: true ) : si debe devolver el valor de cada entrada como un búfer o cadena.fillCache (boolean, predeterminado: false ): si el Cache LRU de LevelDB debe llenarse con datos de lectura. 1 leveldown devuelve una cadena vacía en lugar de undefined en este momento.
db.clear([options, ]callback)Elimine todas las entradas o un rango. No se garantiza que sea atómico. Acepta las siguientes opciones de rango (con las mismas reglas que en los iteradores):
gt (mayor que), gte (mayor o igual) definen el límite inferior del rango a eliminar. Solo las entradas donde la clave es mayor que (o igual a) esta opción se incluirá en el rango. Cuando reverse=true el orden se invertirá, pero las entradas eliminadas serán las mismas.lt (menos que), lte (menor o igual) definen el límite más alto del rango a eliminar. Solo las entradas donde la clave es menor (o igual a) esta opción se incluirá en el rango. Cuando reverse=true el orden se invertirá, pero las entradas eliminadas serán las mismas.reverse (booleano, predeterminado: false ) : eliminar entradas en orden inverso. Solo efectivo en combinación con limit , para eliminar las últimas n entradas.limit (número, predeterminado: -1 ) : limite el número de entradas que se eliminarán. Este número representa un número máximo de entradas y no se puede alcanzar si llega al final del rango primero. Un valor de -1 significa que no hay límite. Cuando reverse=true las entradas con las teclas más altas se eliminarán en lugar de las claves más bajas. Si no se proporcionan opciones, se eliminarán todas las entradas. La función callback se llamará sin argumentos si la operación fue exitosa o con un Error si falló por algún motivo.
chainedBatchchainedBatch.put(key, value) Cola una operación put en este lote. Esto puede lanzar si key o value no es válido, siguiendo las mismas reglas que el formulario de matriz de db.batch() .
chainedBatch.del(key) Cola de del operación del lote. Esto puede lanzar si key no es válida.
chainedBatch.clear()Borre todas las operaciones en cola en este lote.
chainedBatch.write([options, ]callback)Comprometer las operaciones en cola para este lote. Todas las operaciones se escribirán atómicamente, es decir, todas tendrán éxito o fallarán sin compromisos parciales.
El argumento options opcionales puede contener:
sync (boolean, predeterminado: false ). Consulte db.put() para obtener detalles sobre esta opción. La función callback se llamará sin argumentos si el lote es exitoso o con un Error si el lote falló por algún motivo. Después de que se haya llamado a write , no se permiten más operaciones.
chainedBatch.db Una referencia a la db que creó este lote encadenado.
iterator Un iterador le permite iterar toda la tienda o una gama. Funciona en una instantánea de la tienda, creada en el momento en que se llamó db.iterator() . Esto significa que las lecturas en el iterador no se ven afectadas por escrituras simultáneas.
Los iteradores se pueden consumir for await...of o llamando manualmente iterator.next() en sucesión. En el último modo, iterator.end() siempre debe llamarse. Por el contrario, terminar, lanzar o romper desde un for await...of loop automáticamente llama iterator.end() .
Un iterador alcanza su final natural en las siguientes situaciones:
iterator.seek() estaba fuera de alcance. Un iterador realiza un seguimiento de cuando un next() está en progreso y cuando se ha llamado a un end() para que no permita las llamadas concurrentes next() , sí permite end() mientras que un next() está en progreso y no permite que se llame next() o end() después de end() .
for await...of iterator Produce matrices que contienen una key y value . El tipo de key y value depende de las opciones pasadas a db.iterator() .
try {
for await ( const [ key , value ] of db . iterator ( ) ) {
console . log ( key )
}
} catch ( err ) {
console . error ( err )
} iterator.next([callback]) Avance el iterador y obtenga la entrada en esa clave. Si se produce un error, la función callback se llamará con un Error . De lo contrario, la callback recibe null , una key y un value . El tipo de key y value depende de las opciones pasadas a db.iterator() . Si el iterador ha alcanzado su final natural, tanto key como value estarán undefined .
Si no se proporciona una devolución de llamada, se devuelve una promesa para una matriz (que contiene una key y value ) o undefined si el iterador alcanzó su final natural.
Nota: Siempre llame iterator.end() , incluso si recibió un error e incluso si el iterador alcanzó su final natural.
iterator.seek(key) Busque el iterador en una clave dada o la clave más cercana. Las llamadas posteriores a iterator.next() producirán entradas con claves iguales o mayores que target , o igual o menor que target si la opción reverse pasada a db.iterator() era verdadera. Lo mismo se aplica a las llamadas implícitas iterator.next() en A for await...of bucle.
Si las opciones de rango como gt se pasaron a db.iterator() y target no cae dentro de ese rango, el iterador alcanzará su final natural.
iterator.end([callback]) Finalizar la iteración y liberar recursos subyacentes. La función callback se llamará sin argumentos sobre el éxito o con un Error si la finalización falló por algún motivo.
Si no se proporciona una devolución de llamada, se devuelve una promesa.
iterator.db Una referencia a la db que creó este iterador.
leveldown.destroy(location, callback) Elimine completamente un directorio de base de datos LevelDB existente. Puede usar esta función en lugar de un directorio completo rm si desea asegurarse de eliminar solo los archivos relacionados con LevelDB. Si el directorio solo contiene archivos nivelados, el directorio en sí también se eliminará. Si hay archivos adicionales que no son de nivel en el directorio, esos archivos y el directorio se dejarán solo.
La devolución de llamada se llamará cuando se complete la operación de destrucción, con un posible argumento error .
leveldown.repair(location, callback)Intente una restauración de una tienda dañada de LevelDB. Desde la documentación de LevelDB:
Si no se puede abrir un DB, puede intentar llamar a este método para resucitar la mayor cantidad posible del contenido de la base de datos. Se pueden perder algunos datos, así que tenga cuidado al llamar a esta función en una base de datos que contiene información importante.
Encontrará información sobre la operación de reparación en el archivo de registro dentro del directorio de la tienda.
Una repair() también se puede utilizar para realizar una compactación del registro de nivel LevelDB en los archivos de la tabla.
La devolución de llamada se llamará cuando se complete la operación de reparación, con un posible argumento error .
Actualmente, leveldown no rastrea el estado de la instancia de nivel Subyacente. Esto significa que llamar open() en una base de datos ya abierta puede resultar en un error. Del mismo modo, llamar a cualquier otra operación en una base de datos no abierta puede resultar en un error.
levelup actualmente rastrea y administra el estado y evitará que las operaciones fuera del estado se envíen a leveldown . Si usa leveldown directamente, debe rastrear y administrar el estado para usted.
leveldown expone una característica de LevelDB llamada Snapshots. Esto significa que cuando realiza, por ejemplo, createReadStream y createWriteStream al mismo tiempo, cualquier datos modificados por el flujo de escritura no afectará los datos emitidos por el flujo de lectura. En otras palabras, una instantánea de nivel LevelDB captura el último estado en el momento en que se creó la instantánea, lo que permite que la instantánea iterar o leer los datos sin ver ninguna escritura posterior. Cualquier lectura que no realice una instantánea utilizará implícitamente el último estado.
Puede abrir un problema en el repositorio de GitHub si tiene una pregunta.
Los canales de soporte pasados y ya no activos incluyen el canal ##leveldb IRC en FreeNode y el Grupo Node.js LevelDB Google.
Level/leveldown es un proyecto de código abierto . Esto significa que:
Las personas que hacen contribuciones significativas y valiosas reciben acceso de compromiso al proyecto para contribuir como mejor les parezca. Este proyecto es más como un wiki abierto que un proyecto de código abierto estándar guardado.
Consulte la Guía de contribución para obtener más detalles.
Este proyecto usa submódulos Git. Esto significa que debe clonarlo de manera recursiva si está planeando trabajar en ello:
$ git clone --recurse-submodules https://github.com/Level/leveldown.gitAlternativamente, puede inicializar submódulos dentro de la carpeta clonada:
$ git submodule update --init --recursivenpm version ..git push --follow-tags./prebuilds : npm run download-prebuildsnpm run test-prebuildcanadian-pubnpm publish Apóyanos con una donación mensual en Open Collective y ayúdanos a continuar nuestro trabajo.
MIT
leveldown se basa en el excelente trabajo de los equipos LevelDB y Snappy de Google y contribuyentes adicionales. LevelDB y Snappy se emiten bajo la nueva licencia BSD. Una gran parte del soporte de Windows leveldown proviene del puerto Windows LevelDB (archivado) por Krzysztof Kowalczyk ( @kjk ). Si estás usando leveldown en Windows, ¡deberías darle tu agradecimiento!
