mirror of
https://github.com/MariaDB/server.git
synced 2026-10-23 18:49:29 +03:00
243058f5e0
This adds a shell script that lets users keep using their existing
mariadb-backup commands while the real work is done by the new
server-side BACKUP SERVER command. The goal is "drop-in": users
should not have to change their backup scripts.
mariadb-backup-server.sh : Understands the usual mariadb-backup
modes and translates each one.
mbstream-server.sh : lets streamed backups be unpacked by
pipelines that expect the mbstream CLI
mariadb-backup-pipe.sh is the stream sink that
BACKUP SERVER itself runs.
All three are documented in README.md.
--backup
========
Connects with the mariadb client and runs
"BACKUP SERVER TO '<dir>'".
Connection options (--user, --host, --port, --socket,
--defaults-file, ssl, ...) are passed through to the client.
--parallel=N becomes "<N+1> CONCURRENT": mariadb-backup
runs a dedicated log_copying_thread() besides its N data-copy
threads, while CONCURRENT counts every BACKUP SERVER worker.
The result is clamped to the 1..256 the parser accepts,
and to a minimum of 2.
After the backup it writes backup-prepare.cnf into the backup
directory, recording what --prepare needs later:
- where mariadbd lives
- InnoDB parameters (page size, data file path, undo tablespaces,
checksum algorithm, log file size)
- If the server is encrypted then how to reload the
encryption key plugin (the file_key_management variables),
so an encrypted backup can be prepared without extra input.
--backup --stream
=================
Runs "BACKUP SERVER WITH 'pipe'".
The server only accepts a bare command name, which it resolves
n the PATH of the mariadbd process after prepending mariadb-backup-,
so uses the installed mariadb-backup-pipe instead.
mariadb-backup-pipe writes the tar into
.mariadb-backup-pipe-<stream>.tar, a named pipe the wrapper
created in the server @@datadir and is already draining to
its own stdout.
The backup therefore reaches the consumer as it is produced and
never lands on local disk. The wrapper appends backup-prepare.cnf
as a final tar afterwards; the server's tar carries no
end-of-archive marker, so that trailing archive supplies the
only one and the whole stream extracts with a plain "tar -x".
--parallel is ignored here, with a warning.
Four properties follow from how BACKUP SERVER streams,
all differing from mariadb-backup:
- local: the stream command runs inside the server,
so the wrapper must share its filesystem;
- fifo lives in @@datadir, because mariadb-backup-pipe resolves it
relative to the working directory of mariadbd, so --stream needs
write access there;
- tar only: any --stream=<format> yields tar;
- single-threaded: one worker, so no parallel read either.
--target-dir is optional in stream mode;
mbstream-server.sh maps the mbstream CLI onto a plain
"tar -x"/"tar -c", so existing "mbstream -x"/"-c" pipelines
keep working on the wrapper's stream.
mbstream-only flags (-p/--parallel, ...) are accepted and
ignored; any other unknown option is rejected.
Environment overrides:
MARIADB (client),
MARIADBD (the --prepare bootstrap server) and
TAR (the tar implementation, e.g. TAR=bsdtar) can each be overridden.
To run the bootstrap under rr, put it in MARIADBD and
let rr's own _RR_TRACE_DIR choose the trace location, e.g.
_RR_TRACE_DIR=/dev/shm/rr MARIADBD='rr record mariadbd'
--prepare
=========
Starts "mariadbd --bootstrap" on the backup directory using
backup-prepare.cnf as its defaults file, replays the archived redo
log between the start and target LSN read from backup.cnf,
then builds a fresh ib_logfile0 so a normal server can start
on the directory.
mariadbd is taken from the path recorded in backup-prepare.cnf
if that binary exists, otherwise by searching
/libexec, /sbin, /bin and the configured install directories.
PATH is not searched; set MARIADBD to point elsewhere.
User --defaults-file/-extra-file and encryption options are
layered onto the bootstrap.
--copy-back / --move-back
=========================
Copy or move a prepared backup into the datadir. The datadir
is created if missing, a non-empty datadir is refused unless
--force-non-empty-directories is given, and a chown
reminder is printed.
If --aria-log-dir-path is given, the Aria logs (aria_log_control,
aria_log.*) are relocated into that directory.
Packaging
=========
The wrapper is not installed by default and never replaces the
real mariadb-backup / mbstream binaries.
1. cmake -DWITH_MARIABACKUP_WRAPPER=ON (default OFF) controls it.
2. When ON, the scripts install as /usr/bin/mariadb-backup-server,
/usr/bin/mbstream-server and /usr/bin/mariadb-backup-pipe, tagged
COMPONENT Backup so they ship in the mariadb-backup package.
mariadb-backup-pipe must end up in the PATH of the mariadbd
process, not merely in the PATH of whoever runs the wrapper.
3. RPM: nothing extra to do. the component handles it.
4. DEB: not wired. debian/rules uses --fail-missing and does not
enable the option, so the -server binaries are not listed.
To ship via DEB, make a paired change: add
-DWITH_MARIABACKUP_WRAPPER=ON in debian/rules and list all three of
usr/bin/mariadb-backup-server, usr/bin/mbstream-server and
usr/bin/mariadb-backup-pipe in debian/mariadb-backup.install together.
5. The real mariadb-backup/mbstream binaries and the
mariabackup symlink are left untouched; opt in via an alias or a
symlink early in PATH.
Limitations (not supported yet)
===============================
1) Incremental backup & prepare (--incremental-basedir,
--incremental-dir, --apply-log-only)
2) --rollback-xa
3) Partial backup (--databases, --tables, --tables-file)
4) Output compression and encryption (--compress, --encrypt)
5) --export is accepted but only warns and runs a plain recovery
6) --extra-lsndir is ignored
7) --parallel is ignored with --stream
8) Windows: POSIX sh only, not installed on Windows
Behaviour differences from native mariadb-backup
================================================
- The wrapper needs the mariadb client on PATH for --backup;
--prepare needs mariadbd recorded in backup-prepare.cnf, in a
standard install directory, or named by MARIADBD
- BACKUP SERVER refuses an already-existing target directory
- BACKUP SERVER does copy the data file as raw pages without
checksum validation, so a corrupted table is not detected
at backup time
- --prepare only works on a wrapper-made backup: it
needs backup-prepare.cnf
- --stream is tar, not xbstream, local-only and single-threaded,
and needs write access to @@datadir for the fifo
Tests
=====
include/have_mariabackup_wrapper.inc redirects $XTRABACKUP to
mariadb-backup-server.sh and $XBSTREAM to mbstream-server.sh,
skipping when a wrapper or the mariadb client is unavailable.
include/have_mariabackup_combination.inc runs a test under both the
[CLIENT] mariadb-backup binary and the [SERVER] wrapper.
MariaDB Server
MariaDB Server is one of the most widely deployed open source relational databases. It is built by a global community of contributors together with the MariaDB Foundation and MariaDB plc, and it powers workloads from small applications to large-scale production systems.
MariaDB began as a fork of MySQL, led by the original MySQL developers, and it maintains a high degree of MySQL compatibility. It has since grown into a database with its own capabilities, including native vector search, multiple pluggable storage engines, synchronous clustering, and analytical features, while remaining a straightforward migration target for existing MySQL deployments.
Key features
- Native vector search. A built-in VECTOR data type with approximate nearest-neighbour indexing (HNSW), available since MariaDB 11.8 with no extension required.
- Pluggable storage engines. InnoDB (default for transactional workloads), Aria, MyRocks, ColumnStore for analytics, Spider for sharding, and S3 for archival, among others.
- Replication and clustering. Asynchronous, semi-synchronous, and parallel replication with global transaction IDs, plus Galera synchronous multi-primary clustering.
- Advanced SQL. Common table expressions and recursive CTEs, window functions, system-versioned (temporal) tables, sequences, and a broad set of JSON functions.
- MySQL and Oracle compatibility. Wire-protocol and syntax compatibility with MySQL, plus an Oracle SQL mode supporting PL/SQL-style stored routines.
- Spatial and full-text search. GIS data types and functions, and built-in full-text indexing.
- Security. Role-based access control, pluggable authentication (ed25519, PAM, GSSAPI, and more), data-at-rest encryption, and TLS for connections.
Documentation
- Project home, community, and getting involved
- Reference manual and release notes
- MariaDB compared to MySQL
Releases
MariaDB Server follows a yearly long-term support (LTS) model alongside quarterly rolling releases. Binary LTS releases are maintained for three years and are recommended for production; rolling releases deliver new features sooner with a shorter support window.
For the current version and full history, see Releases and the MariaDB release calendar.
Installing
Packages and installation instructions for all supported platforms are available at https://mariadb.org/download/.
Building from source
To build MariaDB from source and run the test suite, follow the developer guide
It covers building the code correctly, running the MariaDB testing framework, and choosing the right branch to target for contributions.
Contributing
Contributions are welcome, from code and documentation to bug reports and reviews. See CONTRIBUTING.md to get started, and CODING_STANDARDS.md for code style. Contributors and community members are recognised in CREDITS.
Getting help
- Zulip chat
- Maria Discuss mailing list
- Bug reports
- Security vulnerabilities: see SECURITY.md
Licensing
MariaDB Server is licensed under version 2 of the GNU General Public License (GPLv2), without the "any later version" clause. This is inherited from MySQL. License information is in the COPYING file, and third-party license information is in the THIRDPARTY file.
About MariaDB Foundation
MariaDB is brought to you by the MariaDB Foundation and MariaDB plc. The MariaDB Foundation is the custodian of the MariaDB Server codebase, ensuring it stays open and that anyone can contribute. See CREDITS for details on the Foundation and the people developing MariaDB.
MySQL, the base of MariaDB, is a product and trademark of Oracle Corporation, Inc.