{"id":16337635,"url":"https://github.com/kstep/fusqlfs","last_synced_at":"2025-09-15T00:20:03.571Z","repository":{"id":910290,"uuid":"669939","full_name":"kstep/fusqlfs","owner":"kstep","description":"FusqlFS is a Fuse file system to mount DB and manage it.","archived":false,"fork":false,"pushed_at":"2019-04-12T15:40:34.000Z","size":487,"stargazers_count":14,"open_issues_count":9,"forks_count":2,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-07-06T15:46:01.712Z","etag":null,"topics":["db","fuse-filesystem","perl"],"latest_commit_sha":null,"homepage":"","language":"Perl","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kstep.png","metadata":{"files":{"readme":"README.pod","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2010-05-16T20:29:24.000Z","updated_at":"2025-05-27T22:53:40.000Z","dependencies_parsed_at":"2022-08-16T11:25:19.788Z","dependency_job_id":null,"html_url":"https://github.com/kstep/fusqlfs","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/kstep/fusqlfs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kstep%2Ffusqlfs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kstep%2Ffusqlfs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kstep%2Ffusqlfs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kstep%2Ffusqlfs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kstep","download_url":"https://codeload.github.com/kstep/fusqlfs/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kstep%2Ffusqlfs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":275186191,"owners_count":25420087,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-14T02:00:10.474Z","response_time":75,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["db","fuse-filesystem","perl"],"created_at":"2024-10-10T23:47:35.861Z","updated_at":"2025-09-15T00:20:03.541Z","avatar_url":"https://github.com/kstep.png","language":"Perl","funding_links":[],"categories":[],"sub_categories":[],"readme":"=head1 NAME\n\nfusqlfs - FUSE file system to mount DB and provide tools to control and admin it\n\n=head1 SYNOPSIS\n\nfusqlfs [options] database directory\n\n=head1 EXAMPLES\n\n    fusqlfs dbname ./mnt\n    fusqlfs --host=localhost --port=5432 --engine=PgSQL --user=postgres --password=12345 dbname ./mnt\n    fusqlfs --database=dbname --user=postgres --mountpoint=./mnt\n    fusqlfs -d dbname -m ./mnt -u postgres -p 12345 -e PgSQL\n\n=head1 OPTIONS\n\n=head2 Basic options\n\n=over\n\n=item B\u003c--host, -h\u003e\n\nHost name to connect, defaults to localhost.\n\n=item B\u003c--port, -P\u003e\n\nPort number to connect to, default depends on database engine in use.\n\n=item B\u003c--user, -u\u003e\n\nUsername to authorize.\n\n=item B\u003c--password, -p\u003e\n\nPassword to authorize.\n\n=item B\u003c--database, --db, -d\u003e\n\nDatabase name to connect to. Mandatory.\n\n=item B\u003c--mountpoint, -m\u003e\n\nMointpoint, must be an empty directory. Mandatory.\n\n=item B\u003c--engine, -e\u003e\n\nDB engine to use. Can be either PgSQL or MySQL for now. PgSQL is really\nimplemented, MySQL is in my todo list. Defaults to PgSQL.\n\n=back\n\n=head2 Other options with values\n\n=over\n\n=item B\u003c--logfile, -l\u003e\n\nFilename to store debug output to in daemon mode. Doesn't have any meaning in\nforeground mode, as all debug output are sent to STDERR in this case.\nDefault is don't store debug data anywhere.\nThis option has sense only with L\u003c/--daemon\u003e option set and at least one\nL\u003c--debug|/--debug, -D\u003e option in command line.\n\n=item B\u003c--charset, -C\u003e\n\nDefault charset, used for tables creation, results display etc.\nDefaults to current locale's charset.\n\n=item B\u003c--fnsep, -s\u003e\n\nFile name fields separator, used to compose filenames out from multi-field\nprimary keys. If you have table with primary key like (obj_id, name), every\nrecord in DB will be visible as a file with its name composed of this two\nfields (like \"12.odrie\", \"43.nanny\" etc.) This option's value is used as a\nseparator to glue field values together. Defaults to single dot (.). You may\nwish to change it if you have table with text fields in primary key with a dot\nin them.\n\nFor tables without primary keys, see L\u003c--namemap|/--namemap, -n\u003e options below.\n\n=item B\u003c--namemap, -n\u003e\n\nTable-to-fields map to format filenames for data rows.\nNormally data records filenames are composed from primary key fields\nconcatenated with fields separator (see L\u003c--fnsep|/--fnsep, -s\u003e option\nabove). But sometimes you can have tables without primary keys, so\nthis algorithm will not work and you won't be able to look inside such\ntables data. To enable data lookup feature for such tables you can\nuse B\u003c--namemap\u003e options. This option can be repeated multiple times,\neach B\u003c--namemap\u003e option defines single table-to-fields mapping in format:\nC\u003ctablename:fieldname1,fieldname2,...,fieldnamen\u003e, so this fields list\nwill be used for given table instead of primary key fields.\n\nFor example there're a lot of tables without primary keys in C\u003cINFORMATION_SCHEMA\u003e\ndatabase of MySQL, but mounting this system database can be very helpful\nto look inside MySQL schema definitions. You can use the following command\nto mount C\u003cINFORMATION_SCHEMA\u003e and be able to review C\u003cTABLES\u003e table\nwith tables metadata:\n\n    fusqlfs --engine mysql --host localhost --database information_schema --mountpount ~/mnt/db --namemap TABLES:TABLE_SCHEMA,TABLE_NAME\n\nA few notices: 1) table and field names in these mappings are case sensitive,\nif you put C\u003c--namemap tables:table_schema,table_name\u003e option into command\nabove you would end up with empty data directory for C\u003cTABLES\u003e table, 2)\nthe field names per table you provide must identify each table row in a\nunique way (i.e. be real primary key, even if not marked so with C\u003cPRIMARY KEY\u003e\nin table definition), otherwise you will get unexpected behavior (for\ninstance, you won't be able to edit each row consistently, as what \"file\"\nyou read may not match the \"file\" you write to, so you can clobber your\ndata in no time).\n\n=item B\u003c--limit, -L\u003e\n\nInteger, number of data rows to show in table's data subdir, defaults to 0\n(means all rows). Useful if you are going to browse really big databases, as\nlisting all data records as files can be very slow and memory consuming.\n\nYou can also try to change and tune your cache strategy with\nL\u003c--cache|/--cache, -c\u003e and L\u003c--cache-limit|/--cache-limit, -M\u003e options (see\nbelow).\n\nIf this is an issue for you, use this option to limit number of listed table\nrows. You can still get record by requesting filename equal to primary key\nvalue (id usually) directly, if you know it, even if you don't see it in\ndirectory listing.\n\n=item B\u003c--cache, -c\u003e\n\nCache strategy to choose. There're three strategies for now (in order of speed\ndecreasing):\n\n=over\n\n=item memory\n\nstore everything in memory, fastest but can be overkill for your\nmemory in case of big databases,\n\n=item limited\n\nlike memory, but number of stored elements is limited to some defined value,\nand cache is cleared down to this limit if it's exceeded (least used entries\nremoved first); good if you have limited memory space (see\nL\u003cFusqlFS::Cache::Limited\u003e for details),\n\n=item file\n\nstore some data in files, good if you are going to work with really big\ndatabases, e.g. with large blobs (see L\u003cFusqlFS::Cache::File\u003e for details).\n\n=back\n\nFor details see L\u003c--cache-limit|/--cache-limit, -M\u003e option description below.\n\n=item B\u003c--cache-limit, -M\u003e\n\nInteger, threshold for cache strategy (see L\u003c--cache|/--cache, -c\u003e option\nfor details), defaults to 0, which means back up to \"memory\" strategy. Meaning\ndepends on chosen cache strategy.\n\nFor \"limited\" cache strategy it means number of max cache items to store. If\nnumber of cached items exceeds this value, cache cleanup is forced, least used\nentries removed first.\n\nI recommend to set this value to at least 3/4 of total objects in your database\n(including all tables, sequences, views, data rows and other objects, browsable\nwith this program), which is about 60% cache hits (~45% for 1/2 and ~56% for\n2/3). But this is just a basic recommendation based on educated guess and some\ntests with \"entry\" names generated with normally distributed random generator.\nExperiment is your best advisor in this case.\n\nFor \"file\" strategy it means min entry size in bytes to store on disk (caches\nsimple files only for now, dirs/symlinks and the like are not cached, which is\nok in most cases). If file size is smaller then given size, then it is stored\nin memory. Useful if you are going to review big chucks of data in your\ndatabase, e.g. large blobs etc.\n\nCommon advice: set C\u003c--cache-limit\u003e above zero and L\u003c--cache|/--cache, -c\u003e to\nanything but \"memory\" only if you really have low memory issues with the\nprogram, as all other cache strategies are slower than simple memory access.\n\"Limited\" cache method has to support additional structures to analyze data\nusage, and so it's slower than simple \"memory\" cache strategy, while \"file\"\ncache method has to check and update real files on your disk, so both of them\nare slower than simple \"memory\" caching (they're still faster than database\nrequests, however).\n\nSee also L\u003cFusqlFS::Cache\u003e, L\u003cFusqlFS::Cache::Base\u003e, L\u003cFusqlFS::Cache::File\u003e\nand L\u003cFusqlFS::Cache::Limited\u003e for detailed description of cache strategies.\n\n=item B\u003c--format, -f\u003e\n\nFormat used to output different text data, like rows, columns description etc.\nCan be \"xml\", \"json\", \"yaml\", \"html\", \"htmltable\" or \"native\" for now, defaults\nto \"native\".\n\nNote a special case of \"native\" format: it doesn't encode data into any\nspecific text-based format, instead it preserves inner Perl structures. The\neffect is all formatted files are represented as directories, each field value\nbeing regular file with data. For details see L\u003cFusqlFS::Formatter::Native\u003e.\n\nOther special formats are \"html\" and \"htmltable\". They are dump-only formats,\nthey produce HTML output (HTML lists for \"html\" or tables for \"htmltable\") but\ndon't parse this format back into Perl structures, so you can't edit and save\ndatabase data while using these formats. For details see\nL\u003cFusqlFS::Formatter::Html\u003e and L\u003cFusqlFS::Formatter::Htmltable\u003e.\n\nFor writing your own formatters see L\u003cFusqlFS::Formatter\u003e.\n\n=back\n\n=head2 Boolean options\n\n=over\n\n=item B\u003c--innodb\u003e\n\nBoolean, MySQL specific. If set, new tables created by the program use InnoDB\nbackend, MyISAM is used otherwise. Defaults to false (MyISAM).\n\n=item B\u003c--debug, -D\u003e\n\nIncremental, output debug info. You can repeat this option up to five times.\nThere're following debug levels:\n\n=over\n\n=item 1. show critical DB errors,\n\n=item 2. show DB warnings as well,\n\n=item 3. show full SQL statements which caused errors,\n\n=item 4. show full stack trace on errors,\n\n=item 5. show FUSE debug tracing output (really noisy).\n\n=back\n\nDefault is no debug messages. See also L\u003c--logfile|/--logfile, -l\u003e to enable\ndebug output logging in daemon mode. If you don't set logfile in daemon mode\nyou won't see any debug output, no matter how many C\u003c-D\u003es you put in command\nline.\n\n=item B\u003c--daemon\u003e\n\nBoolean, if set the program will daemonize itself. Defaults to true. You may\nwish to use it as C\u003c--nodeamon\u003e to debug the program.\n\n=item B\u003c--mkdir, -k\u003e\n\nBoolean, if set the program will try to create mountpoint directory if it doesn't\nexist yet. Default is false.\n\n=item B\u003c--rmdir, -K\u003e\n\nBoolean, if set the program will try to remove mountpoint directory after exit.\nDefault is false.\n\n=back\n\n=head2 Store options into configuration files\n\nFusqlFS leverages L\u003cGetopt::ArgvFile\u003e package to load configuration from files.\n\nLong story short, you can put C\u003c@filename\u003e on command line, it will interpolate\ncontents of the file into command line. You can place as many @-clauses into\ncommand line as you want. This way you can store some common options into a\nfile and use it in C\u003cfusqlfs\u003e invocation. For instance, you can place\ncredentials and database name into F\u003cdatabaserc\u003e file and then just call\nC\u003cfusqlfs @databaserc\u003e to mount it.\n\nAs an alternative to @-prefix you can use C\u003c-r\u003e option instead to load\nconfiguration from given file, so you can write C\u003c-r filename\u003e instead\nof C\u003c@filename\u003e. This is useful to put into shebang line in fusqlfs config\nfile:\n\n    #!/usr/bin/fusqlfs -r\n    --user=root\n    --password=pa$$w0rd\n    --host=localhost\n    --engine=mysql\n\nThen you need to give execute permission to the config file with C\u003cchmod a+x\u003e\nand run it directly from anywhere.\n\n=head1 DESCRIPTION\n\nThis FUSE-daemon allows to mount any DB as a simple filesystem. Unlike other\nsimilar \"sqlfs\" filesystem, it doesn't provide simple DB-backed file storage,\nbut given you full interface to all database internals.\n\nEvery table, view, function etc. is a directory, every single field, index,\nrecord etc. is a file, symlink or subdirectory in the mounted filesystem. You\ncan create table \"mkdir ./mnt/tables/tablename\", and remove them with \"rmdir\"\nafterwards. You can edit fields as simple YAML-files. All your usual file\nutilities are at your service including \"find\", \"rm\", \"ln\", \"mv\", \"cp\" etc.\n\nJust mount your DB and enjoy!\n\n=head1 TODO\n\n=over\n\n=item * Implement MySQL support.\n\n=item * Implement PgSQL triggers.\n\n=item * Write better docs: describe FS structure, rules and precautions to use\nit as DB admin tool.\n\n=back\n\n=head1 AUTHOR\n\nE\u003ccopy\u003e 2010, Konstantin Stepanov E\u003clt\u003eI\u003cmailto:me@kstep.me\u003eE\u003cgt\u003e\n\n=head1 LICENSE\n\nThis product is distributed AS IS without any warrantly under General Public\nLicense v.3 or higher in hope it will be useful for somebody.\n\nLicense text is included in F\u003cLICENSE\u003e file in this distribution.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkstep%2Ffusqlfs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkstep%2Ffusqlfs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkstep%2Ffusqlfs/lists"}