Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/pingcap/activerecord-tidb-adapter
TiDB adapter for ActiveRecord, allows the use of TiDB as a backend for ActiveRecord and Rails apps.
https://github.com/pingcap/activerecord-tidb-adapter
activerecord mysql rails tidb
Last synced: 11 days ago
JSON representation
TiDB adapter for ActiveRecord, allows the use of TiDB as a backend for ActiveRecord and Rails apps.
- Host: GitHub
- URL: https://github.com/pingcap/activerecord-tidb-adapter
- Owner: pingcap
- License: apache-2.0
- Created: 2021-08-04T06:16:26.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2023-09-05T11:12:51.000Z (about 1 year ago)
- Last Synced: 2024-08-17T09:52:07.665Z (3 months ago)
- Topics: activerecord, mysql, rails, tidb
- Language: Ruby
- Homepage:
- Size: 124 KB
- Stars: 24
- Watchers: 31
- Forks: 4
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# ActiveRecord TiDB Adapter
[](https://badge.fury.io/rb/activerecord-tidb-adapter)
[](https://github.com/pingcap/activerecord-tidb-adapter/actions/workflows/ci.yml)
⚠️ This Gem is not currently maintained. If you're looking to connect to TiDB serverless with a Rails application, follow our [TiDB serverless ruby connect example](https://github.com/hooopo/tidb-serverless-ruby-connect-example)
⚠️ Since this Gem is a solution for the compatibility issues left by the older versions (prior to 6.0) of TiDB, TiDB Cloud and TiDB serverless will always use the latest versions, so there is no need for additional adapters for integration. You can directly use ActiveRecord or the mysql2 gem.
------
TiDB adapter for ActiveRecord 5.2, 6.1 and 7.0
This is a lightweight extension of the mysql2 adapter that establishes compatibility with [TiDB](https://github.com/pingcap/tidb).
## Installation
Add this line to your application's Gemfile:
```ruby
gem 'activerecord-tidb-adapter', '~> 7.0.0'
```
If you're using Rails 5.2, use the 5.2.x versions of this gem.
If you're using Rails 6.1, use the 6.1.x versions of this gem.
If you're using Rails 7.0, use the 7.0.x versions of this gem.
And then execute:
$ bundle install
Or install it yourself as:
$ gem install activerecord-tidb-adapter
## Usage
config/database.yml
```yml
default: &default
adapter: tidb
encoding: utf8mb4
collation: utf8mb4_general_ci
pool: <%= ENV.fetch("RAILS_MAX_THREADS") { 5 } %>
host: 127.0.0.1
port: 4000
variables:
tidb_enable_noop_functions: ON
username: root
password:
development:
<<: *default
database: activerecord_tidb_adapter_demo_development
```
* demo repo with rails 6.1.4: https://github.com/hooopo/activerecord-tidb-adapter-demo
## TiDB features
**[Sequence](https://docs.pingcap.com/tidb/stable/sql-statement-create-sequence)**
Sequence as primary key
```ruby
class TestSeq < ActiveRecord::Migration[6.1]
def up
# more options: increment, min_value, cycle, cache
create_sequence :orders_seq, start: 1024
create_table :orders, id: false do |t|
t.primary_key :id, default: -> { "nextval(orders_seq)" }
t.string :name
end
end
def down
drop_table :orders
drop_sequence :orders_seq
end
end
```
This gem also adds a few helpers to interact with `SEQUENCE`
```ruby
# Advance sequence and return new value
ActiveRecord::Base.nextval("numbers")
# Return value most recently obtained with nextval for specified sequence.
ActiveRecord::Base.lastval("numbers")
# Set sequence's current value
ActiveRecord::Base.setval("numbers", 1234)
```
**[CTE](https://docs.pingcap.com/tidb/dev/sql-statement-with#with)**
```bash
$ bundle add activerecord-cte
```
```ruby
require 'activerecord/cte'
Post
.with(posts_with_tags: "SELECT * FROM posts WHERE tags_count > 0")
.from("posts_with_tags AS posts")
# WITH posts_with_tags AS (
# SELECT * FROM posts WHERE (tags_count > 0)
# )
# SELECT * FROM posts_with_tags AS posts
Post
.with(posts_with_tags: "SELECT * FROM posts WHERE tags_count > 0")
.from("posts_with_tags AS posts")
.count
# WITH posts_with_tags AS (
# SELECT * FROM posts WHERE (tags_count > 0)
# )
# SELECT COUNT(*) FROM posts_with_tags AS posts
Post
.with(posts_with_tags: Post.where("tags_count > 0"))
.from("posts_with_tags AS posts")
.count
```
## Setting up local TiDB server
Install [tiup](https://github.com/pingcap/tiup)
```shell
$ curl --proto '=https' --tlsv1.2 -sSf https://tiup-mirrors.pingcap.com/install.sh | sh
```
Starting TiDB playground
```shell
$ tiup playground nightly
```
## Tutorials
* [Build a Rails App with TiDB and the ActiveRecord TiDB Adapter](https://gist.github.com/hooopo/83db933ab07a054f70e23da0ff945747)
## Development
After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
## Testing
install gems
```
bundle install
```
start tidb server
```
tiup playground nightly
```
create database for testing
```
MYSQL_USER=root MYSQL_HOST=127.0.0.1 MYSQL_PORT=4000 tidb=1 ARCONN=tidb bundle exec rake db:tidb:rebuild
```
run tidb adapter tests and activerecord buildin tests
```
MYSQL_USER=root MYSQL_HOST=127.0.0.1 MYSQL_PORT=4000 tidb=1 ARCONN=tidb bundle exec rake test:tidb
```
run **ONLY** tidb adapter tests using `ONLY_TEST_TIDB` env:
```
ONLY_TEST_TIDB=1 MYSQL_USER=root MYSQL_HOST=127.0.0.1 MYSQL_PORT=4000 tidb=1 ARCONN=tidb bundle exec rake test:tidb
```
## Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/pingcap/activerecord-tidb-adapter.
## License
Apache 2.0