logo Dartabase Migration GUI GUIDE

Serverside Database migration for simple version controlled database structure manipulation using MySQL/PGSQL without having to write SQL

combine the power of Dartabase Model and Dartabase Migration

!!now supporting scaffolding!! see bottom of the page

inspired by Ruby on Rails

Tested on

Dart SDK version 1.16.0

Uses Polymer version "^1.0.0-rc.16" MYSQL via sqljocky "^0.14.1"

PGSQL via postgresql version "^0.3.3"


###WIKI 1.How to setup 2.How to update existing dartabase migration version 3.How to create migrations 4.How to run migrations 5.How to revert migrations 6.How to generate backend code from database 7.How to run generated backend code About column id About create updated at column About up and down About order of execution About dartabase data types


####Dartabase Documentation 1.Dartabase Migration - How to install and use - current

2.Dartabase Model - How to how to install and use

####Dartabase Tutorials 1.How to create a Dartabase supported app from scratch

2.How to create a Dartabase supported app for an existing database


1. HOW TO SETUP <a name="how-to-setup"></a>

USE THIS INSTALL GUIDE AND IGNORE THE INSTALL PAGE!!! This is a stand alone app!

1.Download dartabase_migration somewhere to your drive

2.run 'Pub Get' on dartabase_migration/pubspec.yaml

3.Execute dartabase_migration/bin/simpleServer.dart

4.Execute dartabase_migration/tool/index.html which will open in chromeium

now you should see page with a button

one

5.click on add project, now you should see

one

6.fill in the form and click enhance or create

one

7.after reload you should see the created object

one

8.dartabase_migration will create files and folders below to do its magic

  dartabase_migration/bin/projectsMapping.json       
    -maps project names to absolute project path
  yourProject/db/
  yourProject/db/config.json          
    -dartabase config file to connect IP/PORT/DBType
  yourProject/db/schema.json          
    -current dartabase_migration structure as JSON used by Dartabase tools
  yourProject/db/schemaVersion.json   
    -safes name of latest migrated version
  yourProject/db/migrations           
    -folder for your database migration files

9.IMPORTANT if your config data is not correct it might be that dartabase will stop running

in this case make sure to insert the correct data into the config.json file created in your project -yourProject/db/config.json file so dartabase_migration can connect to your existing database. and rerun simpleServer.dart and index.html

eg.
--------config.json---------
{
    "adapter": "MySQL",
    "database": "dbName",
    "username": "dbUsername",
    "password": "dbPassword",
    "host": "localhost",
    "port": "3306",
    "ssl": "false"
}
----------------------------


2. HOW TO UPDATE EXISTING DARTABASE MIGRATION VERSION <a name="how-to-update-dartabase-migration"></a>

GENEREL UPDATE

it is important to keep a backup of 'dartabase_migration/bin/projectsMapping.json'

1.download the new version of dartabase migration 

2a.replace all files from your current running version 
  (but not projectsMapping.json)
2b. extract all files into a new folder and paste a copy of bin/projectsMapping.json

LOST 'projectsMapping.json' DONT PAN!C

1.create a file named projectsMapping.json inside 'dartabase_migration/bin/'
  
  inside the file enter a json key value pair of a projectname of your choice
  
      keys    : project_names (your choice/short is good ;)
      values  : project absolute project path
  
  eg.
  {
     "mysql":"C:\\myServer",
     "pgsql":"C:\\pgServer"
  }

MOVED/RENAMED project

Rename the values when moving/renaming one of your projects
  

now you should be able to find your projects again when running dbUp or dbDown


3. HOW TO CREATE MIGRATIONS <a name="how-to-create-migrations"></a>

  1. select the project you want to create a migration for

one

  1. open the "create migration" view, enter a migration name and click on the action you want to execute

one

createTable

one

enter a table name and additional columns if needed like seen below

one

createColumn

one

select an existing table name and add additional columns like seen below

one removeColumn

one

select an existing table and the existing column you want to remove, like below

one

removeTable

one

select an existing table you want to remove, like below

one

createRelation

one

select two existing tables to create a relation between them like below

one

removeRelation

one

select two existing tables to create a relation between them like below

one

click on "create migration"

it will create a migration inside

"$yourProject/db/migrations/YYYYMMTTHHMMSS_migration_name.json"

if everything works it will show a text mesage inside a toast that asks you to reload the page

one


4. HOW TO RUN MIGRATIONS <a name="how-to-run-migrations"></a>

1 . open the run migration view

one

2 . select the preferred migration that is newer than the one marked as current. in this case version 1

one

3 . now click on "migrate to newer version".

one

dartabase_migration should have executed the actions specified inside the "UP" key for all files INCLUDING the goal migration version.

Additionally it will update

-yourProject/db/schema.json
with the current database structure as JSON

-yourProject/db/schemaVersion.json
with the name of latest migrated migration file

5. HOW TO REVERT MIGRATIONS <a name="how-to-revert-migrations"></a>

1 . open the run migration view

one

2 . select the preferred migration that is older than the one marked as current. in this case version 1

one

3 . now click on "migrate to older version".

one

dartabase_migration should have executed the actions specified inside the "DOWN" key for all files EXCLUDING the goal migration version.

Additionally it will update

-yourProject/db/schema.json
with the current database structure as JSON

-yourProject/db/schemaVersion.json
with the name of latest migrated migration file

6. HOW TO generate backend code from database <a name="how-to-generate-backend-code-from-db"></a>


7. HOW TO run generate backend code <a name="how-to-run-generate-backend-code"></a>


ABOUT COLUMN ID <a name="about-column-id"></a>

The 'id' column will be generated by 'Dartabase Migration' for every table as primary key.

Dont add 'id' in any of the migration files.

This is to let 'Dartabase Model' decide when to create or update an Object on save() - see Dartabase Model


ABOUT CREATED/UPDATED AT COLUMN <a name="about-create-updated-at-column"></a>

For each table a created_at and updated_at column will be generated automatically.

created_at 
  will only be set to current datetime on creation of table row entry 

updated_at 
  will be set to current datetime on creation of table row entry
  PGSQL
    will be updated when the row has been saved
  MySQL
    will be updated when the row has been saved and a value of the row changed 
     

ABOUT UP AND DOWN <a name="about-up-and-down"></a>

Additionally to the "UP" key, migration automatically generates the opposite migration for reverting inside the "DOWN" key

actions inside "UP" are executed during migration
actions inside "DOWN" are executed when reverting migrations

since we created a table named "user", we might want to remove it once we want to revert the migration

!!!ATTENTION be sure your don't need the data inside a table/column 
before you remove it!!!

ABOUT ORDER OF EXECUTION <a name="about-order-of-execution"></a>

Once you have more than one action in the migration file

eg.
  adding a column
  adding a table
  removing a column

remember that the order of execution inside a migration will be

createTable
 ->
 createColumn
  ->
  removeColumn
   ->
   createRelation
    ->
    removeRelation
     ->
     removeTable

its always best to keep migration files as simple as possible and therefore create more migration files


ABOUT DARTABASE DATA TYPES <a name="about-dartabase-data-types"></a>

dartabase_migration types are Specified in capitals.

on the left hand you see the dartabase_migration data type name on the right the data type your database will use

####MYSQL

{
  "BINT": "BIGINT",
  "BINT UNSIGNED": "BIGINT UNSIGNED",
  "BINARY": "BINARY",
  "BIT": "BIT",
  "BLOB": "BLOB",
  "BOOLEAN": "BOOLEAN",
  "BYTEARRAY": "BLOB",
  "CHAR": "CHAR(255)",
  "DATE": "DATE",
  "DATETIME": "DATETIME",
  "DOUBLE": "DOUBLE",
  "FLOAT": "FLOAT(2)",
  "FLOAT UNSIGNED": "FLOAT(2) UNSIGNED",
  "INT": "INT",
  "INT": "INT",
  "INT UNSIGNED": "INT UNSIGNED",
  "LBLOB": "LONGBLOB",
  "LTEXT": "LONGTEXT",
  "MBLOB": "MEDIUMBLOB",
  "MINT": "MEDIUMINT",
  "MINT UNSIGNED": "MEDIUMINT UNSIGNED",
  "MTEXT": "MEDIUMTEXT",
  "SINT": "SMALLINT",
  "SINT UNSIGNED": "SMALLINT UNSIGNED",
  "TEXT": "TEXT",
  "TIME": "TIME",
  "TIMESTAMP": "TIMESTAMP",
  "TBLOB": "TINYBLOB",
  "TINT": "TINYINT",
  "TINT UNSIGNED": "TINYINT UNSIGNED",
  "TTEXT": "TINYTEXT",
  "VARBINARY": "VARBINARY(255)",
  "VARCHAR": "VARCHAR(255)"

}

PGSQL

{
  "BINT": "bigint",
  "BINT UNSIGNED": "numeric(20)",
  "BINARY": "bytea",
  "BIT": "bytea",
  "BLOB": "bytea",
  "BOOLEAN": "boolean",
  "BYTEARRAY": "bytea",
  "CHAR": "char(255)",
  "DATE": "date",
  "DATETIME": "timestamp",
  "DOUBLE": "double precision",
  "FLOAT": "real",
  "FLOAT UNSIGNED": "real",
  "INT": "integer",
  "INT UNSIGNED": "bigint",
  "LBLOB": "bytea",
  "LTEXT": "text",
  "MBLOB": "bytea",
  "MINT": "integer",
  "MINT UNSIGNED": "integer",
  "MTEXT": "text",
  "SINT": "smallint",
  "SINT UNSIGNED": "integer",
  "TEXT": "text",
  "TIME": "time",
  "TIMESTAMP": "timestamp",
  "TBLOB": "bytea",
  "TINT": "smallint",
  "TINT UNSIGNED": "smallint",
  "TTEXT": "text",
  "VARBINARY": "bytea",
  "VARCHAR": "varchar(255)"

}


###TODO

*workaround for database problems with reserved words
 on creation or when switching DBAdapter from PG to MY.
    eg. table name 'user' will break in MySQL
    fix -> add '_' as prefix to all column and table names
*test on other systems
*adding rename action
*adding option to specify variable length
    currently VARCHAR fix at 255
*test functionality of all data types
*and much more

Please let me know about bugs you find and or improvements/features you would like to see in future.

ENJOY & BE NICE ;)

Libraries

dartabase_migration